Providing a common CCAIN configuration with PRECCAIN

From m204wiki
Revision as of 00:38, 9 January 2015 by JAL (talk | contribs)
Jump to navigation Jump to search

Starting with version 7.5 of Model 204, you can provide a common configuration for all ONLINE (and/or IFAM1 and/or IFAM4) jobs, by linking PRECCAIN into your Model 204 ONLINE (and/or IFAM1 and/or IFAM4) load module. PRECCAIN contains a series of parameter settings and command invocations. The parameter settings are processed at the very beginning of Model 204 initialization, namely, immediately before processing the EXEC PARM field in an z/OS ONLINE job, and the commands are processed just after processing the EXEC PARM field.

Before presenting the details for PRECCAIN, note that (for ONLINE and IFAM4) there is an alternate approach to provide a common configuration for Model 204. This may be more effective for you, since whenever you want to change the PRECCAIN configuration you must re-link Model 204.

One of the uses of PRECCAIN is to replace the CUST module which was used to configure date time stamp fields in previous versions of Model 204. PRECCAIN can be used for any Model 204 parameter defaults, and for invoking many commands (such as MSGCTL) during initialization, but you should keep PRECCAIN as small as effectively possible, to avoid the need to frequently re-link Model 204.

Alternate approach for providing a common configuration

There is another approach which provides a common configuration for Model 204. This may be more effective for you, since changing the PRECCAIN configuration requires re-linking Model 204.

Note:

  • The date time stamp field feature provided by the DTS parameter may be the best candidate for use of a common Model 204 configuration, since the value of the DTSFN parameter is, in effect, common to every file at your site.
  • Starting with version 7.5 of Model 204, you can use the CREATExxx and UPDATExxx field attributes rather than DTS, providing the same basic functionality as DTS on a file by file basis.
  • Providing a common configuration for IFAM1 requires programmatic changes to the IFAM1 applications.

Therefore,

  • If you have IFAM1 applications
  • and if you use DTS files and have not been able to convert them to use the CREATExxx and UPDATExxx field attributes instead

then you may find that, at least for the DTSFN parameter, you need to use the PRECCAIN feature.

However, the alternate approach requires that you are able to identify and change every Model 204 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 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 CCAIN DD is a concatenation of multiple DD statements, with the first one containing the common configuration. For example, to set the DTSFN parameter so that it is the same for all jobs:

//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 ...

In M204.COMMON.CCAIN.PARAMS you would have:

DTSFN=DATE_FIELD, X

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

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:

//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 ...

In this case you might put the following (you can provide multiple commands, each starting on a new line) in M204.COMMON.CCAIN.COMMANDS:

MSGCTL M204.0619 NOAUDIT

Usage notes for concatenation approach

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

Using PRECCAIN

Since changing the PRECCAIN configuration requires re-linking Model 204, 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 PRECCAIN and a common CCAIN concatenation. So, in any case, before implementing PRECCAIN at all, or before deciding which commands and parameters you place into it, consider the concatenation approach for providing a common configuration.

Using PRECCAIN is simple:

  1. Copy member PRECCAIN from your 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 Model 204 version number; it is used for all versions of Model 204.
  2. See the instructions below to modify the copy of PRECCAIN in your local source library.
  3. Assemble the copy of PRECCAIN from your local source library:
    • Copy member JASMJ from RKOBJLIB to your local TSO library, naming it something like ASMPRECC.
    • Modify your ASMPRECC:
      • Near the top of AMSPRCC, change hlq on the JCLLIB statement to your installation high level qualifier(s).
      • On the last two lines of your ASMPRECC, supply your installation high level qualifier after HLQ= and add PRECCAIN after MEM=.
    • Submit your ASMPRECC jobstream, which results in the PRECCAIN object file being stored in your local object library.
  4. Now that PRECCAIN is assembled into your local object library, subsequent linking of your ONLINE, IFAM1, and/or IFAM4 load modules will include your PRECCAIN configuration.

Modifying PRECCAIN

After you copy PRECCAIN 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:

DC CL80'text'

Each statement is used to either set its specified parameter value, or to invoke the Model 204 command which it contains.

The structure of PRECCAIN is:

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

There are two sections; each section contains a series of assembler DC CL8'text' statements, with the text being used:

  1. between CCAIN001 and CCAIN002 — parameters
    Here you place in the text the name of the parameter, a blank, and the value of the parameter, just as you would in a RESET command.
  2. between CCAIN002 and CCAIN003 — commands
    Here you place in the text a command name and its arguments, just as you would in the commands in CCAIN after the IODEV lines. The same set of commands is allowed as is allowed before the User 0 parameter line, for example:

Notes:

  • When an apostrophe is needed, as in all assembler statements, it must be doubled; for example, to mimic RESET DTSFN C'SHIPMENT DATE':

    DC CL80'DTSFN C''SHIPMENT DATE'' '

  • 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.
    • 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:

    DC CL12'JANUS DEFINE' DC CL68' MYTNSERV 7204 TNSERV 10 WSFQUERY TCPKEEPALIVE'

  • As exemplified above, as long as you are not dealing with assembler continuation, your DC statements do not need to have the customary column 10 and 16 alignment. One or more blanks before and after DC is entirely sufficient.
  • The parameters and commands generally (except as you reset the INCCC parameter), just as in CCAIN, 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 DC CL chunks.

CCAPRINT output with PRECCAIN

When Model 204 intializes and encounters parameters and/or commands in PRECCAIN, you will see the PRECCAIN results in the CCAPRINT output file.

The parameter lines (from the CCAIN001 section) will be shown first, after the following line:

M204.0062 Execute parameters: (default)

An echo of the 80 byte parameter lines will follow this line, for example:

*** ****** MUDD=5000000 ...

The echo of the parameters is followed by:

M204.1119: Reading parameters

That line is followed the normal RESET command output from processing each PRECCAIN 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:

MUDD 5000000 Max UDD lines ...

After the RESET output for the CCAIN001 parameters, the EXEC PARM parameters will be shown, for example:

M204.0062 Execute parameters: SYSOPT=187,LIBUF=2000

This instance of M204.0062 is followed by the RESET processing of the EXEC PARM parameters; using the above example:

SYSOPT X'BB' System options LIBUFF 2000 Length of input buffer

After the RESET output for the EXEC PARM parameters, the CCAIN002 command lines will be processed, which echoes the command lines (as long as you have not turned off the LECHO parameter), for example:

MSGCTL M204.1149 OPR RETCODEO=0 RETCODEB=0

Examples

The following example shows how to modify PRECCAIN from RKMACLIB so that you can use the field named DATE_FIELD as the value of the DTSFN parameter. This example shows the entire PRECCAIN, including the blank lines and comment lines (those starting with *). The parameters are coded between CCAIN001 and CCAIN002, and the only non-blank, non-comment line in that section of the example is:

DC CL80'DTSFN C''DATE_FIELD'' '

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

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

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=Providing_a_common_CCAIN_configuration_with_PRECCAIN&oldid=74558"