SYSOUT Services function

This chapter introduces SYSOUT Services and uses examples to illustrate the concepts and power of SOS.

Description

SYSOUT Services (SOS) provide facilities for you to use DAL (Detail Action Language) to examine the characteristics of DD statements describing SYSOUT data sets, and to change them if desired. There is also some limited facilities available in JAL to deal with global values.

The Problem

To manage printing services for batch jobs can be a challenging task. As the flexibility to make requests using traditional JCL increases, so do management problems. Setting up standards, communicating them to users, and ensuring that they are followed can be difficult.

Changes to JCL streams are costly and error prone. Further, when you want to make changes there is little room to experiment. Your users are probably (and understandably) reluctant to modify JCL. If you force them to spend time making changes only to find out that the chosen approach is less than ideal, well... good luck if you ask for changes again.

Changes, however, are often necessary. The reasons are many, and vary from installation to installation. The most common ones are:

• New printing devices are installed. In some cases, this requires new work selection rules.
• User groups are restructured in ways that require consolidation or separation of printing tasks.
• User groups are physically relocated, requiring changes in destination parameters.
• JES2 nodes are consolidated within a datacenter. This is a common occurrence as the topology of JES2 and the SYSPLEX are made congruent.
• Datacenters are consolidated. This is normally a challenging project. It is exceptionally rare for the "merging" datacenters to have the same standards. In most cases, you must develop a new set of standards to accommodate heterogeneous JCL streams.

SOS deals with all of these issues. Since the requirements are fluid and different in every case, SOS lets you alter anything that a user can request with a DD statement containing a SYSOUT keyword, an OUTPUT JCL statement, or the "old fashioned" JES2

