Passing Files to Entire Output Management

You can define and pass job SYSOUT and/or one or more other files (for example, output files of a job) to Entire Output Management (NOM) to further process the output in this environment.

This document covers the following topics:


Basic Requirements for File Transfers to Entire Output Management

This section describes the requirements for transferring files from Entire Operations to Entire Output Management.

  1. An NTLFILE or LFILE definition for the Entire Output Management system file must be entered in the start parameters for System Automation Tools or Entire Operations. For further information, see the section Installing Entire Operations on Mainframes and UNIX in the Installation and Setup documentation.

  2. If Entire Output Management (LFILE 206) is defined, and if the Entire Operations Monitor receives a NAT0082 message calling the Entire Output Management API, the message NOM Trigger interface not active will be written to log before Entire Operations task restart. Subsequent attempts to pass SYSOUT to Entire Output Management will be ignored with the message Passing to NOM impossible.

  3. If SYSOUT or another file cannot be passed to the Entire Output Management API, the Entire Output Management API calls for a job to be retried. Check the Entire Operations log for more detailed error information.

  4. In Entire Output Management, the report name is EOR-SOUT.

  5. For UNIX and Windows, refer to Passing SYSOUT from UNIX and Windows Nodes to Entire Output Management.

See also:

Listing Files Defined for Entire Output Management

Start of instruction set To list files defined for processing with Entire Output Management

  1. Select a job and open the End-of-Job Checking + Actions screen.

    The letter T in the Action column indicates that an EOJ (End-of-Job) action for Entire Output Management exists:

     17.04.16                ***** Entire Operations *****                18:02:27 
     Owner REQUEST    Network P106270    Version                     Job J-1       
     End-of-Job Checking + Actions  MVS/ESA               Run       Date           
     ------------------------------------------------------------------------------
     C Action       Step       will be checked for                         means OA
     _         T               Additional Actions for Job-ok                ok     
                                                                                   
                                                                                   
                                                                                   
                                                                                   
                                                                                   
                                                                                   
                                                                                   
     ******************************* Bottom of Data *******************************
     _         T X  All Checks ok                                                  
     _         T    Any Check not ok                                               
     ------------------------------------------------------------------------------
     A Activat. C Cond.  D Delete  E Edit Exit   J JV  L Rel Res  M Modify  O Other
     P Descr. R Recov. S SYSOUT T Output Mgmt U User Msg X Action Exit Y Symbol Set
                                                                                   
     Command => ____________________________________________________________       
                                                                                   
                                                                                   
    Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
          Help  Add   End         Save        Up    Down                    Menu

    See also End-of-Job Checking and Actions Screen in the section Defining and Managing End-of-Job (EOJ) Checking and Actions.

  2. On the End-of-Job Checking + Actions screen, type T (Output Mgmt) in the All checks ok or Any check not ok line command field, and press ENTER.

    If you select All checks ok, a Files for Entire Output Management window similar to the example below opens:

     17.04.16                ***** Entire Operations *****                17:51:35 
     Owner REQUEST    Network P106270    Version                     Job J-1       
     End-of-Job Checking + Actions  MVS/ESA               Run       Date           
     ------------------------------------------------------------------------------
     C Acti +--------------------------------------------------------------------+ 
     _      |                                                                    | 
            |   Job ended ok                                                     | 
            |                  Files for Entire Output Management                | 
            |   Cmd File                                                         | 
            |    _  SYSOUT A 1                                                   | 
            |    _  HUGO.HUGO.HUGO                                               | 
            |    _  SYSOUT SO 3                                                  | 
            |    _  Procname PROC Stepname STEP DDName DD                        | 
     ****** |    _  @EUMEL..TEST                                                 | 
     t      |    _  SYSOUT SO 4                                                  | 
     _      |    _  Procname XXX Stepname YYY DDName ZZZ                         | 
     ------ |    _  TEST.TEST.TEST                                               | 
     A Acti |                                                                    | 
     P Desc |                                                                    | 
            |    D Delete  M Modify                                              | 
     Comman |   Enter---PF1---PF2---PF3---PF5----------------------------------  | 
            |           Help  Add   End   Save                                   | 
            +--------------------------------------------------------------------+ 
    
                                                                                   
    Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
          Help  Add   End         Save        Up    Down                    Menu

    This window contains a list of all files to be handled by Entire Output Management.

