Well, program auto install is a feature provided in the CICS system which would allow you to define a CICS program at run-time. Usual or common way of defining a program to a TXSeries system would be to add an entry in to the PD definition with the help of a RDO command; say, cicsadd -c pd -r region1 MYPROG PathName=myprog.ibmcob. This process of registering the programs is good if you have limited number of CICS programs that you need to define; however in certain cases the number of application programs are many (say hundreds) in which case it is cumbersome to not only define these many entries in to the PD definition but also will be difficult to maintain and manage them. This is where the program auto install feature would come handy. Let's see how this works:
When a request is received from the client (say a request to run a transaction) CICS system attempts to find the corresponding program to be loaded/executed by looking at the TD definition. Further CICS checks to see if there is a corresponding program entry in the PD definition. If exists it goes ahead, load the program and executes them. But if the program entry does not exist in the PD definition.. this is where the program auto install process kicks in.
CICS system realising that there is no program entry, in the PD definition, it invokes a User Exit program to retrieve details on the program. Ok, I know some of you might be wondering what this User Exit program is?!. Well, User Exit programs are plug-in points where user can write piece of code and plug that in to the TXSeries runtime. The plug-in is built as a C module and is registered with the TXSeries system. There are many user-exits points supported by TXSeries, and one of them is the Program Auto Install User Exit. User Exit programs are usually associated with a Number that is used during the registration, so that TXSeries can know at runtime for what purpose the module needs to be invoked. By now you would have realised that for the Program Auto Install to work we need to register a User Exit Program Module.
Let me take you through the procedure for enabling Program Auto Install under TXSeries. The following steps assumes that you have a CICS region already running.
- Firstly, we need to build the User Exit module for the Program Auto Install. For this we can use the sample that is provided with TXSeries under /usr/lpp/cics/samples/userexit directory. A Makefile is already supplied to build the user exit module, so just run "make" command as following:
The program module will be generated under the same directory called, "cicsuxit". You may want to copy this to the region's bin directory or any other directory that you may prefer.
- Now we need to register this user exit module, for that run the following command:
cicsadd -c pd -r <region_name> UXIT PathName="cicsuxit" UserExitNumber=13
In the above the number '13' refers to Program Auto Install. So when CICS doesn't find an PD entry it will invoke the 'cicsuxit' user exit program module.
- After the above change you will need to cold start the CICS region for the definitions to take effect. Once the CICS region is started, you can just run your transaction and CICS should automatically pick up the corresponding program
- (Optional) You may also want to use the CICS_PROGRAM_PATH=<path> in the CICS region's environment file for specifying the location of your CICS application programs (if different from other than the region's bin directory).
You may want to check the following if you see any issues in running the program:
- Confirm if the console.<nnnnnn> has the following similar entries:
- ERZ015042W/0186 09/09/11 16:16:37.655655539 IVPCICS
49438/0001 : Program 'UXIT' now associated with user exit '13'
- if you don't see the above entry, this mean you have not
registered the user exit module correctly. So check your PD definition
- You may experience the following problem (logged in the CSMT.out file) or transaction abend A141:
- ERZ015022E/0146 09/09/11 16:17:43.398292610 IVPCICS 62300/0001 UMMG: Program '/usr/lpp/cics/src/samples/ivp/COBOL/DFHCMNU' not found
- The program names are case-sensitive.. so ensure your programs are in right case. For example if the file is dfhcmnu, then the above error will be flagged.
- The most likely reason is TXSeries is not able to find the application program in the specified location (or set through CICS_PROGRAM_PATH environment variable) - so check for the program module existence
- If the program module exists check the permission of the file; it should have access (usually read should be enough) permissions for the 'cics' user or just make sure the r+o (read other) bit is set. You will not only have to check the permission of the file, but also for the directories under which the program is residing. Easiest way to confirm this is to login as 'cics' user and doing an 'ls' command should clarify the permission problems.
So with this blog entry I hope to have clarified the Program Auto Install Feature of TXSeries, its benefits, the usage and the common issues around it. Please leave your comments if you have any.