/*OUTPUT statement. SOS makes all the complex interrelations of these statements transparent to the person implementing the changes.

The "alterations" could relate to parameters as common as CLASS or as obscure as PRTOPTNS. Of course, MSGCLASS is also one of the values you can modify. You can also negate the effects of an OUTPUT JCL statements or add a new one. Refer to DAL-Reference-Guide and JAL-Reference-Guide for a complete list.

The Solution: SOS

SOS is a function of the Base Product ThruPut Manager. Its power comes from:

• The ThruPut Manager Job Analyzer facilities.
• The full capabilities of the Job Profile and Action Language facilities of ThruPut Manager.
• Extensions to JAL/DAL that provide a simple but effective architecture to deal with the complex relationships of DD statements with the SYSOUT keyword (referred to as SYSOUT DD), OUTPUT JCL statements, /*OUTPUT JES2 statements, /*ROUTE PRINT statements, and system defaults.

The DAL facilities and architecture give you complete control over job streams with a minimum of technical staff effort. As with all ThruPut Manager facilities, the best way to demonstrate the power and simplicity of SOS is with examples.

Some Hypothetical Job Streams

Here are two hypothetical jobs, taken from examples of SYSOUT processing in an IBM JCL User's Guide manual.

Example 1

This example shows an explicit reference to an OUTPUT JCL statement. Note that with an explicit reference, all default OUTPUT JCL statements are ignored.

//BILL002A JOB    ,’DEPT. 25’,USER=ACCT003
//OUT1     OUTPUT COPIES=1,DEST=COMPLEX1
//OUT2     OUTPUT COPIES=2,FORMS=A,DEFAULT=YES,DEST=COMPLEX7
//STEP1    EXEC   PGM=COLLECT
//OUT3     OUTPUT DEFAULT=YES,COPIES=1,DEST=COMPLEX7
//INPUT    DD     DSN=BILL,DISP=SHR
//MFK1     DD     SYSOUT=A
//MFK2     DD     SYSOUT=B,OUTPUT=*.OUT1
//

In this example:

• The system processes the output from DD statement MFK1 using the options on the OUTPUT statement OUT3 because:
  • MFK1 does not contain an OUTPUT parameter, and
  • OUT3 contains DEFAULT=YES and precedes MFK1 in the same step.
• MFK1 cannot implicitly reference the job-level default statement OUT2 because of the step-level default statement OUT3. If STEP1 had not contained OUT3, MFK1 would have referenced statement OUT2.
• The system processes the output from DD statement MFK2 according to the processing options on the job-level OUTPUT JCL statement OUT1 because DD statement MFK2 explicitly references OUT1 using the OUTPUT parameter.
• Note that the system ignores the processing options on all default OUTPUT JCL statements (OUT2 and OUT3) for MFK2.

Example 2

This example shows how the position of the OUTPUT JCL statement affects the processing of the SYSOUT data sets.

//BILL003A JOB    MSGCLASS=A,USER=ACCT005
//OUT1     OUTPUT DEFAULT=YES,DEST=COMPLEX7,FORMS=BILLING,
// CHARS=(AOA,AOB),COPIES=2
//OUT2     OUTPUT DEFAULT=YES,DEST=COMPLEX1,...
//STEP1    EXEC   PGM=ORDERS
//R1       DD     SYSOUT=A
//R2       DD     SYSOUT=B
//STEP2    EXEC   PGM=BILLING
//OUT3     OUTPUT DEFAULT=YES,DEST=COMPLEX7,...
//B1       DD     SYSOUT=A
//B2       DD     SYSOUT=B,OUTPUT=(*.OUT3,*.OUT2)
//STEP3    EXEC   PGM=REPORTS
//OUT4     OUTPUT FORMS=SHORT,DEST=COMPLEX1,...
//RP1      DD     SYSOUT=B
//RP2      DD     SYSOUT=A,OUTPUT=(*.STEP2.OUT3,*.OUT1)
//

• DEFAULT=YES is specified on OUTPUT JCL statements OUT1 and OUT2, and
• There is no OUTPUT JCL statement with DEFAULT=YES within STEP1, and
• The OUTPUT parameter is not specified on DD statements R1 and R2.

In STEP2, the system processes DD statement B1 using the processing options specified on OUTPUT JCL statement OUT3 because:

• DEFAULT=YES is specified on OUTPUT JCL statement OUT3 and OUTPUT JCL statement OUT3 is within the job step STEP2, and
• The OUTPUT parameter is not specified on DD statement B1, and
• OUTPUT JCL statement OUT3 is within STEP2; therefore, the system ignores the DEFAULT=YES specification on job-level OUTPUT JCL statements OUT1 and OUT2 when processing DD statement B1.

In STEP2, the system processes DD statement B2 using the processing options specified on OUTPUT JCL statements OUT3 and OUT2 because:

• Both of the OUTPUT JCL statements are explicitly referenced from the SYSOUT statement. Explicitly-referenced OUTPUT JCL statements can be in any previous procedure or step, before the DD statement in the current step, or at the job-level.
• Note that default OUTPUT JCL statement OUT1 is ignored when processing the data set defined by DD statement B2 because B2 explicitly references OUTPUT JCL statements OUT3 and OUT2.

In STEP3, the system processes DD statement RP1 using the output processing options specified on the job-level OUTPUT JCL statements OUT1 and OUT2 because:

• DEFAULT=YES is specified on OUTPUT JCL statements OUT1 and OUT2, and
• No OUTPUT JCL statement with DEFAULT=YES is coded within STEP3, and
• The OUTPUT parameter is not specified on DD statement RP1.

In STEP3, DD statement RP2 is processed using OUTPUT statements OUT3 and OUT1. You can explicitly reference an OUTPUT JCL statement in another step if you use a fully qualified reference, such as the reference to OUTPUT statement OUT3 used on DD statement RP2.

You can explicitly reference an OUTPUT JCL statement with DEFAULT=YES coded, such as the reference to OUT1 from DD statement RP2. The system ignores the DEFAULT parameter and uses the remaining processing options according to the normal rules that apply when coding explicit references.

Altering the Job Streams

Altering the above JCL streams (or any other) to make adjustments for SYSOUT data set printing services can be done in one of three ways:

• You can modify the actual JCL.
• You can implement JES2 Exit 40.
• In some cases, you can achieve the desired effects by changing the definitions of workload selection rules for different printers.

Regardless of the method used to alter SYSOUT processing, you must understand the relationships. You can make only simple changes without considerations for potential "side effects."

SOS provides an approach that isolates changes, so the person implementing the alterations does not have to consider any indirect consequences. The concept is simple:

• The SYSOUT DD statement is the anchor. It represents the mechanism for the creation of data. A SYSOUT DD statement represents the basic report. It produces results whether or not an OUTPUT JCL statement is present.
• The OUTPUT JCL statements are viewed as distribution requests. By themselves, they mean nothing.
• SYSOUT DD statements cannot be added or deleted "externally" to job streams. Creating a "new" SYSOUT requires programming changes.
• OUTPUT JCL statements can be added or deleted "externally". They do not require programming changes.
• Each pair of SYSOUT DD and an applicable OUTPUT JCL statement constitutes a SYSOUT data set.
• SOS presents you with each SYSOUT data set for potential alteration. If you request any changes, the necessary actions are taken to localize them to that particular SYSOUT DD/OUTPUT JCL pairing. If necessary, a new OUTPUT JCL statement is created to generate the desired results without creating any unexpected "side-effects."

All SOS actions take place after the effects of any SYSOUT JCL statements or /*OUTPUT JECL statements have been applied, but before the job executes.

With this simple approach in mind, let us look again at our two examples. First, note the different SYSOUT data sets that are created by the system.

Example 1

//BILL002A  JOB    ,’DEPT. 25’,USER=ACCT003
//OUT1      OUTPUT COPIES=1,DEST=COMPLEX1
//OUT2      OUTPUT COPIES=2,FORMS=A,DEFAULT=YES,DEST=COMPLEX7
//STEP1     EXEC   PGM=COLLECT
//OUT3      OUTPUT DEFAULT=YES,COPIES=1,DEST=COMPLEX7
//INPUT     DD     DSN=BILL,DISP=SHR
//MFK1      DD     SYSOUT=A
//MFK2      DD     SYSOUT=B,OUTPUT=*.OUT1
//

In the above example, using the SYSOUT DD as the anchor, we have the following SYSOUT data sets created by the system:

• MFK1: This is the result of the following pair:
  MFK1 DD SYSOUT
  OUT3 OUTPUT JCL
• MFK2: This is the result of the following pair:
  MFK2 DD SYSOUT
  OUT1 OUTPUT JCL

This is a simple case. Note that:

• OUT2 is an irrelevant statement.
• This cannot be established by looking at the statement in isolation.
• Any changes to that statement will produce no results.

Now let us look at the second example. Here things get a little more interesting.

Example 2

//BILL003A JOB    MSGCLASS=A,USER=ACCT005
//OUT1     OUTPUT DEFAULT=YES,DEST=COMPLEX7,FORMS=BILLING,
// CHARS=(AOA,AOB),COPIES=2
//OUT2     OUTPUT DEFAULT=YES,DEST=COMPLEX1,...
//STEP1    EXEC   PGM=ORDERS
//R1       DD     SYSOUT=A
//R2       DD     SYSOUT=B
//STEP2    EXEC   PGM=BILLING
//OUT3     OUTPUT DEFAULT=YES,DEST=COMPLEX7,...
//B1       DD     SYSOUT=A
//B2       DD     SYSOUT=B,OUTPUT=(*.OUT3,*.OUT2)
//STEP3    EXEC   PGM=REPORTS
//OUT4     OUTPUT FORMS=SHORT,DEST=COMPLEX1,...
//RP1      DD     SYSOUT=B
//RP2      DD     SYSOUT=A,OUTPUT=(*.STEP2.OUT3,*.OUT1)
//

Again using the SYSOUT DD anchor concept, we have the following SYSOUT data sets.

From R1:

• R1-01. This is the result of the following pair:
  R1 DD SYSOUT
  OUT1 OUTPUT JCL
• R1-02. This is the result of:
  R1 DD SYSOUT
  OUT2 OUTPUT JCL
  
  

Next, from R2:

• R2-01 as a result of
  R2 DD SYSOUT
  OUT1 OUTPUT JCL
• R2-02. as a result of:
  R2 DD SYSOUT
  OUT2 OUTPUT JCL

Next, from B1:

• B1 as a result of:
  B1 DD SYSOUT
  OUT3 OUTPUT JCL

Next, from B2:

• B2-01 as a result of:
  B2 DD SYSOUT
  OUT3 OUTPUT JCL
• B2-02 as a result of:
  B2 DD SYSOUT
  OUT2 OUTPUT JCL

Next, from RP1:

• RP1-01 as a result of:
  RP1 DD SYSOUT
  OUT1 OUTPUT JCL
• RP1-02 as a result of:
  RP1 DD SYSOUT
  OUT2 OUTPUT JCL

Next, from RP2:

• RP2-01 as a result of:
  RP2 DD SYSOUT
  OUT3 OUTPUT JCL
• RP2-02 as a result of:
  RP2 DD SYSOUT
  OUT1 OUTPUT JCL

A few things to notice:

• There is a total of 4 OUTPUTJCL statements and 6 SYSOUTDDstatements.
• 11 SYSOUT data sets will be generated.
• The OUTPUT statement OUT4 is irrelevant.
• Sometimes the same OUTPUT statement is implicitly and explicitly referenced.

The number of permutations and combinations that can be created in any particular job stream is endless, and the scope of any particular OUTPUT JCL statement is extremely difficult to determine for any "large" job.

A More Complex Example

• Any SYSOUT data set with a destination of COMPLEX7 is to change to COMPLEX3.
• Any SYSOUT data set with CLASS B is to have only 1 COPY.
• Any SYSOUT data set with CLASS B is to have a destination of COMPLEX1.

You probably know how much effort it is to do this in your installation without the help of SOS. Let us show you how easily you would do this with SOS.

In a ThruPut Manager environment with the SOS option, you create DAL for SOS to handle the above situation. In the definition section of SOS DAL, you use the definition statements shown here.

EVALUATE   JOB_TO_CHANGE    ($JOBNAME(BILL*) & ($RACFU(ACC*))
EVALUATE   IGNORE_JOB       (JOB_TO_CHANGE)
EVALUATE   B_CLASS          ($SOS_CLASS(B))
EVALUATE   WRONG_DEST       ($SOS_DEST(COMPLEX1))
EVALUATE   DEST_COMPLEX7    ($SOS_DEST(COMPLEX7))
$SOS_COPIES SINGLE_COPY,2,MULTIPLE_COPIES

In this example:

• The first statement identifies jobs that you are interested in changing.
• The second statement identifies jobs to eliminate from SOS processing.
• The third statement identifies SYSOUT data sets with a class of B.
• The fourth statement identifies SYSOUT data sets with a destination other than COMPLEX1.
• The fifth statement identifies SYSOUT data sets with a destination of COMPLEX7.
• The sixth statement identifies SYSOUT data sets with a request for multiple copies.

Now, to request the changes, you code the following logic and action statements:

IF (IGNORE_JOB)
   RETURN DONE
ENDIF

IF (B_CLASS)
   IF (WRONG_DEST)
      SOS ALTER DEST(COMPLEX1)
   ENDIF
   IF (MULTIPLE_COPIES)
      SOS ALTER COPIES(1)
   ENDIF
RETURN CONTINUE
ENDIF

IF (DEST_COMPLEX7)
   SOS ALTER DEST(COMPLEX3)
ENDIF
RETURN CONTINUE
END

This is all there is to it, unless you want to be informative and tell the job submitter about all the wonderful changes that you are making. You can do this with the message facilities of DAL. SOS issues a message informing the user which statements your DAL has altered, unless you turn the feature off:

Below is a complete SOS DAL, including informative messages.

PROC ID(DAL)  TYPE(SOS)  DESC(‘SAMPLE SOS DAL’)
EVALUATE      JOB_TO_CHANGE  ($JOBNAME(BILL*) & $RACFU(ACC*))
EVALUATE      IGNORE_JOB     (JOB_TO_CHANGE)
EVALUATE      B_CLASS        ($SOS_CLASS(B))
EVALUATE      WRONG_DEST     ($SOS_DEST(COMPLEX1))
EVALUATE      DEST_COMPLEX7  ($SOS_DEST(COMPLEX7))
$SOS_COPIES SINGLE_COPY,2,MULTIPLE_COPIES

MSGDEF COPIES_ALTERED (‘SYSOUT STMT# ‘,$JCL_STMT#,’ AND OUTPUT JCL ‘,   +
                      ‘STMT# ‘,$SOS_OUTPUTJCL_STMT#,’ COPIES ‘,         +
                      ‘CHANGED FROM ‘,$SOS_COPIES,’ TO 1 BECAUSE OF
CLASS=B’)
MSGDEF DEST_ALTER_TO1 (‘SYSOUT STMT# ‘,$JCL_STMT#,’ AND OUTPUT JCL ‘,   +
                      ‘STMT# ‘,$SOS_OUTPUTJCL_STMT#,’ DESTINATION ‘,    +
                      ‘CHANGED FROM ‘,$SOS_DEST,’ TO COMPLEX1 BECAUSE OF+
                       CLASS=B’)
MSGDEF DEST_ALTER_TO3 (‘SYSOUT STMT# ‘,$JCL_STMT#,’ AND OUTPUT JCL ‘,   +
                      ‘STMT# ‘,$SOS_OUTPUTJCL_STMT#,’ DESTINATION ‘     +
                      ‘CHANGED FROM ‘,$SOS_DEST,’ TO COMPLEX3’)

IF (IGNORE_JOB)
   RETURN DONE        /*SOS DAL IS NOT CALLED AGAIN FOR THIS JOB */