Line Commands
Command Description
D Delete a file definition.
M Modify a file definition.

Depending on the definition, a Spool File or an Output File definition window opens.

Special PF Key
PF Key Description
PF2 Add a file definition for Entire Output Management.

For mainframe execution nodes, a selection window opens.

For UNIX and Windows nodes, an Output File definition window opens directly.

Adding and Modifying File Definitions

This section provides instructions for adding and modifying file definitions for processing in Entire Output Management.

Note:
The number of files you can define per job event is limited to 10. If you want to specify more than 10 files for a job, define one or more additional events of the type A (Add. Job-ok,-not-ok), and define the extra files for these events.

Start of instruction set To add a file definition

  1. In the Files for Entire Output Management window, choose PF2 (Add).

    A window similar to the example below opens:

    +------------------------------------------------------+
    |                                                      |
    |  Additional Actions for Job-ok                       |
    |     File Definition for Output Management (NOM)      |
    |                                                      |
    |     Please select:                                   |
    |           Spool  File Definition   ==> _             |
    |           Output File Definition   ==> _             |
    |                                                      |
    |  ---------PF3--------------------------------------  |
    |           End                                        |
    +------------------------------------------------------+
  2. Select Spool File Definition or Output File Definition by entering any character in the appropriate field, and press ENTER.

    Depending on the option selected, one of the following windows opens:

    For a spool file definition:

    +--------------------------------------------------+
    |                                                  |
    |  Additional Actions for Job-ok                   |
    |     File Definition for Output Management (NOM): |
    |                    Spool File                    |
    |                                                  |
    |    Operating System  ==> MVS/ESA                 |
    |    Spool Type        ==> JES2                    |
    |                                                  |
    |  Please specify either                           |
    |    Spool File Type   ==> __                      |
    |    Spool File Number ==> _____                   |
    |                                                  |
    |  or                                              |
    |    Procname          ==> ________                |
    |    Stepname          ==> ________                |
    |    DD  Name          ==> ________                |
    |                                                  |
    |  ---PF1---PF3----------------------------------- |
    |     Help  End                                    |
    +--------------------------------------------------+

    For an output file definition:

    +----------------------------------------------------------------------+ 
    |                                                                      | 
    |  Occurrence of String 'INVALID RESPONSE-CODE'                        | 
    |             File Definition for Output Management (NOM):             | 
    |                     Output File (sequential file)                    | 
    |                                                                      | 
    |  Operating System ==> MVS/ESA                                        | 
    |                                                                      | 
    |  File    ==> ANY.TEST.FILE_________________________________________  | 
    |  CC Type ==> _      PName ==> ________                               | 
    |  VolSer  ==> ______ Recfm ==> __ Lrecl ==> _____ Blksize ==> _____   | 
    |                                                                      | 
    |  Execute if temp. Dummy ==> Y  Pass to OPO ==> N                     | 
    |                                                                      | 
    |  ----PF1----PF3----------------------------------------------------  | 
    |      Help   End                                                      | 
    +----------------------------------------------------------------------+

    In this window you can define an output file of the job to be handled.

    The input fields are described in Fields: Output File Parameter Definitions.

  3. Enter the required definitions and press ENTER.

  4. Choose PF3 to close the window.

    You return to the Files for Entire Output Management window where the new file definition is listed.

Start of instruction set To modify a file definition

Fields: Spool File Definition

The input fields required to define a file of the job SYSOUT to be handled are provided in the Spool File window.

Field Description
Operating System (Output field only)

Operating system of the node on which the selected job runs.

Spool Type (Output field only)

Spool type (POWR, JES2, JES3).

Spool file type Spool file type, for example, SO for JES SYSOUT.
Spool file number (Not required for z/VSE)

