Understanding the CICS environment from Application Program

          CICS provides different set of APIs for providing the environment information to the application programmer. As a CICS application programmer, understanding the environment under which the program will run is very important. TXSeries for Multiplatforms supports most widely used operating systems like AIX, SOLARIS, HP-UX, WINDOWS. It also provides better connectivity with CICS Transaction Server. Once the program is developed in one operating system, the same program can be used to run on any of the supporting platform and also the transaction/program containing the business logic can be invoked in different ways like a simple LINK, can be trigger transaction, asynchronously started transaction. Getting the environment in application programs provides application programmers to write the business logic in more effected way to run the business logic.
       
          For example, if an application program contains some functions specific to an operating system to perform some business logic, it might work properly in that particular operation system. Later if the same program is tried to run on different platform, it will fail. As a CICS application programmer, consider these issues while developing the application programs. Using the CICS APIs like EXEC CICS INQUIRE, get the operating system details and then validate and enclose such operating system specific functions calls for that operating system only.

          As an example, the following API can be used to get the operating system details from application program.

          EXEC CICS INQUIRE SYSTEM OPSYS(data-area)

        CICS returns a one-byte character that represents the type of operating system on which the transaction is currently running. The following values are returned:

         A represents CICS for AIX.
         H represents CICS for HP-UX.
         L represents CICS for Solaris.
         N represents CICS for Windows.

          Another example to know how the CICS application programs are invoked, as it can be invoked in different ways.

          EXEC CICS INQUIRE TASK STARTCODE(data-area)

   CICS returns upto a two-character value that indicates how this task started. Possible values are:

    D   The task was initiated to process a distributed programming link (DPL) command that did not specify the SYNCONRETURN option. (The task is not allowed to issue syncpoints.)
    DS  The task was initiated to process a distributed programming link (DPL) command that contains the SYNCONRETURN option. (The task is allowed to issue syncpoints.)
    QD  CICS initiated the task to process a transient data queue that had reached trigger level.
    S   Another task initiated this one, using a START command that did not pass data in the FROM option.
    SD  Another task initiated this one, using a START command that passed data in the FROM option.
    TO  The task was initiated to process unsolicited input from a terminal (or another system), and the transaction that is to be executed was determined from the input.
    TP  The task was initiated in response to a RETURN IMMEDIATE command in another task.
    U   CICS created the task internally.

          The following example will provide way to get the process ID from the application program for logging purpose. Even though user can use directly getpid system call, but its syntax is different for different operating systems.

Unix :
    header file: unistd.h
    pid_t getpid(void);

Usage:   printf("The process ID is %d.", getpid());

Windows :
    header file: process.h
    int _getpid(void);

Usage:   printf("The process ID is %d.", _getpid());
 

Instead of using system call directly, application programmer can use the CICS provided API options to get such type of information.

        EXEC CICS INQUIRE TASK PROCESSID(data-area)
       
    PROCESSID(data-area)
          CICS returns a 32-bit binary value that indicates the process ID of the process that is running the transaction that is associated with the task.

        TXSeries for Multiplatforms provides lot of information about the environment under which the application is invoked or running with EXEC CICS INQUIRE SYSTEM and EXEC CICS INQUIRE TASK APIs.

        For More information on the supported options for these APIs, please refer CICS API Command Reference.

Passing arguments to CICS Transactions

          Are you wondering how send the arguments for CICS Transactions. There will be many cases when user wants to call specific logic in the application code based on particular condition. Writing separate programs for each condition and defining separate transaction for each such program will be difficult for an application programmer. Using the power CICS APIs, CICS application programmer can send arguments for a transaction.

          TXSeries for Multi-platforms provides wide verity of CICS APIs. Using EXEC CICS RECEIVE API, user can read the data from terminal. As most of the terminals uses 24x80 screens, each line can have a maximum of 80 characters. Using EXEC CICS RECEIVE API, user can read the 80 characters as described in pseudo code. After reading, user needs to parse the character string based on requirement. The first four characters contains the transaction name. User can use the remaining 75 characters to pass the character arguments for the transaction.

void main (void)
{
     cics_char_t TextBuffer [80];
     cics_sshort_t TextLength = 80;
     memset(TextBuffer, ' ', 79);
     TextBuffer [79] = '\0';

     EXEC CICS RECEIVE
               INTO(Text_Buffer)
               LENGTH(TextLength);

     /* Read the Trasaction character arguments */
     /* 01234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 */
     /* SAMP 1*/                  /* SAMP is the transaction and '1' is the argument */
     /* SAMP 2*/                  /* SAMP is the transaction and '2' is the argument */
     /* SAMP 3*/                  /* SAMP is the transaction and '3' is the argument */
     /* SAMP 111 2 33*/          

     if (Text_Buffer [4]  != ' ')
           print(Error Message/Usage)
     switch(Text_Buffer [5])
     {
           case '1' :  Business Logic 1;
                       break;
           case '2' :  Business Logic 2;
                       break;
           case '3' :  Business Logic 3;
                       break;
           .
           .
           .
           .   
           Default  :  Business Logic ;
                       break;         
     }
  //     Business Logic   //
}

     User can also pass multiple arguments to the transaction using some delimiter. But in application program it needs to be parsed based on the delimiter or by using some tokenizing techniques.

Region attach at RegionPoolBase may fail when SafetyLevel is set to normal

Setting SafetyLevel=normal can cause cicsas failure in scenarios where a library or application loaded in the cicsas executes shmat call with shmaddr set to NULL.