ENDIF
IF (B_CLASS)
   IF (WRONG_DEST)
      SOS ALTER DEST(COMPLEX1)
      WTU DEST_ALTER_TO1
   ENDIF
   IF (MULTIPLE_COPIES)
      SOS ALTER COPIES(1)
      WTU COPIES_ALTERED
   ENDIF
   RETURN CONTINUE
ENDIF
IF (DEST_COMPLEX7)
   SOS ALTER DEST(COMPLEX3)
   WTU DEST_ALTER_TO3
ENDIF
RETURN CONTINUE
END

Results of SOS Processing

In the following examples, we show certain OUTPUT JCL statements underlined. These statements are intended to illustrate the results of DAL processing. They do not actually appear in the JCL listing for the jobs.

Let us look at the two sample jobs SOS presents to the system after it finishes processing. The first job is a simple case:

//BILL002A JOB    ,’DEPT. 25’,USER=ACCT003
//OUT1     OUTPUT COPIES=1,DEST=COMPLEX1
//OUT2     OUTPUT COPIES=2,FORMS=A,DEFAULT=YES,DEST=COMPLEX7
//STEP1    EXEC   PGM=COLLECT
//$TM0001 OUTPUT COPIES=1,DEST=COMPLEX3
//OUT3     OUTPUT DEFAULT=YES,COPIES=1,DEST=COMPLEX7
//INPUT    DD     DSN=BILL
//MFK1     DD     SYSOUT=A,OUTPUT=*.$TM0001
//MFK2     DD     SYSOUT=B,OUTPUT=*.OUT1
//