Spool file number.

Procname PROCNAME that identifies the file.
Stepname STEPNAME that identifies the file.
DD name DD name that identifies the file.

For more information on spool file types and report identification, see Attributes of a Report in the section Reports of the Entire Output Management User's Guide.

Fields: Output File Parameter Definitions

The fields available to define an output file of the job to be handled are described in the following table.

The fields are provided in the Output File (sequential file) window.

Field Description
Operating System (Output field only)

Operating system of the node on which the selected job runs.

Spool Type (Output field only)

Spool type (POWR, JES2, JES3).

File File to be passed to Entire Output Management.

If the file name contains the activation escape character, a symbol replacement is performed, using the job's active symbol table.

If the file name contains the submission escape character, a symbol replacement is performed using the job's active symbol table.

By using a wildcard in the file name, you may pass all files to Entire Output Management at once, which are matching the wildcard.

CC Type Not applicable to z/OS.

Carriage control type.

If the file contains carriage control characters, you must specify their type: see Carriage Control Type (CC Type).

PName Applies to BS2000 only.

If you want to identify the job by the PNAME option of the BS2000 print command (/Print ...,PNAME=ADAREP), enter the PNAME here.

VolSer For z/VSE, these fields are obligatory.

Information required to allocate the data set/file:

Volume serial number (Blksize), record format (Recfm), record length (Lrecl) and the block size (Blksize) of the file/data set.
Recfm
Lrecl
Blksize
Execute if temporary Dummy If Y is entered here (this is the default), the End-of-Job action is performed even if the job executed as a temporary dummy.

If this field is set to N, the action is not performed.

Pass to OPO Relevant for execution nodes on UNIX and Windows only.

If Y is entered here, the file is passed to the Open Print Option (OPO). In this case, you cannot use wildcards.

Passing files to OPO is not performed by default.

Notes:

  1. Entire System Server/UNIX performs wildcard file copying by invocation of a cp (UNIX) or copy (Windows) command, instead of performing the copy by own code.
  2. All file copying is performed synchronously.
  3. Make sure not to copy too many files at once, due to the limitation of the EntireX Broker timeout, etc.

Normally Entire Output Management identifies report definitions by spool attributes. However, if Entire Operations triggers processing of output files, no such spool attributes exist. Instead, Entire Operations attributes are passed to Entire Output Management as follows:

Entire Operations
Attribute

Entire Output Management Identification
  z/OS  z/VSE  BS2000
JOBNAME Job name Job name PNAME
USER ID Destination Destination User ID
Carriage Control Type (CC Type)

You must specify a carriage control (CC) type for the output file depending on your operating system and the catalog entries contained in the file catalog.

No specification is required in z/OS, where the carriage control type is taken from the file's catalog entry.

Operating System CC Type Setting Explanation
BS2000  blank If the file was created with RECFORM=(...,M) or =(...,A), CC type can be taken from the file's catalog entry; otherwise, it must be specified in the CC Type field.
A ASA code
M Machine code
E BS2000 EBCDIC carriage control characters
z/VSE  A ASA code
M Machine code
z/OS blank CC type not required

Deleting File Definitions

You can delete single or multiple file definition for Entire Output Management by either deleting the EOJ (End-of-Job) action that corresponds to the file definition(s), or by deleting a single file defined for the EOJ action.

Start of instruction set To delete an entire EOJ action

  1. On the End-of-Job Checking + Actions screen, enter the line command D next to the action which contains the file definitions for Entire Output Management, and press ENTER.

    A confirmation window opens.

  2. Enter Y (Yes) to confirm the deletion.

    The EOJ action with all file definitions for Entire Output Management is deleted.

Start of instruction set To delete single files defined for an EOJ action

  1. On the End-of-Job Checking + Actions screen, enter the line command T next to the action which contains the file definitions for Entire Output Management you want to delete, and press ENTER.

    Depending on where you enter the T command (above or below Bottom of Data),

    An Additional Actions for Job-ok window or Job ended ok/Job ended not ok with a list of files defined for Entire Output Management opens.

  2. Enter the line command D next to the file you want to delete, and press ENTER.

    A confirmation window opens.

  3. Enter Y (Yes) to confirm the deletion.

