Entire Operations Utilities

Entire Operations utilities are used to perform selected Entire Operations functions.

A utility is usually a standalone Natural program that runs either online or in batch mode when invoked by a Natural batch job.

This section covers the following topics: .

Introduction

Required LFILE Assignments

LFILE Explanation
216 Entire Operations System File 1.
131 System Automation Tools log file.
215 Entire Operations System File 3 (log selection file).

Log Selection File - Format 1

An empty log selection file (LFILE=215, NOP-LOG-SELECT-1) for accounting data is part of the Entire Operations installation files.

The DDM for the log selection file is EOR-LOG-SELECTION-1.

The DDM is delivered with descriptors on almost every field. It is up to the user to release descriptors which are not necessary.

The file can be read and evaluated with Natural.

DB 255, File 215

This file applies to the default sequence of the NOP-LOG-SELECT-1 file.

T L DB Name Format S D Remarks
* EOR Log Selection  
  1 AA LGS-RECORD-TYPE A6 N D  
*  
G 1 AB LGS-BS2-DATA        
  2 AD LGS-BS2-USERID A8 N D  
  2 AE LGS-BS2-ACCOUNT A8 N D  
*  
G 1 AG LGS-TIME-DATA        
  2 AH LGS-CPU-TIME P7.2 N D /* in seconds
  2 AI LGS-JOB-START T12 N D /* date + time
  2 A7 LGS-JOB-START-TIME-ZONE A10 N    
  2 AK LGS-JOB-STOP T12 N D /* date + time
  2 A8 LGS-JOB-STOP-TIME-ZONE A10 N    
  2 AM LGS-JOB-ELAPSED P13.0 N D /* in 1/10 seconds
*  
G 1 AN LGS-DATA-3        
  2 AO LGS-LOG-TIME T12 N D /* date + time
  2 BM LGS-LOG-MICROSECONDS P5.0 N    
  2 BP LGS-LOG-TIME-ZONE A10 N    
  2 AP LGS-OWNER A10 N D  
  2 AQ LGS-NETWORK A10 N D  
  2 AR LGS-RUN P13.0 N D  
  2 AS LGS-JOB A10 N D  
  2 AT LGS-STATE A3 N D  Possible content:
CHK Job to be checked
ACT Job is activated (active)
JNO Job ended not ok
JOK Job ended ok
  2 AU LGS-JOB-TYPE A3 N D  
*  
  1 AY LGS-EXECUTION-NODE-N5 N5.0 N D  
  1 AW LGS-JOB-ID A10 N D  
  1 AX LGS-OS-JOB-NAME A8 N D  
  1 AZ LGS-NETWORK-VERSION A10 N    
  1 A1 LGS-EXEC-OPSYS-CLASS A1 N   Possible content:
B BS2000
M z/OS
V z/VSE
X UNIX
W Windows
  1 A2 LGS-SUBMIT-USERID A50 N    
  1 A3 LGS-SUBMIT-GROUP A50 N    
  1 A4 LGS-REPEAT-COUNT P13.0 N    
  1 A5 LGS-SPECIAL-TYPE A8 N    
  1 A6 LGS-DUMMY-FLAGS A8 N   Contains the reason(s), why an active job is a (temporary) dummy job.

One or more (in arbitrary order) of the following flags are possible:

C Condition
D Definition (job type DUM)
E Empty JCL
J JCL check
K Job to be deactivated
M Multiple suffix
R Recovery
S Schedule
T Repetition
*  
* Superdescriptors  
*  
  1 AV LGS-KEY-1 A30 N S  
*     LGS-OWNER 1-10      
*     LGS-NETWORK 1-10      
*     LGS-JOB 1-10      

Extract Log Data to Log Selection File

Natural Program Call

LGAX1S-P P-DATE-FROM P-DATE-TO

Parameters

Name Format Description
P-DATE-FROM

(optional)

 A8 Start date for the extraction in format YYYMMDD.
P-DATE-TO

(optional)

 A8 End date for the extraction in format YYYMMDD.

Notes:

  1. Start date and end date for the extraction are optional. If wanted, both parameters must be set. If the start date is smaller than the time stamp in the private control record (see note 2 and 3), the extraction is not performed.
  2. Log data extraction always starts where the last extraction ended.
  3. This time stamp is kept in a private control record. (When the program is started for the first time, the start date 01.11.2001 is used.)
  4. The extraction data consists of job accounting data (see Example of Accounting Information in the section Reporting).
  5. New extraction data do not overwrite existing extraction data.

Delete Old Data in Log Selection File

Natural Program Call

LGAX1D-P  P-RETENTION-DAYS

Parameters

Name Format Description
P-RETENTION-DAYS I2 Entries older than this parameter are deleted.

Print Account Information from Entire Operations Log

Natural Program Call

LG-AP1-P  P-TIME-FROM  P-TIME-TO

Parameters

Name Format Description
P-TIME-FROM A14 Format: YYYYMMDDHHIISS
P-TIME-TO A14 Format: YYYYMMDDHHIISS

Mass Change of Network / Symbol Table Version

Natural Program Call

OV-MB--P
P-OBJECT-TYPE P-OBJECT-OWNER P-OBJECT-NAME P-OLD-OBJECT-VERSION P-NEW-OBJECT-VERSION P-ALLOW-UPD

Depending on the settings of the Natural parameter ID, parameters may need to be comma separated instead of using blanks.

Parameters

Name Format Description
P-OBJECT-TYPE A2 Object type:
NV Network Version.
SV Symbol Table Version.
P-OBJECT-OWNER A10 Owner of object.
P-OBJECT-NAME A10 Object name.
P-OLD-OBJECT-VERSION A10 Version of object to be renamed.
P-NEW-OBJECT-VERSION A10 New version of object.
P-ALLOW-UPDATE A1 N Only perform a check.
Y Allow updates.

Notes:

  1. The Natural session parameter IM must be set to IM=F.
  2. The Monitor should be stopped during the execution of this utility to avoid unintended results of network activations.
  3. The program can be restarted in case of an abnormal termination to complete the rename action.
  4. Every object (to be) changed is reported. The report is written to Natural main output.

Monitor or Task Wait Time Modification

Natural Program Call

MO-WTM-P  P-MONITOR-WAIT-TIME P-TASK-ID

Parameters

Name Format Description
P-MONITOR-WAIT-TIME I4 In seconds.
P-TASK-ID I2 Number of a Monitor task.

Only the wait time of this task will be modified.

Notes:

  1. If a wait time less than 5 seconds is specified, the wait time is set to 5 seconds.
  2. The modifications carried out using this program only apply until the end of the current Monitor run.

Monitor Shutdown

Natural Program Call

MO-SHD-P

Parameters

None.

Monitor Start

Natural Program Call

MO-ST--P P-MONITOR-NODE

Parameter

Name Format Description
P-MONITOR-NODE I2 Value = 1 to 99999.

BS2000 Jobs

These jobs are used to update the submit user ID, submit password and account number.

Natural Program Call

BS2U01-P P-OWNER P-USERID-OLD P-PW-OLD P-USERID-NEW P-PW-NEW P-ACCOUNT-NEW

Parameters

Name Format Description
P-OWNER A10 Entire Operations owner of jobs to be modified.
P-USERID-OLD A8 BS2000 user ID to be exchanged.
P-PW-OLD A8 BS2000 submit password to be exchanged.
P-USERID-NEW A8 BS2000 new user ID.
P-PW-NEW A8 BS2000 new submit password.
P-ACCOUNT-NEW A8 BS2000 new account number.

Notes:

  1. An asterisk (*) for a parameter is converted to blank.
  2. Job fields are only exchanged if the Entire Operations owner, the old BS2000 user ID, and the old submit password do match.
  3. Fields are replaced, only if the new value is not blank.
  4. A log is written to the screen. In batch mode, the log is printed to Natural Printer 1. This printer must therefore be assigned in the JCL.

List or Delete TO-ACTIVATE Command Records

Natural Program Call

TA-DEL-P P-FUNCTION

Parameters

Name Format Description
P-FUNCTION A1 D Delete TO-ACTIVATE records.
L List TO-ACTIVATE records.

Notes:

  1. With this batch utility you can list or delete the internal TO-ACTIVATE command records in the Entire Operations active database.
  2. Use this utility only in co-operation with the Software AG support and if you have to perform a manual removal of the TO-ACTIVATE command records.
  3. This utility may be used only if the Entire Operations Monitor is not running.

Check the Existence of Symbol Table Definitions

Natural Program Call

CHNWST-P P-FUNCTION

Parameters

Name Format Description
P-FUNCTION A1 A List all networks without a symbol table.
S List subnetworks without a symbol table.

The report is written to Print File 1 in batch and to screen in online.

Mass Change of the Owner and Owner Deletion

Natural Program Call

OW-MB--P
P-OWNER-OLD P-OWNER-NEW P-ALLOW-UPDATE

Depending on the settings of the Natural parameter ID, parameters may need to be comma separated instead of using blanks.

Parameters

Name Format Description
P-OWNER-OLD A10 Old owner
P-OWNER-NEW A10 New owner.

If you specify ==DELETE== here, the owner will be deleted, with all references associated with the owner such as, links to users, other owners and objects maintained by the owner.

P-ALLOW-UPDATE A1 N Perform a check only.
Y Allow updates.

Notes

  • The Natural session parameter IM must be set to IM=F.

  • The Entire Operations Monitor must be stopped during the execution of this utility.

  • The old and new owner names may not be SYSDBA.

  • The utility runs in two passes. During the first pass, the data to be changed is checked against potential problems. An error message (line with E:) will result in update mode (P-ALLOW-UPD) switched to N. A typical problem is "target exists", when owner rename would cause merging of Entire Operations objects within a network. A warning message (line with W:) indicates situation of interest which does not prevent from object renaming.

  • The second pass is either the real update or diagnostic run depending on update mode value.

  • Every object (to be) changed is reported. The report is written to Natural main output.

  • The utility must run with Entire Operations System File 1 opened in Adabas exclusive (EXU) mode, which means: the Entire Operations Monitor and every other Natural session with Entire Operations System File 1 must be terminated before. This prerequisite is necessary to protect the integrity of Entire Operations objects and links between them. For this reason we suggest Natural profile parameter: 

    OPRB=(EXU=fnop1,UPD=fnat,flog,ACC=fsec)

    where:

    • fnop1 = Entire Operations System File 1

    • fnat = Natural system file FNAT

    • flog = Entire Operations or System Automation Tools log file

    • fsec = Natural Security system file

    Other files required to run Natural should be added to UPD= or ACC= list.

  • We suggest a job with the following steps to run OW-MB--P:

    • Step 0: Adabas ADAORD/ADASAV/ADAULD to save Entire Operations System File 1 when following OW-MB--P runs in update mode;

    • Step 1: Adabas ADADBS utility with parameters:

      ADADBS OPERCOM
STOPF=fnop1
ADADBS OPERCOM LOCKX=fnop1

    • Step 2: Natural session with OW-MB--P;

    • Adabas ADADBS:

      ADADBS OPERCOM
UNLOCKX=fnop1

  • If the utility runs in a "normal" Natural session, it will (most likely) run out of space in the Adabas WORK area or max ISN hold limit or will be waiting for records being held by others (also with update mode N). So we strictly recommend that you run the utility in batch mode only.

  • There is another Natural profile parameter, DBUPD=OFF, which may be used to run this utility safely and in parallel to other sessions however the utility report may indicate false error messages due to other activities on Entire Operations System File 1.

  • When OW-MB--P reports the E: ... targets exist (xx: nnn) error, xx is the two-character target code and nnn is the number of target records found. xx can be the following:

    NM (Network Master)
    JM (Job Master)
    EM (Event Master)
    JA (Job Active)
    EA (Event Active)
    JC (JCL active)
    CO (Conditions active)
    SA (Symbols Active)
    RP (Resource Prerequisites)
    RU (Resource usage)

  • Existing targets are reported in the sequence above, e.g. EM means that targets NM and JM were not found.

    If the reported target is:

    • JM: create manually missing network definition and jobs will appear in it. Deactivate/delete it again;

    • CO: these are visible in Active Conditions.

  • The rest of the targets can be cleaned up with a new special "orphan" cleanup batch utility: 

    CL-ORP-P owner update-mode

    where all parameters are mandatory:

    • owner (A10): P-OWNER-NEW from the erroneous OW-MB--P run (SYSDBA not allowed);

    • update-mode (L): update mode N or Y.

  • Everything about execution of OW-MB--P mentioned above applies the same way to CL-ORP-P, i.e. it must be executed with Natural profile parameter OPRB to open Entire Operations System File 1 in exclusive update mode or profile parameter DBUPD=OFF may be used for diagnostic purposes. The report about (possibly) deleted "orphan" objects is written to Natural main output.

  • Be sure to keep all the reports of OW-MB--P and CL-ORP-P runs with update mode Y.

Mass Change of Access Rights Granted to Networks

Natural Program Call

LOGON SYSEOR
NV-MB--P
 P-FUNCTION,P-OWNER,P-NETWORK,P-VERSION,P-TYPE,P-NAME,P-OPTION
FIN

The Natural program NV-MB--P provides the option to add, modify or delete user access rights granted to networks. NV-MB--P can run online and in batch mode.

The above Natural program call assumes that the Natural profile parameter ID (input delimiter character) is set to a comma (,).

Example:

LOGON SYSEOR
NV-MB--P
U,EXAMPLE,*,*,O,NOPALL,DORA

In the example above, the access rights of owner NOPALL change to DORA for all networks and network versions of the owner EXAMPLE.

Parameters

Name Format Description
P-FUNCTION A1 D Delete all user access rights granted to all networks specified with P-OWNER, P-NETWORK and P-VERSION.
U Changes user access rights granted to all networks specified with P-OWNER, P-NETWORK and P-VERSION:

  • Access rights are modified to P-OPTION for the user specified with P-TYPE and P-NAME.

  • Access rights are added if the user specified with P-TYPE and P-NAME does not yet exist.

P-OWNER A10 Name of the network owner or a range of names specified with a wildcard (* or ?).

You can only use one parameter to specify a name range.

P-NETWORK A10 Name of the network or a range of names specified with a wildcard (* or ?).

You can only use one parameter to specify a name range.

P-VERSION A10 Name of the network version or a range of names specified with a wildcard (* or ?).

You can only use one parameter to specify a name range.

P-TYPE A1 Only required for P-FUNCTION=U.

User type specification:
O Owner.
U User.
P-NAME A8 Only required for P-FUNCTION=U.

Name of the owner or user whose access rights you want to change.

P-OPTION A5 Only required for P-FUNCTION=U.

Options for access restrictions (multiple values are possible):

R Read access.
W Read and write access.
D Read, write and delete.
O Owner rights with permission to grant access to other users.
A Network activation rights.

User ID Mass Update in Network and Job Definitions

Natural Program Call

US-UPD-P P-FUNCTION P-OLD-VALUE P-NEW-VALUE P-NODE P-OWNER P-NETWORK

Parameters

Name Format Description
P-FUNCTION A3 NSU Change network default submit user ID.
NSG Change network default submit group.
NJU Change network default JCL user ID.
NJG Change network default JCL group.
JMU Change job modification user ID.
JSU Change job submit user ID.
JSG Change job submit group.
JJU Change job JCL user ID.
JJG Change job JCL group.
JSB Change SYSOUT node; catid; user ID on BS2000 node.
P-OLD-VALUE A20 If not empty, change only if old user ID is equal to this. This field is case-sensitive.
P-NEW-VALUE A20 May contain user ID or group (see P-FUNCTION) or blank to reset corresponding user ID. The field is case-sensitive.
P-NODE-A5 A5 Must be a defined node in Entire Operations. If you want to pass a node number directly, you have to assign it to a field in the format A5 first. Mnemonic (short) node names in the A5 format can also be passed.

SYSOUT definitions can only be used by jobs that have this node defined as a submit node.

P-OWNER A10 These two fields can be used for wildcard range definition. Wildcard is allowed in one field only.
P-NETWORK A10

Important:
This utility may be used only if the Entire Operations Monitor is not running.

Mass Update for User Access to Nodes

The utility NOPUNA-P is used to add or update single or multiple users for node access through defined operating system IDs.

Natural Program Call

NOPUNA-P

When running NOPUNA-P in batch mode, Work File 1 must be defined with LRECL 130. The work file can contain comment lines denoted by asterisk (*), double asterisk (**) or slash asterisk (/*) in the first and second positions of the record.

For each user ID to be added or updated, one line must be defined in the following format: 

nop-userid,node-number,os-userid,os-group,ld-value,aj-value,as-value

Each successful user update is logged in the Entire Operations log.

Example:

EXAMPLE,517,nprusr01,Nprgrp01,Y,Y,Y

Fields in the Input Lines

The variable fields used for the program call are described in the following table:

Name Format Description
nop-userid A8

(upper case)

 ID of the Entire Operations user provided node access.
node-number N5 Number of the Entire Operations node to be accessed.
os-userid A50

(mixed case)

 ID of the operating system assigned to the node.
os-group A20

(mixed case)

 Name of a Windows or UNIX group (if defined) to which the operating system ID belongs.
ld-value A1 Allow (Y) or disallow (N or blank) automatic node logon.
aj-value A1 Allow (Y) or disallow (N or blank) automatic node logon for browsing and editing JCL only.
as-value A1 Allow (Y) or disallow (N or blank) automatic node logon for browsing SYSOUT only.

Mass Change of Node Numbers

Natural Program Call

ND-MB--P LOCATION NODE-OLD NODE-NEW OWNER NETWORK NETWORK-VERSION

Parameters

Name Format Description
LOCATION A3 All occurrences of node will be changed in master definitions of network, job or event. For other values, refer to the list of JCL locations.
NODE-OLD N5 Node number.
NODE-NEW N5 Node number.
OWNER A10 Owner filter (optional).
NETWORK A10 Network filter (optional).
NETWORK-VERSION A10 Network version filter (optional).

Notes

  1. Both NODE-OLD and NODE-NEW must be defined and valid and of the same operating system class, i.e., you can change OS/390 to a z/OS node but not VSE to z/OS.

  2. If no value is specified for OWNER, NETWORK, NETWORK-VERSION, an asterisk (*) is used by default.

  3. You can use an asterisk (*), a greater than sign (>) or a smaller than (<) sign as a wildcard character.

    If a wildcard appears in OWNER, NETWORK contains an asterisk (*).

  4. Program ND-MB--P can be run safely (only to list objects) in a Natural session with the Natural profile parameter DBUPD=OFF set.

Mass Logon Processing in Batch Mode

Natural Program Call

ND-LB--P

The utility ND-LB--P must be run in a Natural batch environment. The logging is written both to SYSOUT and to the Entire Operations log (SAT log). Passwords will not be logged.

The input is read from Natural Work File 1. For each logon to be performed, one line must be defined with the format: 

node userid group password

Example:

517 sag users sag-pwd

Comment lines must have an asterisk (*) as first character. The output is written to the Natural batch job SYSOUT and to the Entire Operations log.

Fields in the Input Lines

Name Format Description
node N5 The Entire System Server node, to which the logon is to be performed.
userid A20 User ID for the logon.
group A20 Group for the logon.

For Windows nodes, group must contain the domain. If no group or domain is used, enter a hyphen (-) instead.

Example:

148 USER - USER-PWD
password A20 The password for the logon.

The password parameter must be enclosed in double quotes ("password"), if the password contains at least one blank. Passwords with trailing blanks are not supported.

Notes:

  1. This utility can be used only if the Entire Operations Monitor is not running.
  2. There may be one or several blanks between the parameters.
  3. If no group or domain is used, enter a hyphen (-) instead.
  4. For UNIX and Windows nodes, the input is case-sensitive.
  5. For mainframe nodes, the text strings will be converted to upper case before the logon is performed.
Warning:
Users of this utility must be aware that the input file is very security-sensitive, because it contains passwords in clear text.

Single Node Logons without using a Work File

To allow single node logons without using a work file, the parameters can be passed on the Natural command line too.

The command line parameters are:

  1. node number

  2. user ID

  3. group (UNIX) resp. domain (Windows)

    (Pass a hyphen (-) if the default group resp. no domain is to be used.)

  4. password

The parameters are case-sensitive.

On return, ND-LB--P provides a return code in the AIV variable +ND-LB--P-RC (I4).

It contains 0 (zero) if the logon was successful, and any other error code in case of an error.

Bulk Execution of MACRO Commands

Program: MAC-GE-P

The program performs the MACRO command in batch mode for a given selection of job network(s).

Natural Program Call

(with the Natural parameter ID=, being set) 

LOGON SYSEOR
MAC-GE-P
MODE,OWNER,NETWORK,NETWORK-VERSION
FIN

Example:

LOGON SYSEOR
MAC-GE-P
A,SN,A-1,v-unnamed
FIN

Parameters

Name Format Description
MODE A1 A Catalog all jobs with JCL location MAC.
M Catalog jobs with JCL location MAC, which were not yet cataloged.
OWNER A10 Owner filter.
NETWORK A10 Network filter.
NETWORK-VERSION A10 Network version filter.

The parameters P-OWNER, P-NETWORK and P-NETWORK-VERSION may contain selection wildcards: 

*, >, <, ?

Notes:

  1. The Program MAC-GE-P must be started in batch.
  2. The Natural profile parameters LC=ON, EDPSIZE=100 must be set.
  3. On mainframe systems. The Entire Operations Monitor must be active. The task 90 must be running.

Result Checking

The SYSOUT of the batch job contains detailed information about the cataloging. The results must be checked.

Example:

Owner      Network    Version    Job        Library  Member   Result 
SN         A-1        v-unnamed  MAC1-541   EOR-T541 MAC1     Done
SN         A-1        v-unnamed  MAC1N511   EOR-N541 MAC1     Error
>>> NAT0806 - Library not found.

Data Migration to the current Entire Operations Version

The data migration to the current Entire Operations version adapts various objects and fields, so that they can be used by the current Entire Operations version, 

DMDRIV-P

It is recommended to use a Natural batch job to perform the migration. The Natural commands are: 

LOGON SYSEOR
DMDRIV-P
FIN

Notes:

  1. A data migration consists of several independent migration steps.
  2. Each migration step will be performed only once. Internal control records prevent multiple executions.
  3. The migration invocation may be repeated as often as necessary.
  4. The migration is logged into the Natural SYSOUT.
  5. The data migration may be performed only if the Entire Operations Monitor is not active.