In this case, only one OUTPUT JCL statement has to be created.

The second job is more interesting, and is illustrated below. Please note that this is shown here to give you a conceptual understanding about the workings of SOS. The actual internal implementation details shown here need not concern the implementer of SOS rules.

As before, the created OUTPUT JCL statements are shown underlined.

//BILL003A JOB    MSGCLASS=A,USER=ACCT005
//OUT1     OUTPUT DEFAULT=YES,DEST=COMPLEX7,FORMS=BILLING,
// CHARS=(AOA,AOB),COPIES=2
//OUT2     OUTPUT DEFAULT=YES,DEST=COMPLEX1,...
//STEP1    EXEC   PGM=ORDERS
//$TM0001  OUTPUT DEST=COMPLEX3,FORMS=BILLING,
//                CHARS=(AOA,AOB),COPIES=2
//$TM0002  OUTPUT DEST=COMPLEX1,...
//$TM0003  OUTPUT DEST=COMPLEX1,FORMS=BILLING,
//                CHARS=(AOA,AOB),COPIES=1
//$TM0004  OUTPUT DEST=COMPLEX1,...
//R1       DD     SYSOUT=A,OUTPUT=(*.$TM0001,*.$TM0002)
//R2       DD     SYSOUT=B,OUTPUT=(*.$TM0003,*.$TM0004)
//STEP2    EXEC   PGM=BILLING
//OUT3     OUTPUT DEFAULT=YES,DEST=COMPLEX7,...
//$TM0005  OUTPUT DEST=COMPLEX3,...
//$TM0006  OUTPUT DEST=COMPLEX1,...
//$TM0007  OUTPUT DEST=COMPLEX1,...
//B1       DD     SYSOUT=A,OUTPUT=*.$TM0005
//B2       DD     SYSOUT=B,OUTPUT=(*.$TM0006,*.$TM0007)
//STEP3    EXEC   PGM=REPORTS
//OUT4     OUTPUT FORMS=SHORT,DEST=COMPLEX1,...
//$TM0008  OUTPUT DEST=COMPLEX1,FORMS=BILLING,
//                CHARS=(AOA,AOB),COPIES=1
//$TM0009  OUTPUT DEST=COMPLEX1,...
//$TM0010  OUTPUT DEST=COMPLEX3,...
//$TM0011  OUTPUT DEST=COMPLEX3,FORMS=BILLING,
//                CHARS=(AOA,AOB),COPIES=2
//RP1      DD     SYSOUT=B,OUTPUT=(*.$TM0008,*.$TM0009)
//RP2      DD     SYSOUT=A,OUTPUT=(*.$TM0010,*.$TM0011)
//