Reason:
When you set the SafetyLevel to normal in the RD.stanza, the region attaches and detaches itself at the address specified in RegionPoolBase attribute of RD.stanza with every cics api call. If shmat is used in the application program or in other products (like DB2 or MQ or any other product whose library gets loaded into the cicsas memory) which is being used in conjunction with TXSeries for attaching to the shared memory and passes NULL as a second argument (shmaddr) for shmat, the shared memory is attached at the first available address as selected by the Operating System.
It is possible that the Operating System can assign the same address as RegionPoolBase address. So, the next time when the TXSeries region tries to attach to the address specified in RD.stanza for RegionPoolBase, it fails with EINVAL.

Symptom:
The following message gets recorded in symrecs file:


SYMPTOMS = TIME/"09/22/10 12:37:08.927364556" REGION/TEST PROD/5724AX710 LVLS/710 MOD/"@(#)conco, 17:23:35, Jul 27 2010" FUNC/ConCO_WaitForAnyAMChild LINE/676 MS/010089 MSN/367 SRC/2 PRCS/0 ABCODE/ SRVID/5 PID/1437874 TID/7 PROC/cicsam
SECONDARY SYMPTOMS = Child(PID 250074) returned with exit value 6

Solution:
Set SafetyLevel=none in this scenario, which will make the cicsas to remain attached to the region pool throughout the lifetime of the cicsas.

Automating TXSeries with Mainframe

Like we saw how to send emails from TXSeries, we can also do several things on mainframe viz. Starting a CICS region, Uploading and Compiling programs etc.

First you need to have an extrapartition TDQ defined in TXSeries. This TDQ output should be redirected to ksh.

With Mainframe we can talk over ftp using the QUOTE command and with filetype=jes. When filetype=JES is set, whatever you upload, is submitted to the JES system as the JCL. On other hands when download (GET) command is used in this JES mode, the job output can be retrieved from mainframe. We will see some example FTP sessions for various tasks on mainframe.

1) Creating a PDS (submitting a JCL to create a PDS)
MFUSER=KAILAS
MFPASS=mypasswd
cat > temp.jcl << EOFJCL
//${MFUSER}1 JOB A1,'${MFUSER}',CLASS=A,MSGCLASS=H,MSGLEVEL=(1,1),
// NOTIFY=&SYSUID
//PERFS1 EXEC PGM=IEFBR14
//SYSPRINT DD SYSOUT=A
//SOURC DD UNIT=SYSDA,SPACE=(CYL,(10,5,10)),
// DSN=${MFUSER}.PERF.SOURCES,DISP=(NEW,CATLG,DELETE),
// DCB=(RECFM=FB,LRECL=80,BLKSIZE=8000)
//
EOFJCL
cat > temp.inp << EOFINP
user
${MFUSER} ${MFPASS}
prompt
quote site filetype=jes jesjobname=${MFUSER}* jesstatus=all jesowner=${MFUSER}
put temp.jcl
exit
EOFINP
ftp -n -v mainframeip < temp.inp

2) uploading a member to your PDS
cat > temp.inp << EOFINP
user
${MFUSER} ${MFPASS}
cd PERF.SOURCES
prompt
put PRFSRVIP
exit
EOFINP
ftp -n -v mainframeip <> NULL

3) Testing the status and results of JCL submitted and getting spool output to your local machine
cat > temp.inp << EOFINP
user
${MFUSER} ${MFPASS}
prompt
quote site filetype=jes jesjobname=${MFUSER}* jesstatus=all jesowner=${MFUSER}
dir ${JOBNO}
exit
EOFINP
STATUS="1"
until [[ $STATUS = "OUTPUT" ]] ; do
ftp -n -v mainframeip < temp.inp
STATUS=`grep ${JOBNO} NULL | awk '{print $4}'`
done

