JOURNALMODEL resource definitions

The default JOURNALMODEL

If CICS cannot find an installed JOURNALMODEL definition, it assumes a set of default attributes.

 DEFINE JOURNALMODEL(OTHERS) GROUP(LOGS)
           JOURNALNAME(*)
           STREAMNAME(&USERID..&APPLID..&JNAME.)
           TYPE(MVS)

JOURNALNAME(*) is the default journal model that CICS uses if there is no matching JOURNALMODEL entry for a journal name.

Syntax

Attributes

DESCRIPTION(text)

You can provide a description of the resource that you are defining in this field. The description text can be up to 58 characters in length. There are no restrictions on the characters that you can use. However, if you use parentheses, ensure that for each left parenthesis there is a matching right parenthesis. If you use the CREATE command, for each single apostrophe in the text, code two apostrophes.

GROUP(groupname)

Every resource definition must have a GROUP name. The resource definition becomes a member of the group and is installed in the CICS system when the group is installed.

Acceptable characters:

A-Z 0-9 $ @ #

Valid characters are listed as they render when the code page is IBM®-037. If a different EBCDIC code page is used, be aware of variant characters, as documented in Variant characters.

Any lowercase characters that you enter are converted to uppercase.

The GROUP name can be up to eight characters in length. Lowercase characters are treated as uppercase characters.

JOURNALMODEL(name)

specifies the name of this JOURNALMODEL definition.

The journal model name is used to refer to a specific JOURNALMODEL definition in the CSD file—it does not have to correspond to a CICS journal name. However, the JOURNALMODEL name is also used as the JOURNALNAME if you omit the JOURNALNAME attribute.

The name can be up to eight characters in length.

Acceptable characters:

A-Z 0-9 $ @ #

Valid characters are listed as they render when the code page is IBM-037. If a different EBCDIC code page is used, be aware of variant characters, as documented in Variant characters.

Unless you are using the CREATE command, any lowercase characters that you enter are converted to uppercase.

JOURNALNAME(journal)

specifies the journal names to which this definition applies. If you omit the JOURNALNAME attribute, the name you specify on the JOURNALMODEL attribute is used as the journal name. Name can be either the specific name of a journal or a generic name, although using a generic name for system log and log-of-logs models does not serve much purpose.

The name can be up to eight characters in length.

Acceptable characters:

A-Z 0-9 $ @ #

Valid characters are listed as they render when the code page is IBM-037. If a different EBCDIC code page is used, be aware of variant characters, as documented in Variant characters.

Unless you are using the CREATE command, any lowercase characters that you enter are converted to uppercase.

The forms of the names you can define are as follows:

For system logs

To define a JOURNALMODEL for system logs, specify the name as DFHLOG for the primary system log stream, and as DFHSHUNT for the secondary log stream. Install one journal model only for each of these log streams in a CICS region.

CICS-supplied definitions for DFHLOG, DFHSHUNT, and DFHLGLOG are contained in group DFHLGMOD in DFHLIST.

For log-of-logs

To define a JOURNALMODEL for the log-of-logs, specify the name as DFHLGLOG. See Planning log streams for use by your log of logs (DFHLGLOG) for more information about the purpose of the log of logs.

For autojournals

For autojournals (file control and terminal control), the name must be of the form DFHJnn where nn is a number in the range 1 through 99. The name can be either the specific name of a journal or a generic name.

For user journals

For user journals, the name can be up to 8 characters, and can be either the specific name of a journal or a generic name. If compatibility with releases earlier than CICS Transaction Server for z/OS, is required, the name must be of the form DFHJnn where nn is a number in the range 1 through 99.

For forward recovery logs (non-RLS)

For non-RLS forward recovery logs, the name must be of the form DFHJnn where nn is a number in the range 1 through 99. The name can be either the specific name of a journal or a generic name.

Note: You cannot define a journal model for use with VSAM RLS forward recovery logs. CICS obtains the fully-qualified LSN directly from the VSAM catalog, and therefore does not need a journal model to obtain the LSN.

You define generic names, using the special symbols %, +, and *, as follows:

• You can use the % or + symbols to represent any single character within a journal name.
• You can use the * symbol at end of a name to represent any number of characters. A default name of a single * is used to match any journal names that do match on a more specific name.

If there are several installed JOURNALMODEL definitions that match a journal name, CICS chooses the best match as follows:

1. If there is a JOURNALMODEL with a specific JOURNALNAME that exactly matches, CICS uses this model.
2. If there is no exact match, the journal name is compared with the matching generic entries and the most specific entry is used.
   In comparing names to see which one is more specific, the names are compared character by character. Where they first differ:

   • If one has a discrete character (not %, +, or *) and the other has a generic character (%, +, or *) the one with the discrete character is used.
   • If one has a % or a + and the other has a *, the one with % or + is used.
3. If there are duplicate JOURNALMODEL definitions (that is, definitions with the same JOURNALNAME), CICS uses the last one processed.

Attention: Take care when defining a completely generic journal name using only the single asterisk (*). This is particularly important if you have not defined a specific journal model for the system log (using journal name DFHLOG), and the log stream name is a fully-qualified literal name. If you define a journal model with JOURNALNAME(*) and do not define a journal model for the system log, CICS uses the log stream name defined on the generic model definition. This causes problems if other journals and forward recovery logs are assigned to the same log stream by means of the generic journal model.

STREAMNAME({&USERID..&APPLID..&JNAME.|stream_name_template})