Implementation Summary

SOS is part of the Base Product ThruPut Manager, therefore there are no special implementation procedures required. Here is a summary of some of the areas to consider when dealing with SOS.

System-managed Data sets

As indicated above, the architecture of SOS is based on the idea that the SYSOUT DD statement is the anchor that drives the DAL process. There is an exception to this rule.

The OUTPUT JCL statement allows you to control the printing characteristics of the "system-managed data sets": the JCL listing, the LOG, and the system messages for the job. There is no corresponding SYSOUT DD statement for each of these listings. SOS handles this situation by "driving" DAL once for each JES data set to be generated.

A Unique variable, $SOS_SYSOUT_DS, indicates whether or not you are processing a system-managed SYSOUT data set or a regular SYSOUT data set. If it is a system-managed SYSOUT data set, then you can also determine which type. You can alter the characteristics of any one of them.

 /*OUTPUT JECL Statement

In the examples, the /*OUTPUT statement is not shown. SOS handles job streams that include that type of statement alone or in conjunction with OUTPUT JCL statements. The most obvious difference in the way the system processes OUTPUT JCL and /*OUTPUT JECL statements is in the "override" parameter considerations.

In general, with OUTPUT JCL statements the SYSOUT DD has the last word. The opposite is true with the /*OUTPUT JECL statement. SOS solves this as follows:

• The SYSOUT DD statement becomes a skeleton statement with a minimum of parameters.
• The parameters are all transferred to the inserted OUTPUT JCL statement. This takes place regardless of the "pair" being processed. That is, the same construct takes place for a (SYSOUT DD)/(OUTPUT JCL) as for a (SYSOUT DD)/ (/*OUTPUT) pair. All the alterations result from an inserted OUTPUT JCL statement.

Removing SYSOUT Data sets

The deletion (or negation) of a SYSOUT data set can be accomplished by setting the OUTDISP to (PURGE,PURGE). SOS provides a simpler technique, however: the SOS ALTER REMOVE statement.

Adding SYSOUT Data sets

The creation of a new SYSOUT data set is the result of inserting an additional OUTPUT JCL statement. You can also insert additional OUTPUT JCL statements by re-driving SOS DAL. The RETURN statement in SOS DAL supports the REDRIVE keyword, which causes ThruPut Manager to re-invoke SOS DAL for the current SYSOUT data set. The COUNT keyword repeats the re-driving until a specified number of OUTPUT JCL statements have been inserted.

SOS Logging

By default, SOS records (in the system messages for the job) the SYSOUT DD statement numbers for which alterations were requested. In this way there is an indication

that changes have taken place. You can turn off this logging with the statement SOS SET DO_NOT_LOG_ALTERS.

If you want to provide detailed information about the changes, use the message construct facilities of SOS.

Dependencies

SOS is integrated into ThruPut Manager and has no other dependencies.

Facilities Summary