5) issuing operator commands using this technique
you can fire operator commands using following JCL
/*$VS,'S MYCICS1'
The command inside single quote is the command to be used on console

Notes:
1. JESINTERFACELVEL=2 should be set on the ftp server running in Mainframe.

Sending emails through TXSeries

Sending emails through TXSeries.

Often processing programs need to notify their results, status and events to users through emails. TXSeries is a transaction manager used widely to process transactions. Under TXSeries also we can achieve the functionality of sending emails using some Operating System techniques.

TXSeries has extrapartition TD Queues which can be used by programs to send emails to outside world. An Extrapartition TDQ is actually a flat file where records are logged. This flat file can be redirected to a smtp server using netcat command and thus emails can be sent by the programs running under TXSeries.

Below given is an example configuration to send mails.
1. Create an extrapartion TDQ in the region.
cicsadd -c tdd -r $REGION EMLS DestType=extrapartition ExtrapartitionFile=emails.txt RSLKey=public MaxSize=0 RecordLen=128

2. After starting the region use follwing command to send our mail commands from TXSeries program to smtp server:
tail -f emails.txt | nc your.smtphost.com 25
OR
tail -f emails.txt | netcat -h127.0.0.1 -p25

3. From the program WRITEQ TD cics api should be executed to output the text on the extrapartition file.
EXEC CICS WRITEQ TD QUEUE("EMLS") FROM(W-TEXT)

4. Above api will send 1 line of text in the output file. To send the email, we need to send the whole text given here:
HELO your.smtphost.com
MAIL FROM:
RCPT TO:
DATA
Mail Body (Status/Results)
.
QUIT

Keep doing point number 4 in a loop to send multiple mails.

invhariharan's blog: Ways to monitor a TXSeries (CICS) system

invhariharan's blog: Ways to monitor a TXSeries (CICS) system: "The CICS TS for the z environment has a rich set of monitoring tools available from both IBM and the third-party vendors. Though TXSeries (C..."

Renaming CICS Regions

Renaming a region in TXSeries is not as straightforward as renaming a folder on your desktop. The Region name is used in multiple places -As a prefix in creating sfs files, as an entry in the cicssrcdb ( Remember the subsystems blog ? ), the region environment file is created with its name etc..

So, if you do find yourself in a situation where you want to rename your region, there is a simple way to do so.
And no, there is NO "cicscp restart region blah blah ... "

Here is how you do it :

1) Navigate to CICSREGIONS directory which is /var/cics_regions on Unix systems and C:\var\cics_regions in Windows

2) Run the following command :
" cicsexport -r (Your Region Name) -o (Output File)"

Example : cicsexport -r Arena -o OutFile
This should ensure that an output file is created which contains all your region information. Now this regions is shippable to any other machine in a CICS understandable format.

3) Now Run this Command :
"cicsimport -r (New Region Name) -o (Output File) "

Example : "cicsimport -r ARENA -i OutFile"

Take Care that the file in -i option is the same file you created with cicsexport.

4) Now start your region using this command :
"cicscp start region ARENA StartType=cold"

Note : Did you notice that the region names are case sensitive? This might be a reason to rename your regions in case you want it to Communicate with a region on CICS on z/os.

You have now renamed your region! Good to go.

Rational Host Access Transformation Services(HATS) over TXSeries: Modernizing traditional

HATS transform the legacy 3270 and 5250 green screens into intuitive and rich web
applications which can be furthur exposed as WebServices. HATS does not only transform
applications into Web applications but they can be used to create mobile applications as
well.BMS maps functionality of TXSeries helps in creating applications in the form of these
legacy 3270 terminals. Rational HATS can be used to convert these into Webpages and hence
make these applications more user friendly.In order to make this conversion happen, consider we have a BMS map with certain input and output fields and which has been deployed over TXSeries.

In HATS, on creation of the new project one has to enter parameters like hostname, port number, Region name, TD entry etc to connect to the particular program and BMS map deployed in the TX region. Then using creation of macros and deploying them over the server the conversion of a 3270 terminal to a Webpage happens.

These webpages can be furthur tweeked and changes can be made in the properties to make them more interactive. Also a wsdl file gets created in the process which can then be used to create WebServices.

The use of green screens is no more appealing to people so on converting them to Webpages which is the trend of today, old applications can be converted with no code change.

Facing a problem in TXSeries… wondering what data to collect?

If only I had a tool that’d collect all the data that the product team wants from me to look at this problem…. Wishful thinking??? No. If you look around the utilities directory under the product install (/usr/lpp/cics/utils) you will find a tool called “cicsservice”.

“cicsservice” utility is meant to help automatically generate either the entire set of logs such as region logs, SFS logs, installed product information, intersystem communication information and so on. You could collect all the information at one go or selectively collect a set of information as well.

Prior to 7.1, usage of cicsservice tool was either to collect all data or interactively collect selective logs. With 7.1, a change has been made to use options to collect selective data non interactively. This can be quite handy, especially if you would like to involve this command in your customized scripts.

Some customers find that the size of output generated by cicsservice is high and gets hard to pass the data back to support teams. While selective data collection can help manage the size of data better, as a best practice you might want to archive older product logs, which will control the size of the data collected.

A generic tip on handling product logs : create separate file systems for storing your log files (dumps, trace etc.). This would ensure that even if the file system size hits the peak, region execution does not get affected.

Documentation on cicsservice can be found here, http://publib.boulder.ibm.com/infocenter/txformp/v7r1/index.jsp
TXSeries library can be found here, http://www-01.ibm.com/software/htp/cics/txseries/library/

TXSeries messages and codes ERZxxxxxx

Most of the time we are concerned about our application logic and we only check that our TXSeries transaction is running fine without any abend. We see many CICS message(ERZxxxxxx), but do we know what exactly the message is reporting us ??
Each CICS message has a significance attached to it. CICS Messages being displayed in TXSeries logs (like console, CSMT.out, CCIN.out etc) files are of format ERZxxxxxx.

Usually these CICS messages are of 3 types

1) Information messages: CICS Information messages are meant for user information purpose only. CICS Information message are of type ‘ERZxxxxxxI’. For example CICS message 'ERZ096176I'.

2) Warning message: CICS Warning messages are of format ‘ERZxxxxxxW’.CICS warning message indicate that some issue was seen while processing, but the transaction would continue execution. For example, CICS message 'ERZ004072W'.

3) Error message: CICS Error messages are of format 'ERZxxxxxxE'. CICS Error message indicates an abnormal condition while executing transaction. Usually transaction force purge or any abnormal condition in transaction leads to transaction being terminated by printing an error message in TXSeries log files. For example CICS message 'ERZ010014E'.

A CICS tool 'cicserr' provides information about CICS message codes.

cicserr can be used as cicserr [message_code].

For example
#cicserr ERZ096176I
ERZ096176I The Version is 'buffer!'
Explanation:
This message prints CICS Version information
System action:
Nothing.
User response:
Nothing

User response for the Information message would be nothing, as this message specific information. CICS users can check the 'User response' for warning and error messages and perform the necessary actions to debug the message.

invhariharan's blog: Java in a TXSeries environment

invhariharan's blog: Java in a TXSeries environment: "TXSeries being positioned as a transaction processing platform for traditional applications written on COBOL, C, C++, and PL/I. - predominan..."

invhariharan's blog: Smarter Migration of Oracle Tuxedo applications on...

invhariharan's blog: Smarter Migration of Oracle Tuxedo applications on...: "I guess moving Oracle Tuxedo based applications on to an IBM based platform is never going to be easier than using the newly released IMAT (..."

invhariharan's blog: Smarter Work Load Management Tool

invhariharan's blog: Smarter Work Load Management Tool: "I don't think that Work Load Management terms are anything new to us! There are loads of load balancing software tools available...These are..."

Clueless about CICS subsystems?

By now, I trust the concept of a "region" is a familiar one. If not, this might be a good place to start -> click

In brief, a region is that independent environment in which your applications run. This particular environment, when started, comes up with a set of properties that are defined in the "stanza" files. For more details on regions - how to start, stop etc, visit this link.

On AIX, each region runs as a subsystem. A subsystem is any program or process or set of programs or processes that is usually capable of operating independently or with a controlling system. A subsystem is designed as a unit to provide a designated function. 

Similarly, a region running on other platforms that TXSeries supports; such as Windows, Solaris or HP, need to emulate a subsystem.

The concept of "subsystems" is unique only to AIX, hence, when a region comes up in Solaris/HP, the process "cicsstart" sets up a subsytem-like environment. It uses the "cicssrcdb" file that is present in the cics_src directory in order to access dynamic information in order to bring up the region.

That's about subsystems and the cics Region. More on cicssrcdb related blogs later!

Understanding and configuring TXSeries SFS volumes.

Usually TXSeries users would configure TXSeries regions to meet their architecture requirements. But users miss to configure and tune SFS volumes (both data and log volumes). Whenever a default region (SFS Server as File Manager) is created in TXSeries, SFS Server with the hostname is also created with default settings. Default settings include SFS Log Volume size and SFS Server Data Volume size.

SFS Log Volume is used to store a SFS Servers log files. The data in this volume is used during recovery of transactions. The recovery data typically would include non-committed SFS Server data.

SFS Data Volume is used to store a SFS Severs application data. Committed data in SFS Server is stored in SFS Server’s data volume.


If the SFS Server fails to commit the data to data volume then the SFS log volume is used during the recovery process. Once the data is committed in data volume, entries in the log volumes are deleted. A typical setting of log volume size could be something like 100MB and data volume size as 2GB.

Steps to follow for configuring SFS Server’s volume size.

Before creating the SFS Server, understand how much log volume and data volume size is necessary for your architecture. In this example, im setting SFS log volume size as 128MB and SFS data volume size as 1GB.

a) Set the environment variable CICS_SFS_LOGICAL_PARTITION_SIZE to Physical partition size in the machine. Physical partition size can be obtained by running ‘lsvg rootvg’ command.
export CICS_SFS_LOGICAL_PARTITION_SIZE=64

b) Set the environment variable CICS_SFS_LOG_SIZE to 128MB . This environment variable takes input in MB
export CICS_SFS_LOG_SIZE=128

c) Set the environment variable CICS_SFS_DATA_SIZE to 1024 MB(1 GB). This environment variable takes input in MB
export CICS_SFS_DATA_SIZE=1024

For any further information on this, refer TXSeries Infocenter documentation.

TXSeries region migration within a machine

Recently I was trying to migrate a region in TXSeries 5.1 version to TXSeries 7.1 version. I found a webpage TXSeries link where the migration steps were clearly documented. So I wanted to write a blog about region migration.

Here in this link, the document also describes about migrating a TXSeries region from version 5.1 to 7.1 on a new machine. If you are migrating a region from TXSeries version 5.1 to 7.1 on a same machine, only step you would need to follow is to run the cicsmigrate command (Step 5 in the TXSeries link).

Run the command cicsmigrate on the region to create the upgrade script and then execute the generated upgrade script.


a) Create an upgrade script as follows:

# install_dir/bin/cicsmigrate -g script_name -o log_filename -r region_name

where:

install_dir is the directory where CICS is installed.

script_name is the full path name of the upgrade script. If we open this script file, we will be able to see CICS commands in this script. These CICS commands would actually migrate the region to TXSeries 7.1 version.

log_filename is the log file, that logs the information about the migration.

region_name is the region that needs to be migrated.




b) Run the upgrade script by entering the following command.

# ksh script_name

where:

script_name is full path name of the upgrade script.

When this script has run, the region has been migrated to the latest version level.

Further information on migration to TXSeries 7.1 can be found here: http://publib.boulder.ibm.com/infocenter/txformp/v7r1/index.jsp?topic=/com.ibm.cics.tx.doc_7.1.0/tasks/t_mig_tx_previous_ver.html

Debugging CICS COBOL programs using MicroFocus COBOL Animator (for Open Systems)

Animator is a MicroFocus tool for debugging your COBOL programs. It intercepts the execution of an application program, showing execution of your code line by line. Application screens are displayed in a different window, as and when required. This process is referred to as animating or animation of a COBOL program.

For more information on Animator, click here.

TXSeries supports cross-session debugging with Micro Focus Server Express COBOL. Cross-session debugging enables the user to use Animator in a different terminal window from that in which the program to be debugged is running.

To configure Animator, to animate CICS COBOL application programs, you can read through this page.

Animating a CICS COBOL program

1. Create required TD and PD entries, so that TXSeries can find and execute your COBOL application program.
Run CADB and setup the program for debugging.(Lets call this terminal session as TERM1) (See Screenshot)

In the above screen, the following fields are required.

1. COBANIMSRV Id - Any string (max. 40 characters), containing only alphabets or numbers

2. PROGRAM : The name of the program to be debugged/animated. Note : This should be the same name as that of the PD entry.

Press enter to accept the debugging values in CADB.

3. In a new terminal session (lets say TERM2), set the following variable

export COBANIMSRV = value of “COBANIMSRV Id” from CADB screen

4. Now, in TERM2, run the command

cobanimsrv

The screen should be blank, waiting for execution of a COBOL program.

5. Go back to TERM1, and run the transaction, which invokes the COBOL program.

E.g. cicslterm -r TXREG1 -t "transaction_name"

6. Now, in TERM2, you should see your COBOL code, in animator.(see screenshot)

7. You can now perform various debugging tasks, as provided by Animator.

E.g. To execute the program, just press 'g' (Go). You will be see each line of code highlighted as program is being executed.

Remote Task Information (or Transaction life mapping) feature in TXSeries : What is it?

Well, if you have been using TXSeries, one of the difficult problems that you would have come across is to debug transaction error scenarios that span across multiple regions. Co-relating critical data for a transaction or a task across all the involved regions is always important while debugging such scenarios. In most situations, a TXSeries setup involves multi-region setup that are all connected using inter system communication facilities (DPL, TR etc). So, if you imagine a typical setup, 3 TXSeries regions are connected with each other and workload is distributed across these three TXSeries regions using LINK command or API.

Remote task information (or also called as Transaction life mapping) feature in TXSeries 7.1 helps gather information about corresponding task in the immediate front end region and the originating region. For example, in the above figure, if you are looking for information for CPMI transaction in region “C”, you will be able to get task information about CPMI running in region “B” and information on the task T1 running in region “A”. Critical information such as, Process ID, Task ID, Program name, Terminal ID (originating terminal) and Task start time are generated. Today, this feature logs data in an extra partition TDQ under /var/cics_regions//data directory.

This was for what this feature is, now let’s just look at a few scenarios where this new feature comes in handy…

Making sense of the monitoring data…

Usually, whenever a user reports the problem of transaction response time being large (i.e slow transactions), one of the immediate request is to generate monitoring information. This information comes along with various parameters such as transactions start time, elapsed time and so on, which is quite handy in figuring out where the delay is caused. However, in the case of transactions spanning across multiple regions, just this monitoring information usually would not help. Yes, if the problem is occurring within the span of any given region, it would still be alright, but if the monitoring information does not show any apparent issue, that’s when co-relation across various regions becomes important.

The data generated by remote task information feature helps the user to understand the behavior of the transaction prior to landing into this current region. For example, using the data such as PID, TID, Transaction / task start time and so on, it’s easy to understand where the transaction spent how much time. If the transaction response within a given region is alright, the co-relation allows us to see if the delay happens to be over the network for example.

Sometimes, if all the transactions in the backend region run under the CPMI name , the remote task information comes in handy to differentiate each one of them while relating the monitoring data across regions. Typically, PID and task ID of each of those transactions can be mapped using the remote task information data for differentiation.

Task/Transaction hanging in the backend region…

On many occasions, we see transactions hanging on the backend due to some issue on the corresponding front end transaction. For example, an application server process on the front end may either have got terminated (possibly due to timeout and force-purge) or the application server process could be hanging for some reason. To be able to relate the hanging backend transaction to the front end transaction, the data generated by the remote task information can be used to identify the triggering PID and transaction ID. This co-relation can help isolate the problem to a particular region or a process. One such scenario could be, backend transaction hanging as the front end process went away due to forcepurge as a result of client timeout. Just tweaking the timeout value can solve this problem as well. Even if the problem is slightly more complex, co-relating the data can help isolate processes with hang situations and map the overall life of that transaction, thus helping understand the scenario better.

There are some more cases in which this feature can be handy. For example, one of the data that you can get to know is the terminal ID from where the transaction got initiated. This information that can help identify branches or end clients which are initiating the transactions.

Remote task information is not enabled automatically in your TXSeries 7.1 region. Parameters “EnableTaskInfo”, “SendTaskInfo” and “DumpRemoteInfo” need to be set to “yes” in the region stanza.

Overall, a very handy feature – especially for troubleshooting. This feature is currently supported with CICS_TCP and PPC_TCP protocols and across TXSeries regions running on TXSeries 7.1. Not supported with prior versions of TXSeries. Also, since the remote task information generates lots of data, you might want to use it based on the need appropriately to avoid any degradation in performance.

TXSeries library @ http://publib.boulder.ibm.com/infocenter/txformp/v7r1/index.jsp would help find more information on usage of this feature.

Do comment on the feature and let me know if any of you readers have any suggestions…

TXSeries Region restart taking long time than expected???

TXSeries Region restart taking long time than expected???

             If TXSeries CICS region is stopped with -f option or if a transaction using SFS server file terminates abnormally and started with StartType=cold option, then one of the possible reason for starting the region taking long time than expected can be open file descriptors if region is configured with SFS server. Even the region is stopped forcefully, some times the OFDs related to that region still remain open.

             For checking the open file descriptors for a specific region perform following operation

sfsadmin list ofds -server /.:/cics/sfs/<sfs server Name> |grep <region Name>

             A file can become unavailable if it is not appropriately closed. For instance, if a client of an SFS server terminates abnormally, files that were exclusively opened by the client may remain open, preventing access by other users. While restarting the region, for each file it will wait. Depending on number of open file descriptors, the region start will wait for that much time.

             You can terminate the ofds using following command

sfsadmin terminate ofd -server /.:/cics/sfs/<sfs server Name> <ofd number>

             For more information on OFD, check

http://publib.boulder.ibm.com/infocenter/txformp/v7r1/topic/com.ibm.cics.tx.doc/reference/r_sfsadmin_terminate_ofd.html#r_sfsadmin_terminate_ofd

Resolving hostname issue in UNIX Platforms

A very common stop point when configuring a region on HPIA and other unix machines for any tests is the hostname issue. There are many a instance when your configuration searches for hostname and gets a "-s" or you get a blank space or you miss checking for it. The hostname represents the dns name of that machine in the network. This hostname is used in multiple places, for instance, for setting default SFS server name.

The following is the console log usually found when there is no hostname declared and region fails to start:

ERZ010144I/0375 09/06/10 14:35:11.313616000 ISCPTF02 22554/0001 : Application server 102 started
ERZ044012E/0023 09/06/10 14:35:11.317421000 ISCPTF02 22553/0001 : Unable to convert TCP/IP host name '' into a network adapter address for LD entry 'TCP'. Error number was 2.
ERZ044009E/0010 09/06/10 14:35:11.319621000 ISCPTF02 22553/0001 : CICS listener 'TCP' process 'cicsip' start was unsuccessful
1 22552 10/09/06-14:35:11.458937 6c1c041c T ppc_tcpSockInit: gethostbyname error: -s not found
1 22552 10/09/06-14:35:11.459940 0000000c T /cics/FSB/encsrc/src/ppc/tcp/ppc_tcpSock.c 869
ERZ010040I/0055 09/06/10 14:35:11.460257000 ISCPTF02 22552/0001 : CICS control process 'cicsas' terminated
1 22554 10/09/06-14:35:11.464153 6c1c041c T ppc_tcpSockInit: gethostbyname error: -s not found
1 22554 10/09/06-14:35:11.464635 0000000c T /cics/FSB/encsrc/src/ppc/tcp/ppc_tcpSock.c 869
ERZ010040I/0055 09/06/10 14:35:11.464837000 ISCPTF02 22554/0001 : CICS control process 'cicsas' terminated


Steps to resolve the issue:

1. Go to sam (type "sam") in command line for HPIA , similarly, if its AIX, type smitty.
2. Select networks and communications and then goto hosts
3. There, it will show you suggested names and the current names. Now modify as required and save the configuration. Now your hostname must be displayed.

Steps to configure a TXSeries region with a particular language

IBM TXSeries for Multiplatforms supports multiple locales. Details of TXSeries supported locales can be found in the infocenter link http://publib.boulder.ibm.com/infocenter/txformp/v7r1/index.jsp?topic=/com.ibm.cics.tx.doc/concepts/c_tx_supported_locales.html

Here are the steps to configure a TXSeries region with a particular language(locale)

1) Create a new region
cicscp –v create region japreg

2) Setup region environment to work with the language.
Suppose we are configuring a region with Japanese language, we need to export the following environment variables in the regions environment file.
LANG=Ja-JP
NLSPATH=$CICSPATH/msg/Ja_JP

3) Copy the Japanese map files into regions map directory.
cp $CICSPATH/msg/Ja_JP /var/cics_regions/japreg/maps/prime

Copying the Japanese map files into regions prime folder will enable the region to pick the Japanese map files whenever we are running CICS Supplied transactions like CSTD,CEBR etc

4)Start the region
cicscp –v start region japreg StartType=cold

To check whether the region is properly configured with Japanese language, we can check for the following ‘ERZ010135I ‘ message in the console file of the region.

ERZ010135I/0362 09/15/10 23:21:12.642808969 test2 46208/0001 : CICS region 'japreg' is being started with locale categories Ja_JP Ja_JP Ja_JP Ja_JP Ja_JP Ja_JP’

Boost your application performance using SET NEWCOPY

Caching a program saves reloading costs thereby improving the performance.
The SET PROGRAM NEWCOPY or SET PROGRAM COPY (NEWCOPY) or SET PROGRAM PHASEIN or SET PROGRAM COPY (PHASEIN) commands for a Micro Focus Server Express COBOL or Net Express program removes every program that was previously loaded by the application server, so that a fresh copy of every such program is used after one of these commands is run.
Here we will learn how SET NEWCOPY works in Windows for both .cbmfnt and .gnt files.
Language:COBOL

1.First create a region "cicscp -v create region test123"(say region name is test123)
2.Take a simple "hello world" program (P1) in COBOL.
Take another program (P2) to be written with EXEC CICS SET PROGRAM(P1) NEWCOPY.

3.TD,PD entries are added for the first program
cicsadd -c td -r test123 QWER ProgName=P1 which will add the transaction definition entry.
cicsadd -c pd -r test123 P1 PathName=hello where hello is the executable.
Similarly TD,PD entries are added for the second program.

4.Then compile both the programs using cicstcl –elCOBOL .ccp to generate .cbmfnt files" where .ccp is ur cobol program.
Cold start the region using "cicscp -v start region test123 StartType=cold"
5.Do a cicsteld and run the transaction of the first program "P1"and observe the output.
Modify this program and recompile.
6.Now run transaction of the second program P2 once, and then run for P1 again. Observe the output,it should reflect the changes made in the first program.

The same scenario can be run using the following:
a)CEMT SET PROGRAM(P1) NEWCOPY.
b)CECI SET PROGRAM(P1) NEWCOPY.

Steps to generate .gnt file on windows:
SET COBCPY=C:\opt\cics\include
cobol NOANIM OMF"GNT" /CALL-RECOVERY /DATA-CONTEXT

Four Easy steps to Configure TXSeries Region with DB2

If you are going to use TXSeries with DB2 but not sure how to start that systematically,no worry...just follow simple steps mentioned below and it's done...

1)Configure the region-

First of all create a region (say test) by "cicscp -v create region test" and Set the CICSREGION environment variable to the name of the region.

Add the following entries corresponding to created region like-

cicsadd -c td -r $CICSREGION UXA1 ProgName="UXA1C" to add transaction entry definition

cicsadd -c pd -r $CICSREGION UXA1C PathName="uxa1" to add program entry definition

2) Build the programs.

Compile your C program and put it in your region's bin directory. I am assuming here that your program executable name is "uxa1" same as used in above PD entry addition commands.

3) Enable the XA connection.

The XA standards define the interfaces between the transaction manager, application program, and the resource manager to achieve the two-phase commit in a DTP(Distributed transaction processing) environment and hence you need to define the XA connection to the region as described below using the cicsadd command because using the XAD connection your program will be talking to DB2.Here i am using default database cicstest you can have different database also.

cicsadd -c xad -r $CICSREGION XADdef SwitchLoadFile=cicsxadb2 XAOpen=”cicstest,username,password”

Here XAOpen string is using switcload file cicsxadb2 which is provided with TXSeries and hence you don't need to build it.

Also XAOpen string contains crucial information to be used for making connection with DB2.here "cicstest" is your database name and "username and passwords" are same as you have set up during database installation.

4) Now just cold start the region "cicscp -v start region test StartType=cold" and you are ready to run your transaction.

Getting around starting woes

If you're doing a fresh installation of TXSeries on a machine i.e., the first time TXSeries is being installed on that machine you might hit a couple of issues.

NLSPATH or LANG isn't set

For example, when you try to start/create a region using the command :
"cicscp -v start region XYZ StartType=cold"

You are likely to see this message :
ERZ057001E/00xx: Cannot access message catalog cics.cat for message ERZ038038I
Please check if NLSPATH or LANG variable is set

This happens because the LANG environment is set to "C" by default, since there is multiple language support with TXSeries and the user has to set this variable.
Also, we need to verify if the path that contains the directory (catalog) that contains CICS messages. This is usually found in this path : /msg/ or /usr/lpp/cicssm/msg ( /opt/lpp/cicssm/msg for non AIX )

ERZ038255E : SFS_NO_SUCH_FILE_SYSTEM

Another issue that you may hit is when we try to start a region/sfs for the first time, you may see SFS_NO_SUCH_FILE_SYSTEM where even though the sfs server exists, it fails to start.
In this case, we need to stop the sfs server and do a cold start.

Stop : cicscp -v stop sfs_server sfsSeverName
Cold Start: cicscp -v start sfs_server sfsSeverName StartType=cold

(Warning : Cold starting an sfs server will erase user's files and TDQs. Never cold start an sfs server in the middle of a production environment )

More on ERZ038255E :
http://www-01.ibm.com/support/docview.wss?uid=swg21045527
http://www-01.ibm.com/support/docview.wss?uid=swg1IZ64176
http://www-01.ibm.com/support/docview.wss?uid=swg21045361

TXSeries..CICS.. What is this all about..

Well, there is a lot of TXSeries and CICS talk here. If you are like me (ie. like I was a few years back), you probably doesn't know anything about TXSeries. And perhaps you know CICS only as some kind of a mainframe specific skill.

I'll try to demystify some of these CICS/TXSeries talks to begin with in this blog.

All right.. so to start with let's figure out what CICS is..

CICS stands as an acronym for Customer Information Control Systems. A mouthful eh?
Well, I know that doesn't tell you anything about what CICS is all about.

Ok..ok.. let me try explaining this in a more simple way. CICS is a software originally designed to run on IBM mainframe systems, which helps customers to develop and deploy their business applications.

What does that mean? In modern parlance, you call CICS as a middleware. In a nutshell what it does is, it runs business applications for you. We'll see how is that done and what makes CICS so successful and mysterious.

So, we said CICS helps you running your applications. Let's see what is required to run applications. What do applications do normally? 3 things...

1. Take some kind of inputs from a user or give some output to a user
2. Store or retrieve some kind of data based on some logic
3. Correlate the inputs in some way with the stored data

If I make this a bit generic, it would translate into

1. Ability to interact with users through user interfaces (presentation)
2. Ability to handle data
3. Ability to write business logic to handle the data and inputs.

The key reason for people using CICS (and why CICS is still successful after 40 years.. about that later) for managing their applications is that CICS provides all these essential services required by applications.

To begin with on the mainframes, data used to be (and even now in many cases) stored on what is called datasets or Files in a VSAM file system. CICS gives you APIs to access those files and read, write and modify data in these files. It is pretty much like the SQL apis that you use today with RDBMSs. CICS data management APIs get you the data the way you want, without you having to know where the data is and how it is stored.

Similarly, CICS gives you a set of APIs and capability for managing presentation interfaces. If you have seen old mainframe applications, you would have noticed those infamous green screens. Many of them are provided by CICS. Of course, modern day CICS applications seldom use those kind of presentation interfaces. But if you want a bare minimum application up and running all that you need is only CICS and it can give you a character based presentation layer.

Likewise, CICS also provides a number of APIs to manage business logic. You can call different programs from within applications, pass data, do various things to manage things.

In addition CICS supports multiple programming languages like COBOL, C, PL/I, Java which you can write your applications on.

So, in essence CICS gives you a basic infrastructure facility to write and host your applications, without worrying about the details underneath, like how the data is stored, where and how the user interface is presented or where a called program resides. It makes application programming much transparent and allows the application programmer to concentrate on what they want to do. ie. writing business applications.

Yes, that's what makes CICS unique and interesting. That's why it is here for the past 40 years and still going strong.

Hopefully that gives you an idea of what CICS is and what it does... Will come back with more sometime later.

New to TXSeries, TX Series, TxSeries. Txseries, TXS, TXSeries/CICS.....?

Hmm... probably the first thing to know if you are new to TXSeries, is how to search for relevant materials/discussions on the web!

There's a lot of documents on the web that has mis-interpreted the name of the product with some of the variations you could see in the title of this blog itself! When I do a Google on "TXSeries" it's always the standard information from the product's site... I don't tend to see any discussion out there in the community, but a small tweak to the name, like "TX Series" +CICS produces some amazing results... give it a try!

I guess, the correct representation of the product name is "TXSeries" (the first three letters in capital) ... or to be more precise "TXSeries for Multiplatforms" as seen in the IBM's site.

So few tips if you are searching for any content related to this product. Use different variations of TXSeries like TXSeries (the correct one, unfortunately with less search results), TX Series (the most commonly used 'incorrect' representation), and so on. And a magic happens, and your search results gets more precise if you include the "CICS" word in your search.

I have heard this product getting referred to other names like CICS on open systems, CICS on distributed platforms, CICS open, CICS 6000, CICS on AIX... So if you are not finding any results with your searches, you might want to include some of these terms and try again.

If you still can't get relevant search results, may be that's something not yet discussed on the web, so you might want to try discussing it here: TXSeries Forum

So, happy searching! and you have learnt your first lesson on TXSeries!

Port stealing between different cics processes

Whenever we bring up more than one region on the same host machine what if the first region's cics processes steals the listener port assigned to the second region's listener?
This is very much possible provided the listener ports for the second region lies in the dynamic port range of host machine's OS. This looks like an uncommon scenario but occurs surprisingly often.

Region A Steals Region B's Ports
First question which would strike anyone here is how the first region's process managed to steal the port assigned to the other region's listener. This is possible because, when first region comes up, it runs a daemon process called “SARPCD” which acts as an endpoint
between various cics processes. So the first region's cics processes needs to register with SARPCD for tcp, udp and cics_ipc transport layer protocol in order to communicate with other cics processes.
So here's the hook from Region A. Since Region B has not started yet, if its listener ports defined in /etc/services are in the dynamic port range of the host machine OS, then it is available to be used by the Region A's cics processes to register with SARPCD. Region B's ports are hence liable to be stolen by Region A!


Aftermath : Region B Fails to Start
Second question following it is about the consequences. Since
the port assigned to Region B has already been stolen by Region A's cics processes, whenever
we try to bring up Region B, it will fail with a message "cicsip failed to start"

The Solution
Now the next thing to follow is the solution. With the new IANA standard, dynamic port range has been shifted to 49152-65535. This reduces the chance of port stealing provided the assigned port range for the Region is below 49152.
Microsoft Windows operating systems from Server 2003 use the range 1025-5000 as ephemeral ports(dynamic port). Windows Vista and Server 2008 use the IANA range(49152-65535 ). So Windows versions before Vista are quite suseptible to this issue if we choose listener ports for Region B and subsequent regions in the range of 1025-5000.
To overcome this issue either choose listener port for subsequent regions above 5000 or tweak the registry to restrict the dynamic port range inside the provided range of 1024-5000 to a range for which you are not going to define a subsequent region's listener.

Information on how to tweak registry can be found here.

Introduction to WebServices in TXSeries

TXSeries for Multiplatforms announced the availability of in-bound web services support natively in November, 2009. The feature is provided as a support pac named CN01 (can be downloaded from here,http://www-01.ibm.com/support/docview.wss?rs=1083&uid=swg24024193). CN01 provides support for in-bound SOAP requests to be translated to program invocations in TXSeries. It allows to expose existing or new transactions as web services. There is no requirement for additional products now to be able to perform this function. Prior to this support pac, clients had to use WebSphere Application Server and CICS Transaction Gateway to be able to do this.
With this feature, TXSeries acts as a Web services provider. Transactions written in C or COBOL programming languages can be exposed as Web services. A new tool, CICS WebServices assistant is provided with this SupportPac, which helps to create Web services description language (WSDL) files from the language structure. Various commands are available for using the tool. In addition, RDz (Rational Developer for System z) provides web services assistant tool that can be used to create WSDL files. Refer to RDz documentation for more information on usage and details of applicable options for TXSeries.
Note : The WSDL files created using the Web services assistant tool are compatible with CICS TS (CICS Transaction Server for z/OS). However, TXSeries does not support all the features or options that CICS TS supports.
This SupportPac is supported for use with TXSeries 7.1 Fixpack 1. SupportPac does not work with prior versions of TXSeries.
Some important information about the support pac below,
Ability to expose CICS transactions as Web services. Does not support invocation of other Web services (outbound) from within TXSeries runtime.
Supported only on English language
Supports COMMAREA interface only. Does not support Containers & Channels.

Additional information and details available with following links ,
TXSeries web site -> http://www-01.ibm.com/software/htp/cics/txseries/
Infocenter -> http://publib.boulder.ibm.com/infocenter/txformp/v7r1/index.jsp
Podcast on Enhancing Business Flexibility using WebServices in TXSeries for Multiplatforms V7.1 can be found at the library -> http://www-01.ibm.com/software/htp/cics/txseries/library/
Developer works article : Using and configuring WebServices with TXSeries -> http://www.ibm.com/developerworks/webservices/library/ws-txseriesmulti/index.html

Introduction to TXSeries

Introduction to TXSeries
TXSeries for Multiplatforms is a distributed CICS transaction processor for mixed language applications.

IBM TXSeries for Multiplatforms V7.1 delivers simplified interoperability with IBM CICS Transaction Server, improved system resilience, problem determination, and application development tooling.
* Robust and extensible distributed transaction processing platform for deploying CICS applications written in C, C++, COBOL and PL/I.
* Widely used for integrating data and applications between distributed solutions and enterprise systems such as CICS and IMS.
* Reuse existing CICS applications and application programming skill sets in your organization consistent with corporate distributed platform policy.
* Develop, test and diagnose CICS applications using COBOL, PL/I, C, and C++ for deployment to CICS Transaction Server for z/OS.
* TXSeries for Multiplatforms V7.1 delivers significant enhancements in integration and connectivity through containers and channels and TCP/IP based interoperability between CICS regions, and further improvements to system resilience, application development and problem determination tooling, Web administration console, and installation.

Important documentation information can be found here, http://www-01.ibm.com/software/htp/cics/txseries/library/