Handing Over SYSOUT and Files to Entire Output Management

This section covers the following topics:

Repetition if File is missing or open

If the file to be handed over did not (yet) exist or was (not) yet closed, the handover will be retried.

The following rules apply:

Case Retries Interval between retries
Output file cannot be found

(does not apply to spool files)

3 5 minutes
All other cases 1000 30 minutes

The retry queue will not be deleted in case of a Monitor shutdown and restart.

Copying Files before passing them to Entire Output Management

In the default settings, you can define that the SYSOUT files are copied physically before handover to Entire Output Management.

The advantage of this is that exclusive use (as well as renaming and deleting) of the copy by Entire Output Management can still be looked at in Entire Operations. This, however, means that SYSOUT files need more space.

File Copy to another Entire System Server Node

Under the following conditions, the SYSOUT copy is created on another node:

  • The symbol SYSOUT-NODE-GLOBAL exists in the symbol table SYSDBA/A and contains a valid node number.

  • In the target environment, the same PubIDs and BS2000 user IDs exist as in the source environment.

Connection with Defined Recovery Action

Defined recovery actions for an erroneous job are only executed, after all activities for the handover of the SYSOUT to Entire Output Management have been concluded, or after the maximum number of handover tries has been reached.

In case of a recovery action, the SYSOUT of all job runs are handed over to Entire Output Management. For further information, see Defining Recovery Actions in the section Defining and Managing End-of-Job (EOJ) Checking and Actions.

SYSOUT Line Limit

If the SYSOUT file or spool data set exceeds a given line limit, the copied file will be truncated: see SYSOUT Line Limit in Default Setting (4) in the Administration documentation.

Passing SYSOUT from UNIX and Windows Nodes to Entire Output Management

On UNIX and Windows, the environment variable EOR_NOM must be defined. It must contain a valid directory name. Entire Operations copies the SYSOUT files for Entire Output Management into this directory. If the directory does not exist, Entire System Server/UNIX (Entire System Server/Windows) creates it at the first usage attempt.

Start of instruction setTo define the copying of SYSOUT to Entire Output Management

  1. On the End-of-Job Checking + Actions screen, enter the line command S next to the required action, and press ENTER.

    The SYSOUT Actions window opens.

  2. Enter the line command O to select the option Pass SYSOUT to Entire Output Mgmt. See also Defining SYSOUT Actions in the section Defining and Managing End-of-Job (EOJ) Checking and Actions.

This is a job-level definition that only applies to the selected job.

Entire Operations creates the SYSOUT file copies in this directory with unique names.

It is up to Entire Output Management to fetch the files from there.

Notes:

  1. If copied SYSOUT files are not fetched by Entire Output Management within the retention period for active jobs, they are removed by Entire Operations cleanup after that time.
  2. If the SYSOUT file or spool data set exceeds a given line limit, the copied file will be truncated: see SYSOUT Line Limit in Default Setting (4) in the Administration documentation.

Naming Rules for Files copied into the EOR_NOM Directory (UNIX and Windows)

SYSOUT Files

The file names for SYSOUT files for the $EOR_NOM directory have the following syntax:

dbid-fnr.owner.network.run.job.txt
File Name Meaning
dbid-fnr Concatenated DBID and FNR, 10 digits.
owner Owner of job.
network Network of job.
run Run number of job.
job Job.
Other Files

The file names for other files for the $EOR_NOM directory have the following syntax:

Format A with the components:

yymmdd.hhiisst.rrrrr.filename.ext
File Name Meaning
yymmdd Year, month, day.
hhiisst Time, incl. 1/10 sec.
rrrr Entire Operations run number, with leading zeros.
filename Unqualified part of original file name.
ext Extension of original file name.

Format B with the components:

