View source for Providing a common CCAIN configuration with PRECCAIN

Starting with version 7.5 of <var class="product">Model 204</var>, you can provide a
<b>common configuration</b> for all ONLINE (and/or IFAM1 and/or IFAM4) jobs, by
[[#linkPRECCAIN|linking PRECCAIN]]
into your <var class="product">Model 204</var> ONLINE (and/or IFAM1 and/or IFAM4)
load module. <code>PRECCAIN</code> contains a series of parameter settings and command invocations.
The parameter settings are processed
at the very beginning of <var class="product">Model 204</var> initialization, namely, immediately before
processing the <code>EXEC PARM</code> field in an z/OS ONLINE job, and the commands are processed just after
processing the <code>EXEC PARM</code> field.
 
Before presenting the [[#usingPRECCAIN|details for PRECCAIN]], note that (for ONLINE and IFAM4)
there is an [[#otherUser0|alternate approach]] to provide a common configuration for <var class="product">Model 204</var>.  This may be more effective for you,
since whenever you want to change
the <code>PRECCAIN</code> configuration you must re-link <var class="product">Model 204</var>.
 
One of the uses of <code>PRECCAIN</code> is to
replace the <code>CUST</code>
module which was used to configure date time stamp fields in previous versions of <var class="product">Model 204</var>.
<code>PRECCAIN</code> can be used for any <var class="product">Model 204</var> parameter defaults, and for invoking many
commands (such as <var>[[MSGCTL command|MSGCTL]]</var>) during initialization, but you should keep <code>PRECCAIN</code> as small
as effectively possible, to avoid the need to frequently re-link <var class="product">Model 204</var>.
 
<div id="otherUser0"></div>
==Alternate approach for providing a common configuration==
<!--Caution: <div> above-->
 
There is another approach which provides a common configuration for <var class="product">Model 204</var>.  This may be more effective for you,
since changing the <code>PRECCAIN</code> configuration requires re-linking <var class="product">Model 204</var>.
 
<blockquote class="note"><b>Note:</b>
 
<table><tr><td><ul><li>The date time stamp field feature provided by the <var>[[DTS parameter|DTS]]</var> parameter may be the best candidate for use of a common <var class="product">Model 204</var> configuration, since the value of the <var>[[DTSFN parameter|DTSFN]]</var> parameter is, in effect, common to every file at your site.</li>
<li>Starting with version 7.5 of <var class="product">Model 204</var>, you can use the <var>CREATE</var>xxx and <var>UPDATE</var>xxx field attributes rather than <var>DTS</var>, providing the same basic functionality as <var>DTS</var> on a file by file basis.</li>
<li>Providing a common configuration for IFAM1 requires programmatic changes to the IFAM1 applications.</li></ul>
</td></tr></table>
 
Therefore, if both the following are true:
<ul>
<li>You have IFAM1 applications.</li>
<li>You use <var>DTS</var> files and have not been able to convert them to use the <var>CREATE</var>xxx and <var>UPDATE</var>xxx field attributes instead.</li>
</ul>
Then you may find that, at least for the <var>DTSFN</var> parameter, you need to use the <code>PRECCAIN</code> feature.
 
</blockquote>
 
However, the alternate approach requires that you are able to identify and change every <var class="product">Model 204</var> job at your site; if you are unable to manage that and a common configuration is necessary, this is the other situation in which you should [[#usingPRECCAIN|use PRECCAIN]].

===Common concatenation of CCAIN===
The more flexible approach to a common configuration is to modify all ONLINE and IFAM4 jobs so that the <code>CCAIN DD</code> is a concatenation of multiple <code>DD</code> statements, with the first one containing the common configuration.  For example, to set the <var>DTSFN</var> parameter so that it is the same for all jobs:
<p class="code">//CCAIN DD DISP=SHR,DSN=M204.COMMON.CCAIN.PARAMS
//      DD *
NUSERS=01,SERVSIZE=567656,LOUTPB=5000,RCVOPT=X'00',NSUBTKS=8,          X
LFSCB=65528,NSERVS=01,MAXBUF=20,  NFILES=13,RETRVKEY=12,LOGADD=5,      X
 ...
</p>
In <code>M204.COMMON.CCAIN.PARAMS</code> you would have:
<p class="code">DTSFN=DATE_FIELD,                                                      X</p>

Note the continuation character in column 72.  You can, of course, provide multiple parameter settings in <code>M204.COMMON.CCAIN.PARAMS</code>.

If your common configuration also contains commands, you will probably want to place them into a separate dataset, so that you can add additional commands for any given online:

<p class="code">//CCAIN DD DISP=SHR,DSN=M204.COMMON.CCAIN.COMMANDS
//      DD *
MSGCTL M204.1500 OPR
//      DD DISP=SHR,DSN=M204.COMMON.CCAIN.PARAMS
//      DD *
NUSERS=01,SERVSIZE=567656,LOUTPB=5000,RCVOPT=X'00',NSUBTKS=8,          X
LFSCB=65528,NSERVS=01,MAXBUF=20,  NFILES=13,RETRVKEY=12,LOGADD=5,      X
 ...
</p>

In this case you might put the following (you can provide multiple commands, each starting on a new line) in <code>M204.COMMON.CCAIN.COMMANDS</code>:
<p class="code">MSGCTL M204.0619 NOAUDIT</p>

====Usage notes for concatenation approach====
<ul>
<li>In addition to avoiding the installation of <code>PRECCAIN</code>, the concatenation approach allows you to immediately change the common configuration, without requiring you to reassemble <code>PRECCAIN</code> and then to re-link ONLINE and IFAM4.
<li>The concatenation approach requires that you modify all ONLINE and IFAM4 jobstreams, whereas the <code>PRECCAIN</code> approach applies for all jobs using the load module(s) containing your version of <code>PRECCAIN</code>.
<li>As mentioned, the concatenation approach does not lend itself to IFAM1.
<li>One small difference between the concatenation approach and the <code>PRECCAIN</code> approach is that the <code>PRECCAIN</code> parameters are set <b>before</b> the <code>EXEC PARM</code> parameters, whereas the <code>EXEC PARM</code> parameters are set first in the concatenation approach.
</ul>
 
<div id="usingPRECCAIN"></div>

==Using PRECCAIN==
<!--Caution: <div> above-->
 
Since
changing the <code>PRECCAIN</code> configuration requires re-linking <var class="product">Model 204</var>, you should use it sparingly.
Even if you need it,
you should probably keep its contents restricted to those parameters and commands which are required there, and consider a
hybrid approach with <code>PRECCAIN</code> and a common <code>CCAIN</code> concatenation.
So, in any case, before implementing <code>PRECCAIN</code> at all, or
before deciding which commands and parameters you place into it, consider the
[[#otherUser0|concatenation approach]] for providing a common configuration.
 
Using <code>PRECCAIN</code> is simple:
<ol>
<li>Copy member <code>PRECCAIN</code> from your [[M204_inst_zOS#RKMACLIB|installation macro library (RKMACLIB)]] into your local source library (which is also discussed on that installation wiki page).
 
This step should only be performed once; if you have ever performed it before, do not perform it again.  The DSN of your local source library does not contain the <var class="product">Model 204</var> version number; it is used for all versions of <var class="product">Model 204</var>.
</li>
<li>See the
[[#modifyPRECCAIN|instructions below]] to
modify the copy of <code>PRECCAIN</code> in your local source library.
<li>Assemble the copy of <code>PRECCAIN</code> from your local source library:
<ul>
<li>Copy member <code>JASMJ</code> from RKOBJLIB to your local TSO library, naming it something like ASMPRECC.
<li>Modify your <code>ASMPRECC</code>:
<ul>
<li>Near the top of <code>AMSPRCC</code>, change <code>hlq</code> on the JCLLIB statement to your installation high level qualifier(s).
<li>On the last two lines of your <code>ASMPRECC</code>, supply your installation high level qualifier after <code>HLQ=</code> and
add <code>PRECCAIN</code> after <code>MEM=</code>.
</ul>
<li>Submit your <code>ASMPRECC</code> jobstream, which results in the
<code>PRECCAIN</code> object file being stored in your local object library.
</ul>
<li id="linkPRECCAIN">Now that
<code>PRECCAIN</code> is assembled into your local object library, subsequent linking of your ONLINE, IFAM1, and/or IFAM4
load modules will include your <code>PRECCAIN</code> configuration.
</ol>
 
<div id="modifyPRECCAIN"></div>
===Modifying PRECCAIN===
After you copy <code>PRECCAIN</code> from the installation macro library (RKMACLIB) to your local source library, you will
add, to the local source copy, assembler statements of the following form:

<p class="code">  DC CL80'<i>text</i>'</p>

Each statement is used to either set its specified parameter value, or to invoke the
<var class="product">Model 204</var> command which it contains.
 
The structure of <code>PRECCAIN</code> is:
<p class="code"><nowiki>PRECC    TITLE 'Default parameters and initialization commands'
CCAIN001 DC    0H'0'
***********************************************************************
*  Here are the default parameters, 80 bytes each:                    *
*        DC    CL80'parameterName parameterValue'                     *
*        ... as many as are needed                                    *
*                                                                     *
* End of default parameters                                           *
***********************************************************************
 
CCAIN002 DC    0H'0'
***********************************************************************
*  Here are the initialization commands, 80 bytes each:               * 
*        DC    CL80'msgctl/etc. command'                              *
*        ... as many as are needed                                    *
* End of initialization commands                                      *
***********************************************************************
 
CCAIN003 DC    0H'0'
         END
</nowiki></p>

There are two sections; each section contains a series of assembler
<code>DC CL8'</code><i>text</i><code>'</code> statements, with the
<i>text</i> being used:
<ol>
 
<li>Between CCAIN001 and CCAIN002 &mdash; parameters
<br/>Here you place in the <i>text</i> the name of the parameter, a
blank, and the value of the parameter, just as you would in a
<var>[[RESET command|RESET]]</var> command.</li>
 
<li>Between CCAIN002 and CCAIN003 &mdash; commands
<br/>Here you place in the <i>text</i> a command name and its arguments,
just as you would in the commands in <code>CCAIN</code> after the
IODEV lines.
The same set of commands is allowed as is [[Defining the runtime environment (CCAIN)#Runtime environment|allowed before the User 0]] parameter line, for example:
 
<ul>
<li><var>[[MSGCTL command|MSGCTL]]</var></li>
<li><var>[[RESET command|RESET]]</var></li>
<li><var>[[APPDATE command|APPDATE]]</var></li>
<li><var>[[*LOWER command|*LOWER]]</var></li>
<li><var>[[DEFINE DATASET command|DEFINE DATASET]]</var></li>
<li><var>[[DEFINE STREAM command|DEFINE STREAM]]</var></li>
</ul>
</li>
</ol>
 
<blockquote class="note"><b>Notes:</b>
<ul>
 
<li>When an apostrophe is needed, as in all assembler statements, it must be doubled;
for example, to mimic <code>RESET DTSFN C'SHIPMENT DATE'</code>:
<p class="code"><nowiki>        DC    CL80'DTSFN C''SHIPMENT DATE'' '</nowiki></p>
</li>
 
<li>If you need to continue a line, you don't need to use the assembler continuation
convention, but instead use a length other than 80 in the DC statement, and use a
series of lines whose lengths add to 80, to represent a single parameter or command
line.</li>
 
Here is an example (which would be ridiculous, because not all onlines could use the same tnserv port number!) to illustrate
lines which might not fit on a single assemble source line:
<p class="code">DC CL12'JANUS DEFINE'
DC CL68' MYTNSERV 7204 TNSERV 10 WSFQUERY TCPKEEPALIVE'
</p>
 
<li>As exemplified above, as long as you are not dealing with assembler continuation, your <code>DC</code> statements do not
need to have the customary column 10 and 16 alignment.  One or more blanks before and after <code>DC</code> is entirely sufficient.</li>
 
<li>The parameters and commands
generally (except as you reset the <var>[[INCCC parameter|INCCC]]</var> parameter), just as
in <code>CCAIN</code>,
require a continuation character in column 72 of the line if continuation is needed.
Those situations are a clear example of when you will want to
use the technique just explained of dividing the 80 byte line into separate <code>DC CL</code> chunks.
</li>
</ul>
</blockquote>
 
===CCAPRINT output with PRECCAIN===
 
When <var class="product">Model 204</var> intializes and encounters parameters and/or commands in <code>PRECCAIN</code>,
you will see the <code>PRECCAIN</code> results in the <code>CCAPRINT</code> output file.
 
The parameter lines (from the <code>CCAIN001</code> section)
will be shown first, after the following line:
 
<p class="code">M204.0062 Execute parameters: (default)</p>
 
An echo of the 80 byte parameter lines will follow this line, for example:
<p class="code"><nowiki>***        ******            MUDD=5000000
...
</nowiki></p>
 
The echo of the parameters is followed by:
<p class="code">M204.1119: Reading parameters</p>
 
That line is followed the normal <var>RESET</var> command
output from processing each <code>PRECCAIN</code> parameter.  This output usually contains the parameter name in column 1, the parameter value in column 11, and the parameter description in column 23.
For example:
<p class="code"><nowiki>MUDD      5000000     Max UDD lines
...
</nowiki></p>
 
After the <var>RESET</var> output for the <code>CCAIN001</code> parameters, the<code> EXEC PARM</code> parameters will be shown, for example:
 
<p class="code">M204.0062 Execute parameters: SYSOPT=187,LIBUF=2000</p>
 
This instance of M204.0062 is followed by the <var>RESET</var> processing of the <code>EXEC PARM</code> parameters; using the above
example:
<p class="code">SYSOPT    X'BB'       System options
LIBUFF    2000        Length of input buffer
</p>
After the <var>RESET</var> output for the <code>EXEC PARM</code> parameters, the <code>CCAIN002</code> command lines  will be processed, which echoes the command lines (as long as you have not turned off the <var>[[LECHO parameter|LECHO]]</var> parameter), for
example:
 
<p class="code">MSGCTL M204.1149 OPR RETCODEO=0 RETCODEB=0</p>
 
===Examples===
 
The following example shows how to modify <code>PRECCAIN</code> from RKMACLIB so that you can use the field named <code>DATE_FIELD</code> as the value of the <var>DTSFN</var> parameter.  This example shows the entire <code>PRECCAIN</code>, including the blank lines and comment lines (those starting with <code>*</code>).  The parameters are coded between <code>CCAIN001</code> and <code>CCAIN002</code>, and the only non-blank, non-comment line in that section of the example is:

<p class="code"><nowiki>         DC    CL80'DTSFN C''DATE_FIELD'' '</nowiki></p>

This example does not contain any commands; they would be coded bewtween <code>CCAIN002</code> and <code>CCAIN003</code>, but all of those lines are either blank or comments.

<p class="code"><nowiki>PRECC    TITLE 'Default parameters and initialization commands'
PRECC$   CSECT
PRECC$   AMODE 31
PRECC$   RMODE 31
CCAIN001 DC    0H'0'
         ENTRY CCAIN001,CCAIN002,CCAIN003
 
***********************************************************************
*  Here are the default parameters, 80 bytes each:                    *
 
*        DC    CL80'parameterName parameterValue'
 
* 'DATE_FIELD' is the value of the date-timestamp field (DTSFN):
 
         DC    CL80'DTSFN C''DATE_FIELD'' '
 
*                                                                     *
* End of default parameters                                           *
*                                                                     *
***********************************************************************
 
CCAIN002 DC    0H'0'
 
***********************************************************************
*  Here are the initialization commands, 80 bytes each:               *
 
*        DC    CL80'msgctl/etc. command'
 
*        ... as many as are needed
 
*                                                                     *
* End of initialization commands                                      *
*                                                                     *
***********************************************************************
 
CCAIN003 DC    0H'0'
         DC    16C'*'
         DC    CL8'PRECC'
         DC    CL8'Any vsn'
         DC    A(PRECC$_END-PRECC$,0)
         DC    CL16'&SYSDATC &SYSTIME'
         DC    24A(0)
PRECC$_END EQU  *
         END
</nowiki></p>

[[Category:System management]]