specifies either an explicit z/OS System Logger log stream name, or a template used to construct the log stream name. STREAMNAME is applicable only to journal models defined with a LOGSTREAMTYPE of MVS.

The four symbolic names, from which you can use a maximum of three, are:

&USERID.

The symbolic name for the CICS region userid, which can be up to eight characters. If the region does not have a userid, the string 'CICS' will be used.

&APPLID.

The symbolic name for the CICS region APPLID as specified on the system initialization parameter, and which can be up to eight characters.

Note: If you are using XRF and you specify the APPLID system initialization parameter as APPLID=(generic_applid,specific_applid), it is the generic applid that CICS uses when resolving &APPLID..

&JNAME.

The symbolic name for a journal name that references, either by a specific or generic match, this journal model definition. &JNAME. can be up to eight characters in length.

&SYSID.

The symbolic name for the CICS region SYSID as specified on the SYSIDNT system initialization parameter. If SYSIDNT is not specified, the string 'CICS' will be used.

The default set of symbolic names is: &USERID..&APPLID..&JNAME.

For Example: &USERID..&APPLID..&JNAME. =

        CICSHA##.CICSHAA1.DFHJ02

where:

CICSHA##

is the CICS region userid used by all the AORs.

CICSHAA1

is the applid of one AOR.

DFHJ02

is the journal name of an auto journal.

An alternative set of symbolic names could be:

        &SYSID..&APPLID..&JNAME. =
        SYSA.CICSHAA1.DFHJ02

where:

SYSA

is the character string as specified by the SYSIDNT system initialization parameter.

CICSHAA1

is the applid of one AOR.

DFHJ02

is the journal name of an auto journal.

CICS installs the JOURNALMODEL resource as defined, including the symbolic names.

stream_name_template

A log stream name can be either an unqualified name or a qualified name, as defined for z/OS data set names:

• Unqualified name: 1 through 8 alphanumeric or national characters ($ # @), or a hyphen. The first character of the name must be alphabetic or national (A-Z $ # @).
• Qualified name: Multiple names joined by periods, up to a maximum of 26 characters. Each name in a qualified name must follow the rules for an unqualified name, with each qualified name (except the last) followed by a period. For example,

  name_1.name_2...name_n

  where the number of names is restricted by the 26-character limit.

For more information about the rules for qualified and unqualified data set names, see z/OS MVS JCL Reference.

You can construct log stream names consisting of a mixture of specific characters (from within the allowed set), and symbolic names for substitution. After substitution, the name must meet the rules for qualified and unqualified log stream names, and must not exceed 26 characters, including periods. Thus, if each name in a qualified name uses the maximum of eight characters, you are restricted to three names only, with the first and second names, and the second and third names separated by a period. For example:

CICSDA##.CICSDAA1.FWDRECOV

for a forward recovery log stream. The log stream name is determined by symbolic substitution when a journal name is first resolved to a JOURNALMODEL definition.

By specifying the same log stream name for multiple CICS general logs, you can merge the log streams from different CICS regions. However, you cannot merge general log streams with the CICS system log, nor can you merge system logs from different CICS regions.

When merging log streams from different CICS systems, the log data blocks are written to their log streams in strict z/OS System Logger time-stamp sequence. However, the individual records from different CICS regions may not be in strict time-stamp sequence across different blocks

CICS log streams should not be merged with log streams generated by other products unless any programs that read the log stream are prepared to handle the formats.

Security note: When you have defined a log stream name to CICS and the z/OS System Logger, you must ensure that the required security authorizations are defined to RACF® (or an equivalent external security manager). This security authorization is necessary before you attempt to start a CICS region that references a new log stream. RACF supports the LOGSTRM general resource class for this purpose.

TYPE({DUMMY|MVS|SMF})

specifies where the journal records are to be written. It can be up to five characters, and can have the following values:

DUMMY

No log records are to be written. For example, you can use this to suppress unwanted log records without changing an application, or without changing file or profile resource definitions.

If you do not want a system log or a log-of-logs, specify DUMMY on the JOURNALMODEL definitions for the DFHLOG, DFHSHUNT, and DFHLGLOG, as required.

MVS

Records are to be written to a z/OS System Logger log stream. The name of the log stream is specified in the STREAMNAME attribute.

SMF

Journal records are to be written in SMF format to the SMF log instead of to a z/OS System Logger log stream.

Note: SMF is not allowed for the CICS system log or for forward recovery logs.

Examples

Example of resource definition commands for CICS JOURNALMODELs.

  DEFINE JOURNALMODEL(USERJNL8) GROUP(LOGS)
           JOURNALNAME(DFHJ08)
           TYPE(SMF)

  DEFINE JOURNALMODEL(USERJNL9) GROUP(LOGS)
           JOURNALNAME(DFHJ09)
           TYPE(DUMMY)

  DEFINE JOURNALMODEL(UJ10TO19) GROUP(LOGS)
           JOURNALNAME(DFHJ1%)
           STREAMNAME(&USERID..MERGED.USRJRNLS)
           TYPE(MVS)

  DEFINE JOURNALMODEL(LOGOFLOG) GROUP(LOGS)
           JOURNALNAME(DFHLGLOG)
           STREAMNAME(CICSVR.SHARED.DFHLGLOG)
           TYPE(MVS)

 DEFINE JOURNALMODEL(JNLMODL1) GROUP(LOGS)
          JOURNALNAME(USERJNL*)
          STREAMNAME(&USERID..ANYCORP.&JNAME..UK)
          TYPE(MVS)