yymmdd.hhiisst.rrrrr.job.ix
File Name Meaning
yymmdd Year, month, day.
hhiisst Time, incl. 1/10 sec.
rrrr Entire Operations run number, with leading zeros.
job Entire Operations job name.
ix Index of file definition in Entire Operations (2 digits).

Note:
Format B is used only if the length of filename.ext is longer than 20 characters, because of a size limitation in Entire Output Management.

Defining the Handover of SYSOUT Files from UNIX/Windows to BS2000

Start of instruction set To define the handover of SYSOUT files from UNIX or Windows to BS2000

  • In the SYSOUT Actions window, choose PF9 (ToMF).

    A SYSOUT Copy window similar to the following opens:

    +-------------------------------------------------------+
    |                                                       |
    |  SYSOUT Copy from UNIX / Windows to Mainframe         |
    |                                                       |
    |  Owner      SAGTEST       SYSOUT Node        31       |
    |  Network    MAIN1         SYSOUT Cat ID               |
    |  Run                      SYSOUT User ID    SAG       |
    |  Job        JOB-01                                    |
    |  Exec.Node    501                                     |
    |                                                       |
    |  Note: Please use Job Definition function 'Specials'  |
    |        (PF6) to modify the values                     |
    |                                                       |
    |  ---PF1---PF3---------------------------------------  |
    |     Help  End                                         |
    |                                                       |
    +-------------------------------------------------------+

    You can copy a UNIX or Windows SYSOUT file to a BS2000 system so that it can be handed over to the Output Management for instance.

    The SYSOUT node must differ from the execution node, and it must be a BS2000 node.

    The naming conventions for the copy are identical to the ones for SYSOUT files, which have been directly created on the mainframe. (Even exits for SYSOUT file names, which may be present, are run through.) SYSOUT copies are affected by the automatic file cleanup just as the original SYSOUT.

    The SYSOUT Copy window contains information fields only. You can modify a field value in the job master definition by using PF6 (Spec) as described in Defining Master JCL for a Job.

This section covers the following topics:

Accessing SYSOUT File Names in User Exits

You can retrieve the names of SYSOUT source files (on UNIX or Windows) and target files (on BS2000) for End-of-Job checking (EJC) and End-of-Job action (EJA) user exits (see also User Exits for End-of-Job Checking and Actions).

If you want to retrieve the file names, add the following to the definitions in the user exit:

  • For the SYSOUT source file:

    INDEPENDENT
      1 +P-SYSOUT-FILE-250         (A250)
  • For the SYSOUT target file:

    INDEPENDENT
      1 +P-SYSOUT-FILE-COPY-250    (A250)

For BS2000 target nodes, only the leading 54 bytes of the field are used.

Notes:

  1. Choose PF6 (Specials) on the Job Definition (Master) window to modify the values. See Defining Job Type Specific Execution Features in the section Job Maintenance.
  2. The application of this function means an additional working effort for the Entire Operations Monitor, which depends on the number of the handovers and on the size of the SYSOUT files.
  3. A log message is written at the beginning and at the end of a SYSOUT copy from UNIX or Windows to the mainframe.
  4. The resubmission of a job with an ongoing SYSOUT copy is inhibited.
  5. No SYSOUT copying will be attempted if the job has the type DUM (dummy) or if it is a temporary dummy job (see also Job Execution as a Dummy Job in the section System Overview).
  6. Both SYSOUT source and target file names can vary depending on the repeat count of the active job. Refer to the reserved symbol P-REPEAT-COUNT (alias P-REPEAT) described in Table of Predefined Symbols in the section Symbol Table and Symbol Maintenance.
  7. File truncation: If the SYSOUT file or spool data set exceeds a given line limit, the copied file will be truncated: see SYSOUT Line Limit in Default Setting (4) in the Administration documentation.

Field Descriptions

Field Meaning
SYSOUT Node  A valid Entire System Server node on BS2000. 
SYSOUT Cat ID  BS2000 Cat ID, which is to be used for the copied file (optional). 
SYSOUT User ID  BS2000 User ID, under which the copied SYSOUT file is to be generated.