U0320

SIEMENS
ENDESA PERU
User Guide
PDM Interface
Document Number: U0320
Revision: 1.0.0.0
Date: 2015-02-09
CONFIDENTIAL
Author: N. Bogachev
NOTICE:
This document contains information which is confidential and proprietary to Siemens Energy, Inc. This
document, including any excerpt hereof, may not be copied, transmitted, distributed or otherwise
communicated to any third party without the express written consent of Siemens Energy, Inc.
SIEMENS
ENDESA PERU
User Guide
Configuration ID: U0320
PDM Interface
Document Revision: 1.0.0.0
Date: 2015-02-09
Name Date
Author: _____________________ ______________
Reviewer: _____________________ ______________
_____________________ ______________
_____________________ ______________
Int. Approval: _____________________ ______________
CONFIDENTIAL
Disclaimer of Liability Copyright © 2009 Siemens Energy, Inc.
Although we have carefully checked the contents of this The reproduction, transmission or use of this document or
publication for conformity with the hardware and software its contents is not permitted without express written
described, we cannot guarantee complete conformity authority. Offenders will be liable for damages. All rights,
since errors cannot be excluded. The information including rights created by patent grant or registration of a
provided in this manual is checked at regular intervals utility model or design, are reserved.
and any corrections that might become necessary are
Registered Trademarks
included in the next releases. Any suggestions for
improvement are welcome. SIMATIC®, SIMATIC NET®, SIPROTEC®, DIGSI®,
SICAM®, SINAUT® and Spectrum Power™ are
Subject to change without prior notice.
registered trademarks of Siemens AG. All other product
This document contains information which is confidential and brand names in this manual might be trademarks, the
and proprietary to Siemens Energy, Inc. use of which by third persons for their purposes might
infringe the rights of their respective owners.
This document contains information which is confidential and proprietary to Siemens Energy, Inc. Information is subject to the restrictions
stated on the first page.
U0320
1.0.0.0
Revision
Revision Record
Date
2015-02-09
Spectrum Power 3 PDM Interface, User Guide

Description
Initial Project Release
Page iii
Revision: 1.0.0.0
Table of Contents
Table of Contents
1 Introduction ..........................................................................................1
2 Job Management Overview .....................................................................2
2.1 Job .................................................................................................................. 2
2.2 Viewing the Current Jobs ..................................................................................... 2
2.3 Task ................................................................................................................. 3
2.4 Viewing the Tasks of a Job ................................................................................... 3
2.5 Job and Task Report ........................................................................................... 3
2.6 Application Log.................................................................................................. 4
2.7 Job and Application Log Report ............................................................................ 4

3 Copy Management .................................................................................5
3.1 PDM Initiated Activation....................................................................................... 6
3.2 Forms Interface for PDM Initiated Activation ............................................................ 7
3.2.1 Remote Activation Form ......................................................................................... 7
3.2.2 Activate All ......................................................................................................... 7
3.2.3 Undo All ............................................................................................................ 8
3.2.4 Delete Job.......................................................................................................... 8
3.3 Script Interface for PDM Initiated Activation........................................................... 10
3.3.1 ImCmActivateAll ................................................................................................ 10
3.3.2 ImCmUndoAll.................................................................................................... 11
3.3.3 Reset .............................................................................................................. 12
3.3.4 ImCmDeleteAll .................................................................................................. 12
3.4 Abandoning a Copy (ImCmAbandon) ................................................................... 13

3.5 Synchronizing the Copies with the Main (ImCmResynch) ......................................... 13
3.5.1 Synchronizing the PDM Copy with the Main .............................................................. 13
3.5.2 Synchronizing the HIS Copy with the Main ................................................................ 14
3.6 Failing Over to PDM Copy (ImCmFailover) ............................................................. 15
3.6.1 Planned Failovers .............................................................................................. 15
3.6.2 Catastrophic Failovers ......................................................................................... 15
4 Job Status ..........................................................................................19
5 Application Status ...............................................................................23
5.1 Transfer status ................................................................................................. 23
5.2 Activation Status .............................................................................................. 24
5.3 Delete Status ................................................................................................... 26
6 Job Interlocks .....................................................................................28
6.1 B1 Hierarchy Job Interlocks................................................................................ 28
6.2 ICCP Job Interlocks .......................................................................................... 28
6.3 Load Shed Job Interlocks................................................................................... 28
6.4 Reference Job Interlocks ................................................................................... 28
6.5 RTDS/CFE Job Interlocks ................................................................................... 29
Spectrum Power 3 PDM Interface, User Guide Page iv

U0320 Revision: 1.0.0.0
Table of Contents
6.6 Underfrequency Load Shed Job Interlocks ............................................................ 29

6.7 Voltage Reduction Job Interlocks ........................................................................ 29
6.8 Voltage Set Range Job Interlocks ........................................................................ 29
6.9 Energy Accounting Job Interlocks ....................................................................... 29
6.10 AA Job Interlocks ............................................................................................. 29
6.11 Job Interlock Report.......................................................................................... 30
7 General Notes on the Usage of the PDM Interface Scripts ..........................31
7.1 Accessing the PDM Interface .............................................................................. 31
7.2 Im.profile and Im.kshrc ...................................................................................... 31
7.3 PDM Interface Scripts ........................................................................................ 31
7.4 man pages ...................................................................................................... 32

7.5 The “run” directory ........................................................................................... 34
7.6 Autonomous Transactions ................................................................................. 34
8 Creating a Job/Connecting to a Job .......................................................35
9 Locking a Job/Unlocking a Job ..............................................................36
10 Base Applications Import .....................................................................37
10.1 Division of BA Data in Multiple IDDUG Files........................................................... 37
10.2 Import and Data Removal ................................................................................... 37
10.3 Import and Job Management .............................................................................. 37
10.4 Import and Validation ........................................................................................ 38
10.5 Import and Change Detection.............................................................................. 38
10.6 Import and Job Interlock .................................................................................... 38
10.7 B1 Hierarchy and Auto Insert of Elements and Infos................................................ 38
10.8 RTDS Hierarchy and Auto Insert of Station RTDS components.................................. 39

10.9 Execute Import and Check Results ...................................................................... 40
10.10 Executing Import With Detailed Trace ................................................................... 42
10.11 Deleting IMPORT_BULK Rows ............................................................................ 43
11 Communications Import .......................................................................44
11.1 ICCP Import ..................................................................................................... 44
12 Load Shed Import ................................................................................45
12.1 Load Shed Import ............................................................................................. 45
13 Underfrequency Load Shed Import.........................................................46
13.1 Underfrequency Load Shed Import ...................................................................... 46
14 Voltage Reduction Import .....................................................................47
14.1 Voltage Reduction Import................................................................................... 47
15 Energy Accounting Import ....................................................................48
15.1 Energy Accounting Import ................................................................................. 48
16 Advanced Applications Import, Validation and Export ...............................49
16.1 AA Import Pre-processor ................................................................................... 49
Spectrum Power 3 PDM Interface, User Guide Page v

U0320 Revision: 1.0.0.0
Table of Contents
16.2 AA Import ....................................................................................................... 50

16.3 AA Export ....................................................................................................... 50
17 Base Applications Export .....................................................................52
17.1 Export UNIX Script—ImBaExport ......................................................................... 52
17.2 B1 Export ........................................................................................................ 53
17.3 Reference Export.............................................................................................. 53
17.4 RTU Export...................................................................................................... 53
17.5 Characteristic Curve (CMCH) Export .................................................................... 54
17.6 SAM Export ..................................................................................................... 54
17.7 Voltage Level Export ......................................................................................... 54
18 Communications Export .......................................................................55

18.1 Export UNIX Script—ImCommExport .................................................................... 55
19 Load Shed Export ................................................................................56
19.1 Export UNIX Script—ImLsExport ......................................................................... 56
20 Underfrequency Load Shed Export ........................................................57
20.1 Export UNIX Script—ImUlsExport ........................................................................ 57
21 Voltage Reduction Export .....................................................................58
21.1 Export UNIX Script—ImVrExport.......................................................................... 58
22 Energy Accounting Export ....................................................................59
22.1 Export UNIX Script—ImEaExport ......................................................................... 59
23 Primitive Database Forms .....................................................................60
23.1 Executing Forms .............................................................................................. 60

23.2 Forms and Job Management............................................................................... 60
24 Global Validation .................................................................................61
24.1 Global Validation for a Job - ImGvJob .................................................................. 61
24.2 Global Validation for B1 - ImGvB1........................................................................ 61
24.3 Global Validation for B1 Miscellaneous – ImGvBaMisc ............................................ 62
24.4 Global Validation for Duplicate Names – ImGvSpecDupName ................................... 62
24.5 Global Validation for References – ImGvReference ................................................. 62
24.6 Global Validation for RTU (RTDS and CFE) ImGvRtu ............................................... 62
24.7 Global Validation for SAM (RTDS and CFE) ImGvSam.............................................. 63
24.8 Global Validation for RTDS Miscellaneous – ImGvRtdsMisc...................................... 63
24.9 Global Validation for ICCP – ImGvICCP................................................................. 63
24.10 Global Validation for Load Shed – ImGvLs ............................................................ 63
24.11 Global Validation for Underfrequency Load Shed – ImGvUls ..................................... 64
24.12 Global Validation for Voltage Reduction – ImGvVr .................................................. 64
24.13 Global Validation for Energy Accounting – ImGvEa................................................. 64
24.14 Global Validation for all Base Application Data – ImGvBaAll ..................................... 64
25 Deleting Primitive Data .........................................................................66
Spectrum Power 3 PDM Interface, User Guide Page vi

U0320 Revision: 1.0.0.0
Table of Contents
25.1 Cascade Delete ................................................................................................ 66

25.2 Scope of Cascade Delete ................................................................................... 66
25.3 Cascade Delete and SCADA Data ........................................................................ 66
25.4 Cascade Delete and Calc Operand Data ................................................................ 68
25.5 Cascade Delete and Reference Data ..................................................................... 68
25.6 Cascade Delete and RTU Scan Order Data............................................................. 68
25.7 Cascade Delete and Advanced Applications Data ................................................... 69
26 Modeling Primitive Data........................................................................70
26.1 Modeling......................................................................................................... 70
26.2 Scope of Model ................................................................................................ 70
27 PDM Interface Reports .........................................................................72

28 Base Application Reports .....................................................................73
29 Communication Protocol Reports ..........................................................74
30 Load Shed Reports ..............................................................................75
31 Underfrequency Load Shed Reports .......................................................76
32 Voltage Reduction Reports ...................................................................77
33 Energy Accounting Reports ..................................................................78
34 Editing using SQL*Plus ........................................................................79
35 Change Log ........................................................................................80
36 Job Trace ...........................................................................................81
37 Validation Error Messages ....................................................................83
37.1 Error Message Reports ...................................................................................... 83

37.2 Creating an Error Summary ................................................................................ 84
37.3 Deleting Error Messages .................................................................................... 86
38 Job Undo/Job Redo .............................................................................87
39 Task Cancel........................................................................................88
40 Job Transfer .......................................................................................89
40.1 Execute Job Transfer ........................................................................................ 89
40.2 Check Job Transfer Output................................................................................. 90
40.3 DBA Job Management ....................................................................................... 92
40.4 Cancel the DBA Job .......................................................................................... 92
40.5 Use the DBA Editors to Make Additional Changes .................................................. 93
40.6 Activate the DBA Job ........................................................................................ 93
40.7 Delete the DBA Job ........................................................................................... 93
40.8 Undo the DBA Job ............................................................................................ 93
40.9 Caution........................................................................................................... 94
41 Build and Transfer Advanced Application Databases ................................95
41.1 Transfer the Relation Databases.......................................................................... 95
Spectrum Power 3 PDM Interface, User Guide Page vii
U0320 Revision: 1.0.0.0
Table of Contents
41.1.1 Transfer AGC Relations ....................................................................................... 95

41.1.2 Transfer Load Forecast Relations (LFTRAN) ............................................................. 95
41.2 Transfer the Oracle databases ............................................................................ 96
41.2.1 Transfer Unit Commitment (UC) data....................................................................... 96
42 Job Delete ..........................................................................................97
43 Job Cancel .........................................................................................98
44 Job History.........................................................................................99
44.1 Job Log History................................................................................................ 99
44.2 Change Log History .......................................................................................... 99
44.3 Deleting Job Log and Change Log History ............................................................ 99
45 Base Applications Reverse Transfer.....................................................100

46 Full Transfer .....................................................................................103
47 Operating Modes ...............................................................................105
48 IM Tools ...........................................................................................106
48.1 ImBaDeleteTA ................................................................................................ 106
48.1.1 Executing ImBaDeleteTA ................................................................................... 106
48.2 ImBaImportDirectory ....................................................................................... 106
48.2.1 Executing ImBaImportDirectory ............................................................................ 106
48.3 ImBaLoadFilltab ............................................................................................. 107
48.3.1 Executing ImBaLoadFilltab ................................................................................. 107
48.4 ImIddugCompare ............................................................................................ 107
48.4.1 Executing ImIddugCompare ................................................................................ 107
48.5 ImCompare.................................................................................................... 108

48.5.1 Executing ImCompare ....................................................................................... 108
48.5.2 Corrective Action.............................................................................................. 109
48.6 ImOraDumpLoad ............................................................................................ 109
48.6.1 Setting up to run ImOraDumpLoad........................................................................ 110
48.6.2 Executing ImOraDumpLoad ................................................................................ 111
48.6.3 Using ImOraDumpLoad to Dump and Load Other Databases ....................................... 112
48.7 IndentTrace ................................................................................................... 113
48.7.1 Executing IndentTrace ....................................................................................... 113
49 Creating Oracle Users ........................................................................114
50 CFE on AIX .......................................................................................115
50.1 Modeling CFE Data ......................................................................................... 115
50.2 CFE Defaults IDDUG........................................................................................ 115
50.3 ImArsExportBulk ............................................................................................ 115
50.4 ImAsrExportCfe and Job Transfer...................................................................... 115
50.5 Skipping Incremental ASR Generation ................................................................ 116
51 Putting It All Together - A Process Flow ................................................117
Spectrum Power 3 PDM Interface, User Guide Page viii

U0320 Revision: 1.0.0.0
Table of Contents
List of Figures
Figure 49-1: ImOraDumpLoad Process Flow............................................................................................ 110
List of Tables
Table 4-1: Job Status - Action and Results................................................................................................. 20
Table 5-1: Application Log Status - Action and Results ............................................................................... 27
Table 41-1: Mapping an Application Name to an Error File Name ............................................................... 90
Table 52-1: Process Flow ........................................................................................................................ 117
Spectrum Power 3 PDM Interface, User Guide Page ix

U0320 Revision: 1.0.0.0
Introduction
1 Introduction
The Primtive Data Management (PDM) Interface is a set of functions that allow primitive data to be defined, accessed
and transferred to the operational database. The PDM Interface functions include:
Job Management
Job management provides the ability to group a set of changes into a job and to control the actions performed
on this job.
Copy Management
Copy Management is a feature of the PDM, designed for multisite, which manages the propagation of primitive
data to Backup Control Center(s), and to other Real Time databases such as Historical Information Systems
This document contains information which is confidential and proprietary to Siemens Energy, Inc. Information is subject to the
(HIS), Energy Accounting (EA), and Communication Front End (CFE). Copy Management makes use of the
tools provided by Job Management.
Import
Import provides the ability to load and remove data from ASCII files into the primitive database.
Export
Export provides the ability to extract data from the primitive database and produce ASCII files which may be
subsequently imported.
Forms
Forms provide the ability to view and/or edit the contents of the primitive database using a GUI interface. See
the PDM Forms User Guide - U0325.
restrictions stated on the first page.
Reports
Reports provide the ability to produce an ASCII file displaying the contents of primitive data.
Validation
Validation of data occurs during entry of data into the primitive database. This type of validation is referred to as
entry-level validation. Error messages are issued if data values violate the validation rules. Error message
reports produce an ASCII file of the error messages.
Global Validation
Global validation provides the ability to verify the contents of the primitive database. Global validation includes
both entry-level validation and database-level validation. Error messages are issued if data values violate the
validation rules.
Job Transfer
Job transfer provides the ability to transfer a job from the primitive database to the operational database.
Reverse Transfer
Reverse transfer provides the ability to initialize SCADA, ICCP, Reference and RTDS/CFE data in an empty
primitive database from an existing operational database.
Configuration
Configuration provides the ability to install and configure the PDM Interface product. This includes creating
additional PDM Oracle users that may modify the PDM schema owned by user PRIME. See the Primitive
Database Maintenance User Guide - U0385.
The PDM Interface functions are executed using both UNIX scripts and Oracle SQL*Plus scripts. The following
chapters describe how to use these scripts.
Spectrum Power 3 PDM Interface, User Guide Page 1

U0320 Revision: 1.0.0.0
Job Management Overview
2 Job Management Overview

2.1 Job
Most interaction with the primitive database is done through a job. A job can best be illustrated using an example.
Suppose a user wishes to define a new station in the primitive database and propagate the station to the online
operational database. The sequence of steps to accomplish this are:
The user first creates a new job name. A job name is a 1-8 character name and contains no embedded blanks or
special characters1. The script ImJmJobList may be used to display a list of the jobs currently defined.
After choosing a new job name, the user executes the import script and supplies the new job name and the name
of the datafile of the new station. Import loads the data from the input file into the primitive database. All of the
changes made to the primitive database are recorded in the change log and associated with the job. The user may
disconnect from and reconnect to the same job many times.
When finished defining the station in the primitive database, the user executes the job transfer script and supplies
the job name. Job transfer retrieves the primitive data changes made by this job from the change log and transfers
the changes into the offline operational database.
When the transfer is complete, the user activates the job into the online operational database. If Remote Copies
are established in a Multisite system, the user also activates the job to ALL ‘Active’ Remote Copies requiring the
job changes at that time.
After the activation is complete, the user deletes the job from both of the Remote databases: the operational
database and the primitive database. The job is archived in the job log history and the change log history.
In formal terms, a job is a collection of data changes identified by a unique name. The job is the increment that is
transferred from the primitive database to the operational database. The user is in control of which changes are
included in a job.
2.2 Viewing the Current Jobs

ImJmJobList is a UNIX script that lists the currently defined jobs and, for each job, its associated job ID, status,
creation date/time/oracle_username, and last used date/time/oracle_username. The associated SQL*Plus script
ImJmJobList.sql is also available. An example usage is:
unix> ImJmJobList -u {oracle_username}
Job Name/
Job Id Status Current User Creation User
---------- ---------- ------------------- --------------------
crystal READY PRIME PRIME
1 25-JAN-94 01:59:39 25-JAN-94 01:59:55
star1 READY PRIME PRIME

2 25-JAN-94 02:00:23 25-JAN-94 02:00:55
Job data is also available within Oracle Forms and may be viewed by using the form JOBL. See the PDM Forms User
Guide - U0325.
1. A valid name may contain letters, numbers, and the underscore (_).

U0320 Revision: 1.0.0.0
2.3 Task
Jobs are further subdivided into tasks. A new task is created each time a user connects to a job. All of the changes
made in one connection are grouped together into one task. For example, if an import, which consists of two tasks, is
run three times within a job, that job will contain six tasks. The concept of tasks also applies to changes made using
Forms. In this case, a task consists of all the changes made during a single visit to a form. To clarify, imagine calling up
the DIG form and changing data for several digital points followed by a call-up of the ANA form from which several
analog points are changed. The changes made using Form DIG represent one task; the changes made using Form
ANA represent a second task.
Each task has both a name and an id. The task id is the unique identifier for a task because the task name is the same
for each execution of a particular function.
2.4 Viewing the Tasks of a Job

ImJmTaskList is a UNIX script that lists the tasks of a job. The associated SQL*Plus script ImJmTaskList.sql is also
available. An example usage is:
unix> ImJmTaskList -u {oracle_username} -j {jobname}
Job Name/ Task Name/
Job Id Task Id Task Creation
---------- ---------------------------- ------------------
crystal import_bulk PRIME
1 1 25-JAN-94 01:59:39
import PRIME
25-JAN-94 01:59:41
star1 import_bulk PRIME

2 1 25-JAN-94 01:59:56
import PRIME
2 25-JAN-94 01:59:59
Task data is also available within Oracle Forms and may be viewed by using the form TASL. See the PDM Forms User
Guide - U0325.
2.5 Job and Task Report

ImRptJobLog.sql is an SQL*Plus script that generates a detailed report about the currently defined jobs and their
associated tasks. The information contained in the report for each job includes the job name, job id, job status, creation
date/time/oracle_username, last used date/time/oracle_username, current usage date/time/oracle_username/ORACLE
session id, locked by oracle_username, and list of tasks associated with the job. This script may be executed from
SQL*Plus or through the UNIX script ImRpt. An example usage is:
sql> @ImRptJobLog
Enter value for report _output: job.lst
Job and task reports may also be run from the REP form within Oracle Forms. See the PDM Forms User Guide -
U0325.

U0320 Revision: 1.0.0.0
2.6 Application Log

Once transfer is to be started for a job rows are added to the application log for that job. Each application log record
contains the job id, application name and the application’s transfer and activate Statuses. A record is created in the
application log for each application that is affected by the changes made by the job. If the change log is empty for the
job hen PDM assumes a full transfer was run and the application log will contain an entry for whichever application’s
full transfer was run.
The Application Log is used as a control table for the various job handling operations. It will tell the state of the job on
all systems to facilitate Copy Management and also will show what kind of data the job has changed and direct the job
transfer operations that need to be run for the job.
2.7 Job and Application Log Report

ImJmShowJob is a UNIX script that lists the contents of both job and application information for a job. The associated
SQL*Plus script ImJmShowJob.sql is also available. An example usage is:
unix> ImJmShowJob -u {oracle_username} -j {jobname}
Job Name/ Status Current User/ Creation User/
Job Id Current Date/Time Creation Date/Time
-------- ------- ----------------- ----------------
starl TRANSFERRED PRIME
359 20-SEP-05 11:06:28
Appl Transfer Status Activate Status Prev Delete ODB Job Date/Time
Activate Status
Status
---- --------------- --------- ------ ------ ------------------
AI TRANSFER_SKIPPED
BA TRANSFERRED 20-SEP-05 11:07:07
NWA TRANSFER_SKIPPED
EA_NOT_NEEDED
HIS_NOT_NEEDED
NOT_REQUIRED

U0320 Revision: 1.0.0.0
Copy Management
3 Copy Management
Copy Management is a feature of the PDM, designed for Multisite, which allows propagation of primitive data to the
Backup Control Center(s), and to other RealTime databases like Historical Information Systems (HIS) and Energy
Accounting (EA). In a Copy Management configuration, there is one Main center, and any number of:
PDM Backup Control Center (PDM Copy)
HIS/EA Copy
All of the Copies are linked, and in synchronization, with the Main center. Only jobs that have been activated at the
Main can be propagated to the Copies, as needed.
Note: For specific details about the pre-requisites, set up and configuration for Copy Management, please refer to
Core System Installation Guide - I3000.
It is important to note that the entire design of Copy Management relies on change detect to maintain data within a
‘Copy’. Thus, running a data import without change detect and then full transferring that data will adversely affect the
data within the PDM ‘Copy’. The user should abandon all PDM copies and then run the resynch process to re-establish
them should it ever be necessary to run PDM jobs without change detect on.
Copy Management maintains only jobs that contain primitive data. It cannot maintain changes made to relations
through the use of Spectrum Power 3 DBA Editors.
It is strongly recommended that the RDBMS Forms interface be used to handle PDM jobs in the Copy Management
environment, rather than the corresponding UNIX command line scripts. The RDBMS Forms will ensure the proper
handling of jobs, and will guide the user through the correct and allowable steps in the data propagation process, even
if the user is not familiar with the allowable job states within Copy Management.
This chapter discusses the job flow and the movement of data from the Main to the Active Copies using the PDM
Initiated Activation feature.
Note: Whenever the word “remote” is capitalized, as in “Remote database”, it is referring to those databases which are
linked to in the PDM copy_definition table.

U0320 Revision: 1.0.0.0
Copy Management
3.1 PDM Initiated Activation

The PDM Initiated Activation (PIA) is an enhancement and extension of the Copy Management functionality. The user
now has control over when the job should be propagated to the Remote databases. Most importantly, the user gets
feedback when there is a failure in activation to any Remote database(s) and has the capability to retry.
The main features of PDM Initiated Activation are as follows:
1. The user can activate data changes from the PDM of the Main system to ALL Remote databases (Active Copies)
configured in the system, with one click of the ‘ACTIVATE_ALL’ button in the RDBMS Form or the
‘ImCmActivateAll’ script. The data changes are activated to ALL the Copies at the same time.
2. The job cannot be deleted until the changes have been activated to ALL Remote databases (Active Copies)
needing the change. Therefore, the Remote databases are always in synch with the Main.
3. An activation failure on any Remote database is reported back to the user on the Main.
4. The failed Remote database DOES NOT become automatically abandoned (the need of frequent Resynchs is
eliminated).
5. In the event of a failed activation on the Remote database, the user may:
a. Reset and retry the activation again on the failed database.
b. Undo the activation from successful databases.
c. Abandon the failed database and proceed with making the job permanent (job delete).
6. When a database is ‘Abandoned’, it requires a ‘Resynch’ to synchronize it back with the Main (as before).
Please Note that if Copies have not been established, or if the PDM Initiated Activation software determines that
activation to Copies is not required (based on the type of data change made) the normal job flow of Transfer ->
Activate Delete comes into play.

U0320 Revision: 1.0.0.0
Copy Management
3.2 Forms Interface for PDM Initiated Activation

As previously mentioned, it is strongly recommended to use the PDM Forms interface to handle PDM jobs in the Copy
Management environment, rather than the corresponding UNIX command line scripts (discussed later in this chapter).
The PDM Forms will enforce the proper handling of jobs, even if the user is not familiar with allowable job states within
Copy Management.
The PDM forms have been enhanced to guide the user through the PDM Initiated Activation process.
The main PDM form has been modified to add a [Remote Database Activations] button in the button palette. After the
job is successfully activated to the online operational database, the job stays in ‘ODB_ACTIVATE_IN_PROGRESS’
status, pending activation to the Remote databases, and the ‘Remote Database Activations’ button becomes available.
At this time, the user can either select the ‘Remote Database Activations’ button to proceed with Remote database
activation, or Undo the online operational activation on the Main and back out the job.
3.2.1 Remote Activation Form

When the user selects the [Remote Database Activations] button a new form ‘Remote Activation’ (app.fmt) is invoked.
The Remote Activation form is a graphical representation of the Oracle table ‘application_log’ which contains
information on the transfer/activate status of the job on the Main and on ALL Active Copies defined in the system. In
this form, the user can view the activate and delete status of the job on each Active Copy.
The PDM Initiated Activation software determines based on the type of data change made whether activation is
required on an Active Copy or not. The activate statuses for the Copies at this point can be:
HIS Copy HIS_ACTIVATION_REQ/HIS_NOT_NEEDED (for HIS changes)
EA_ACTIVATION_REQ/EA_NOT_NEEDED (for EA changes)
PDM Backup Copy PDM_SEND_REQ
3.2.2 Activate All

When the user invokes the Remote Activation form the [Activate All] button is the only button that is available to the
user. Selecting this button activates the job across all the Active Copies that require the data change. It performs the
following functions on the different Active Copies:
PDM Copy - It calls the ‘ImCmPDMSend’ script to “push” the data changes associated with the job from the Main to
the PDM Copy and completes a “Redo”. This is done for all the Active PDM Copies that have been defined in the
system.
The status of the PDM Copy in the ‘application_log’ table for the concerned job_id is updated to ‘PDM_SENT’ if the
send was successful or to ‘PDM_SEND_FAILED’ in case of a failure.
HIS Copy - For HIS related changes it calls the ‘ImHisJobMgmt’ script to connect to the Oracle database and send
the HIS related data changes across to the HIS sid on the HIS Copy through an Oracle database link. After the
changes have been applied to the HIS sid the script also sends a softbus message to the COMS to inform them
that new HIS changes have arrived. This is done for all Active HIS Copies that have been defined in the system.
The status of the HIS Copy in the ‘application_log’ table for the concerned job_id is updated to ‘HIS_ACTIVATED’ if
the activation was successful or to ‘HIS_ACTIVATE_FAILED’ in case of a failure.
For EA related changes it calls the ‘ImEaJobMgmt’ script to connect to the Oracle database and send the EA
related data changes across to the HIS sid on the HIS Copy through an Oracle database link. This is done for all
Active HIS Copies that have been defined in the system.
the activation was successful or to ‘HIS_ACTIVATE_FAILED’ in case of a failure.
After the activation is complete the form is refreshed and updated with the correct activate statuses pertaining to the
Copies.

U0320 Revision: 1.0.0.0
Copy Management
If activation to a Copy has failed a message is issued to the user that activation failed on a Remote Copy. The only
option for the user at this point is to [Reset] the failed activation.The user can point the cursor at the failed Copy in the
Remote Activation form. The [Reset] button will become available. At this time the user can Reset the failed activation,
fix the error and try activation again for that failed Copy.
Upon successful completion of the activation across ALL Active Copies requiring the change the job status changes to
‘ODB_ACTIVATED’ since the job is now activated everywhere. The only options in front of the user now are to either
‘Undo All’ - undo activation from the Copies the job was activated to - or go back to the main PDM form and delete the
job making the job changes permanent everywhere.
3.2.3 Undo All

Once the job is successfully activated to ALL the Copies requiring the data change the [Undo All] button becomes
available. Selecting this button “undo”es the activation of the job from all the Active Copies the data change was
activated to. It performs the following functions on the different Active Copies:
PDM Copy - It calls the ‘ImCmPDMUndo’ script to reverse the data changes associated with the job from the PDM
Copy and deletes the job from the PDM Copy. This is done for all the Active PDM Copies that have been defined in
the system.
The status of the PDM Copy in the ‘application_log’ table for the concerned job_id is updated to
‘PDM_SEND_REQ’ if the undo was successful or to ‘PDM_UNDO_FAILED’ in case of a failure.
HIS Copy - For HIS related changes it calls the ‘ImHisJobMgmt’ script to connect to the Oracle database and Undo
the HIS related data changes from the HIS sid on the HIS Copy through an Oracle database link. After the changes
have been reversed from the HIS sid the script also sends a softbus message to the COMS to inform them that the
HIS changes have been reversed. This is done for all Active HIS Copies that have been defined in the system.
The status of the HIS Copy in the ‘application_log’ table for the concerned job_id is updated to
‘HIS_ACTIVATION_REQ’ if the undo is successful or to ‘HIS_UNDO_FAILED’ in case of a failure.
For EA related changes, it calls the ‘ImEaJobMgmt’ script to connect to the Oracle database and Undo the EA
related data from the HIS sid on the HIS Copy through an Oracle database link. This is done for ALL Active HIS
Copies that have been defined in the system.
‘EA_ACTIVATION_REQ’ if the undo is successful, or to ‘EA_UNDO_FAILED’ in case of a failure.
After the Undo is complete, the form is updated with the correct activate statuses pertaining to the Copies.
If Undo from a Copy has failed, a message is issued to the user stating that Undo has failed on a Remote Copy. The
user can point the cursor at the failed Copy in the Remote Activation form. The [Reset] button will become available. At
this time, the user can Reset the failed Undo, fix the error and try Undo again for that failed Copy.
Upon successful completion of the Undo from ALL Active Copies requiring the Undo, the job status changes to
‘ODB_ACTIVATE_IN_PROGRESS’. The only options in front of the user now are to either [Activate All] - Activate data
changes within the job to the Copies as needed - or go back to the main PDM form and Undo on-line operational
database Activation, Cancel Job Transfer and so on to back out the changes.
3.2.4 Delete Job

As mentioned before, after the successful activation of job to ALL Active Copies requiring the change, the user can
either [Undo All] or [Delete] the job to make the job changes permanent.
Deletetion of the job is a one-step process through the main PDM form. If the user decides to delete the job, the user
needs to navigate to the main PDM form from the Remote Activation form. The only button available there is the
[Delete] button. When the user selects the [Delete] button, the job status changes to ‘ODB_DELETE_IN_PROGRESS’,
pending completion of the delete of job everywhere. The form executes delete of the job in the following order - first
from the Remote Copies, then from on-line operational database on the Main and then from the PDM on the Main.
The [Delete] button executes the following scripts:
Deleting job from Remote Copies
U0320 Revision: 1.0.0.0
Copy Management
o PDM Copy - It executes the ‘ImCmDelete’ script to delete the job from the PDM Copy. This is performed on all
Active PDM Copies defined in the system. The activate_status of the PDM Copy in the ‘application_log’ table
for the concerned job_id stays ‘PDM_SENT’, and the delete_status is updated to ‘PDM_DELETED’ if the
delete was successful, or to ‘PDM_DELETE_FAILED’ in case of a failure.
o HIS Copy - There is no delete per se for HIS or EA data. Therefore, it just updates the application_log table
and sets the delete_status for the HIS Copy to ‘HIS_DELETED’ or ‘EA_DELETED’ depending on the
application affected by the job.
Deleting job from on-line operational database - After the successful job delete from ALL Active Copies the job was
activated to, on-line operational database job delete is performed by the form by calling the ‘ImDBAJobMgmt’
script.
Deleting job from PDM - This is the last step in the job delete process. It calls pkg_jobm.delete_job to delete the job
from PDM.
If the delete fails on any Remote Copy, delete continues to be performed on other Copies. However, on-line
operational database job delete and PDM job delete is not performed. At this time, the user can go back to the Remote
Activations form, reset the failed delete on the host, and click on the [Delete] button in the Remote Activations form to
execute delete again on the failed host.

U0320 Revision: 1.0.0.0
Copy Management
3.3 Script Interface for PDM Initiated Activation

Job Propagation to the Remote Copies is also available through the script interface. However, as previously
mentioned, it is strongly recommended to use the PDM Forms interface to handle PDM jobs in the Copy Management
environment, rather than the corresponding UNIX command line scripts (discussed here). The PDM Forms will enforce
the proper handling of jobs, even if the user is not familiar with allowable job states within Copy Management.
After the job is successfully transferred/activated to the on-line operational database, the job_status remains
‘ODB_ACTIVATE_IN_PROGRESS’. The PDM Initiated Activation software determines, based on the type of data
change made, whether activation is required on an Active Copy or not. A row is created in the application_log table for
each Active Copy and the actiivate_status of the job on that Copy. The activate statuses for the Copies at this point
can be:
HIS Copy --> HIS_ACTIVATION_REQ/HIS_NOT_NEEDED (for HIS changes)
--> EA_ACTIVATION_REQ/EA_NOT_NEEDED (for EA changes)

PDM Backup Copy --> PDM_SEND_REQ
At this time, the user can execute the ‘ImCmActivateAll’ script to activate the job to all Active Copies requiring the
change.
3.3.1 ImCmActivateAll
ImCmActivateAll is a UNIX script that activates the job changes to all the Active Copies that require the data change. It
needs to be executed on the Main and can be invoked as follows:
unix> ImCmActivateAll -u {Oracle Username} -j {job_name}
ImCmActivateAll performs the following functions for the different Active Copies:
PDM Copy - It calls the ‘ImCmPDMSend’ script to “push” the data changes associated with the job from the Main to
the PDM Copy and completes a “Redo”. This is done for all the Active PDM Copies that have been defined in the
system.
The status of the PDM Copy in the ‘application_log’ table for the concerned job_id is updated to ‘PDM_SENT’ if the
send was successful or to ‘PDM_SEND_FAILED’ in case of a failure.
HIS Copy - For HIS related changes, it calls the ‘ImHisJobMgmt’ script to connect to the Oracle database and send
the HIS related data changes across to the HIS sid on the HIS Copy through an Oracle database link. After the
changes have been applied to the HIS sid, the ‘ImHisJobMgmt’ script also sends a softbus message to the COMS
to inform them that new HIS changes have arrived. This is done for all Active HIS Copies that have been defined in
the system.
the activation was successful, or to ‘HIS_ACTIVATE_FAILED’ in case of a failure.
For EA related changes, it calls the ‘ImEaJobMgmt’ script to connect to the Oracle database and send the EA related
data changes across to the HIS sid on the HIS Copy through an Oracle database link. This is done for all Active HIS
The status of the HIS Copy in the ‘application_log’ table for the concerned job_id is updated to ‘EA_ACTIVATED’, if
the activation is successful or to ‘EA_ACTIVATE_FAILED’ in case of a failure.
If activation to a Copy fails, a diagonostic message is issued in the ‘msg’ table. At this time, the user has to Reset the
failed activation using the respective Reset script before attempting activation for that failed Copy again (discussed in
detail later in the Reset section).
Once the activation fails and is Reset, the ‘ImCmActivateAll’ script can no longer be used for activation to the failed
Copy. The user will have to use the individual activation script for activating the job to the Copy. The scripts need to be
run on the Main. Please note that the ‘host name’, ‘preferred node name’ and ‘alternate node name’ are the same
parameters as passed in in the ‘ImCmAddCopy’ script when defining a Copy and can be found in the ‘copy_definition’
Oracle table.

U0320 Revision: 1.0.0.0
Copy Management
The individual activation script for PDM Copy is:

unix> ImCmPDMSend -u {Oracle username} -j {job_name} -h{host_name}
The individual activation script for HIS Copy (HIS changes) is:
unix> ImHisJobMgmt -u {Oracle username} -j {job_name} -f A -h{host_name}
The individual activation script for HIS Copy (EA changes) is:
unix> ImEaJobMgmt -u {Oracle username} -j {job_name} -f A -h{host_name}
Upon successful completion of the activation across ALL Active Copies requiring the change, the job status changes to
‘ODB_ACTIVATED’, since the job is now activated everywhere. The user can now either start to delete the job from the
Copies (ImCmDeleteAll - discussed later in this section), or start to undo activation from the Copies the job was
activated to (ImCmUndoAll) to back out the changes.
3.3.2 ImCmUndoAll
Once the job is successfully activated to ALL the Copies requiring the data change, the user may wish to “undo” the
activation of the job from the Active Copies. The UNIX script ‘ImCmUndoAll’ can be invoked at this time to perform the
undo from the Copies. It needs to be executed on the Main and can be invoked as follows:
sql> ImCmUndoAll -u {Oracle Username} -j {job_name}
ImCmUndoAll performs the following functions for the different Active Copies that the job was activated to:
PDM Copy - It calls the ‘ImCmPDMUndo’ script to reverse the data changes associated with the job from the PDM
Copy and deletes the job from the PDM Copy. This is done for all the Active PDM Copies that have been defined in
the system.
The status of the PDM Copy in the ‘application_log’ table for the concerned job_id is updated to
‘PDM_SEND_REQ’ if the undo was successful, or to ‘PDM_UNDO_FAILED’ in case of a failure.
HIS Copy - For HIS related changes it calls the ‘ImHisJobMgmt’ script to connect to the Oracle database and Undo
the HIS related data changes from the HIS sid on the HIS Copy through an Oracle database link. After the changes
have been reversed from the HIS sid the ‘ImHisJobMgmt’ script also sends a softbus message to the COMS to
inform them that the HIS changes have been reversed. This is done for all Active HIS Copies that have been
defined in the system.
‘HIS_ACTIVATION_REQ’ if the undo is successful or to ‘HIS_UNDO_FAILED’ in case of a failure.
For EA related changes it calls the ‘ImEaJobMgmt’ script to connect to the Oracle database and Undo the EA
related data from the HIS sid on the HIS Copy through an Oracle database link. This is done for ALL Active HIS
‘EA_ACTIVATION_REQ’ if the undo is successful or to ‘EA_UNDO_FAILED’ in case of a failure.
If Undo from a Copy fails a diagonostic message is issued in the ‘msg’ table under the user’s job_id. The user then has
to Reset the activation for the failed host using the respective Reset scripts (discussed later in this section). After the
failed activation is Reset the ‘ImCmUndoAll’ script can no longer be used for undoing from the failed Copy. The user
will have to use the individual undo script for undoing the job from the Copy. The scripts need to be run on the Main.
The individual undo script for PDM Copy is:
unix> ImCmPDMUndo -u {Oracle username} -j {job_name} -h{host_name}
The individual undo script for HIS Copy (HIS changes) is:
unix> ImHisJobMgmt -u {Oracle username} -j {job_name} -f U –h
{host_name}
The individual undo script for HIS Copy (EA changes) is:

U0320 Revision: 1.0.0.0
Copy Management
unix> ImEaJobMgmt -u {Oracle username} -j {job_name} -f U -h

host_name}
Upon successful completion of the Undo from ALL Active Copies requiring the Undo, the job status changes to
‘ODB_ACTIVATE_IN_PROGRESS’. The only options in front of the user now are to either [Activate All] - Activate data
changes within the job to the Copies as needed - or go back to the main PDM form and Undo on-line operational
database A ctivation, Cancel Job Transfer and so on to back out the changes.
3.3.3 Reset
If the activation or undo to/from any Copy fails, the user has to reset the failed activation/undo before attempting
activation/undo again.
For a failure of activation/undo on the PDM Copy, the user will have to Reset the failed activation/undo by running the
following command on the Main:
unix> ImCmPDMReset -u {Oracle username} -j {job_name} -h host_name}

For a failure of activation/undo on the HIS Copy, the user will have to Reset the failed activation/undo by running the
following command on the Main:
unix> ImHisJobMgmt -u {Oracle username} -j {job_name} -f R –h
{host_name}
After the Reset is complete, the application_log is updated with the last successful activate_state and the user can run
the activate/undo script (discussed earlier) for the failed host to activate/undo the job again.
3.3.4 ImCmDeleteAll
Unlike the Forms interface, deleting the job through the scripts is not a one-step process as compared to deleting the
job through the PDM form. The user has to use multiple scripts to delete the job. If the user is using the script interface,
the job delete must be executed in the following order:

1. Delete job from Remote Copies - ImCmDeleteAll
2. Delete job from on-line operational database on the Main - ImDBAJobMgmt
3. Delete job from PDM on the Main - ImJmDelete
To delete job from the Remote Copies, execute the script ‘ImCmDeleteAll’ from the Main:
unix> ImCmDeleteAll -u {Oracle username} -j {job_name}
The ‘ImCmDeleteAll’ script deletes job from ALL Remote Copies the job was activated to and updates the
delete_status in the application_log with the success/failed delete status respectively for each Remote Copy under the
concerned job_id.
The ‘ImCmDeleteAll’ script continues to delete from ALL Remote Copy even if a delete fails on any Remote Copy.
However, the user cannot proceed with on-line operational database job delete until the job is successfully deleted
from ALL Copies.
Once the job is successfully deleted from all Copies, the user can execute ‘ImDBAJobMgmt’ script to delete job from
the on-line operational database on the Main:
unix> ImDBAJobMgmt -u {Oracle username} -j {job_name} -f D –a BA
After the successful deletion of job from the Copies and the on-line operational database, the PDM job can be deleted
from the Main:
unix> ImJmDelete -u {Oracle username} -j {job_name}
The job is now deleted and made permanent everywhere.

U0320 Revision: 1.0.0.0
Copy Management
3.4 Abandoning a Copy (ImCmAbandon)

There may arise a situation in which communication with a Copy database is failing due to reasons such as hardware
problems, downed pipes, unhealthy Oracle etc. When communication fails, the job activities cannot be completed and
the job will stay in ‘ODB_ACTIVATE_IN_PROGRESS’ state on the Main. This job cannot be deleted (i.e. changes
made permanent), or undone from the on-line operational database until it is successfully activated/undone to/from the
failing Copy as well. In such a scenario, the user can :
a. Fix the cause of the error on the Copy and retry the job propagation.
b. Abandon the erroneous Copy and continue with making the job changes permament on the Main and the
Copy(s) the job was successfully propagated to.
ImCmAbandon allows the abandoning of an ‘ACTIVE_COPY’ database in the system. Once a Copy is abandoned,
data changes cannot be propagated to the Copy until the Copy is once again ‘Resynch’ with the Main by using the
appropriate synchronization procedure detailed later in the chapter.

ImCmAbandon is a manual process; that is, a decision has to be made by the user to ‘abandon’ the Copy. It does not
happen automatically. Once a Copy is ‘abandoned’, its status in the copy_definition table on both the Main and the
PDM Copy (if available) changes to ‘ABANDONED’.
The same script ‘ImCmAbandon’ is used to abandon any Copy database - PDM or HIS.
To manually abandon the Copy, log in as UNIX user “imdba” and run the ImCmAbandon script as follows from the
Main:
unix> ImCmAbandon -u {Oracle username} -h {Copy host_name}
Upon successful completion of ImCmAbandon, the host specified will have a status of ‘ABANDONED’ in the
copy_definition table of the Main and the PDM Copy (if available).
When a Copy is ‘Abandoned’, it will need to be ‘Resynched’ to synchronize its database with the Main
3.5 Synchronizing the Copies with the Main (ImCmResynch)

The ‘ImCmResynch’ function synchronizes the database of the ‘PDM/HIS’ Copy with the ‘Main’. It ensures that all
tables managed under PDM job management are updated in the ‘Copy’ from the current primitive database (the
‘Main’).
This process is used when the systems are configured for the first time, and is also used if any ‘Copy’ database is
‘ABANDONED’ and needs to be Resynch with the ‘Main’. ImCmResynch will change a database that is in an
‘ABANDONED’ state to an ‘ACTIVE_COPY’ state.
Note: Prior to ImCmResynch, all PDM jobs must be removed from the system, either by cancelling or by
transferring/activating/deleting. The ImCmResynch process will fail if any PDM jobs exist and it will not allow any new
PDM jobs to be created during the synchronization process. This is necessary to ensure that the data is not changing
while the Resynch process is running.
After the synchronization process has successfully completed, the Copy(s) are in “synch” with the Main. All future job
actions will propogate to the Copy(s), if applicable, to keep the Copy(s) in synch.
3.5.1 Synchronizing the PDM Copy with the Main

To synchronize the database of the ‘PDM Copy’ with the ‘Main’, use the UNIX script ’ImCmResynch’ on the ‘Main’
center as stated below. Please note that ‘ImCmResynch’ needs to be run as UNIX user ‘imdba’.
unix> ImCmResynch -u {oracle_username} -h {Copy host_name} -d
{Copy database_type}
In our example, the command will be as follows:
unix> ImCmResynch -u prime -h PDM_BU -d PDM

U0320 Revision: 1.0.0.0
Copy Management
As the Resynch process is running, the statuses of both the Main and the PDM Copy will change to transient states.
Use the following select statement on both the Main and the PDM Copy:
sql> select * from copy_definition;
and it will show :
host_name link status db_type
{Main host_name {Main db_link} PAUSE_MAIN PDM
{PDM Copy host_name} {Copy db_link} RESYNCHING PDM
After the successful completion of Resynch process, the statuses of the Main and the PDM Copy will be updated on
both the Main and the PDM Copy(s). The PDM Copy will now become ‘ACTIVE_COPY’.

{Main host_name} {Main db_link} ACTIVE_MAIN PDM
{PDM Copy host_name} {Copy db_link} ACTIVE_COPY PDM
If a system is configured to have multiple ‘PDM Copy’ systems, ImCmResynch must be run individually for each ‘PDM
Copy’.
In the event that ImCmResynch should fail, the status of ‘PDM Copy’ would get set back to ‘ABANDONED’.
If a PDM Copy is ‘ABANDONED’, a resynchronization using ImCmResynch is the only action that will correct the
‘Copy’ and place it into an ‘ACTIVE_COPY’ state.
It is important to note that PDM jobs and data changes CANNOT be initiated from the ACTIVE_COPY. All data
changes need to be initiated from the ACTIVE_MAIN. The successful activation of data changes in the primitive
database “pushes” the changes from ACTIVE_MAIN to ACTIVE_COPY and enables the changes in the Copy.
Data can, however, be viewed on the ‘ACTIVE’ PDM Copy using sql*plus or Oracle forms.
3.5.2 Synchronizing the HIS Copy with the Main

To synchronize the database of the ‘HIS Copy’ with the ‘Main’, use the UNIX script ’ImCmResynch’ on the ‘Main’
center as stated below. Please note that ‘ImCmResynch’ needs to be run as UNIX user ‘imdba’.
unix> ImCmResynch –u {oracle_username} –h {Copy host_name} -d
{Copy database_type}
In our example, the command will be as follows:
unix> ImCmResynch -u prime -h HIS_BU – d HIS
As the Resynch process is running, the statuses of the Main and the HIS Copy will change to transient states on both
the Main and the PDM Copy(s). Use the following select statement on both the Main and the PDM Copy:
sql> select * from copy_definition;
and it will show:
{Main host_name} {Main db_link} PAUSE_MAIN PDM
{HIS Copy host_name} {Copy db_link} RESYNCHING HIS
After the successful completion of Resynch process, the statuses of the Main and the HIS Copy will be updated on
both the Main and the PDM Copy(s). The HIS Copy will now become ‘ACTIVE_COPY’.
{Main host_name} {Main db_link} ACTIVE_MAIN PDM
{HIS Copy host_name}{Copy db_link} ACTIVE_COPY HIS

U0320 Revision: 1.0.0.0
Copy Management
If a system is configured to have multiple ‘HIS Copy’ systems, ImCmResynch must be run individually for each ‘HIS
Copy’.
In the event that ImCmResynch should fail, the status of ‘HIS Copy’ would get set back to ‘ABANDONED’.
If a HIS Copy is ‘ABANDONED’, a reshychronization using ImCmResynch is the only action that will correct the ‘HIS
Copy’ and place it into an ‘ACTIVE_COPY’ state.
3.6 Failing Over to PDM Copy (ImCmFailover)

ImCmFailover is the means of failing primitive database functions to the ‘PDM Copy’. Literally, it means swapping the
roles of the Main and the PDM Copy.
If the primitive database (‘Main’) were to become unavailable due to, say, technical problems, storm damage etc., the
user would initiate failover from the PDM Copy which would enable the PDM Copy to take over all of the functions of
the Main.
Please note that the ‘PDM failover’ is not an automatic function; it comes into effect only after user intervention.
The PDM Failover process performs the following functions. It:
1. Resets all sequence generators to the current maximum.
2. Rebuilds the s_internal_number table.
3. Updates the copy_definition table with the correct status.
The reset and rebuild of internal control tables and sequence number generators assures proper operation of PDM Job
Management software after the Failover is complete.
To execute Failover, as UNIX user ‘imdba’, run the UNIX script ‘ImCmFailover’ on the PDM Copy which is to takeover
the Main functionality, as follows:
unix> ImCmFailover -u oracle_username

After the successful Failover completion, the ‘PDM Copy’ will become ‘ACTIVE_MAIN’, and the ‘Main’ will become
‘ACTIVE_COPY’ (if it is still available in real-time scenario) or will become ‘ABANDONED’ (if it is not available). The
availability of the former Main will be determined by several factors such as the Oracle SID being up, the LAN being
up, etc. on the former Main.
Failovers can be classified in two ways:
1. Planned Failovers.
2. Catastrophic Failovers.
3.6.1 Planned Failovers

Planned Failovers are scheduled failovers of the Main to the Backup (PDM Copy) for the purpose of catastrophe
training or for the verification of Main functionality on the Backup Control Center.
Because a planned failover is scheduled, all PDM jobs must be cancelled, or activated and deleted, prior to initiating
the failover command. This is necessary to ensure the consistency of data across all database Copies- PDM and
HIS/EA.
3.6.2 Catastrophic Failovers

A Catastrophic failover is one that, by definition, assumes that the Main is no longer available and its database will
need to be resynchronized when it becomes available again. During this type of failover, end- user intervention will
be necessary after the failover to the new Main to ensure that all data is consistent across multiple database copies
PDM and HIS/EA.
The presence of jobs in the PDM_SENT state on the new Main indicates that job activation activity had commenced.
This data can provide some clues as to the state of the data, but will require the user to look up additional information

U0320 Revision: 1.0.0.0
Copy Management
3.6.2.1 Option 1 - Manual verification of data

For each PDM job, the user will need to perform the following steps to determine the state of the data propagation to
relevant database copies. Please note that no reversal of the data changes in the job is allowed without re-creation of
the contents of the application_log table. Such manual steps, while possible, are quite difficult to describe.
1. Check DBA system for the presence of job by the same name. This really must be there as the PDM_SENT job
state is not possible without the on-line operational database activation completing successfully.
unix> dmt
unix> dmt> jadm all
- Presence of job indicates that job had been activated within on-line operational database.
- This will need to be deleted - made permanent
unix> dmt> jn <job name>

unix> dmt> deljob
2. Execute ImRptChgLog for the job in PDM.
3. View the report output to determine data changes for HIS/EA or CFE
HIS Look for tables ACC_HIS, ANA_HIS, DIG_HIS. Note: Changes in the B1, B2, B3 and ELEMENT tables also
affect the HIS data. Specifically the Name, Technological Area Number and LogBook Text columns.
EA Look for tables EA_CONTROL_AREA, EA_TIE_CORRIDOR, EA_TIE_LINE, EA_TIE_POINT.
Check the HIS/EA operational data for evidence of the changes recorded in the report. For HIS changes, the
views affected in the HIS database would be HIS_TA_ANALOG, HIS_TA_ACCU, HIS_TA_DIGITAL.
For EA changes, the views affected would be EA_CTRL_AREA, EA_TIE_CORRIDOR, EA_TIE, EA_GROUP,
EA_LOAD_NAME, EA_GEN_NAME, EA_TA_NAMES, EA_AUTHORISED_TA, EA_PREPROCESSED_TA.
If the expected data changes are not in place in the HIS database, the HIS copy will need to be abandoned and
resynched. Subsequent jobs affecting HIS/EA do not need to be verified as the resynch will cover all the data.
4. Delete job from PDM.
unix> sqlplus prime
sql> insert into job_log history (select * from job_log where

job_id=(select job_id from job_log where job_name=<job_name>));
sql> insert into change_log history (select * from change_log where

job_id=(select job_id from job_log where job_name=<job_name>));
sql> delete from change_log where job_id=(select job_id from job_log

where job_name=<job_name>);
sql> delete from job_log where job_name=<job_name>;
3.6.2.2 Option 2 - Resynch primitive data with contents of operational databases

While the steps in this option will take some time and data changes cannot be made until all the steps are complete,
this method ensures that the data will be consistent without a lot of manual checking being required.
1. Delete on-line operational DBA jobs.
unix> dmt

U0320 Revision: 1.0.0.0
Copy Management
unix> dmt> jadm all

unix> dmt> jn <job name>
unix> dmt> deljob
2. Run ImOraSchema.plx.
As UNIX user ‘imdba’, run ImOraInstall.plx to recreate the PDM schema in the EMP Oracle database.
unix> ImOraSchema.plx –app PDM –db emp –drop Y
3. ImBaRvFilltab
Run ImBaRvFilltab to reverse transfer the filltab table information from on-line operational database. The directory
'{filltab directory}' must exist before executing this command.
unix> ImBaRvFilltab -p {filltab directory} -c 1000

4. ImBaLoadFilltab
Load the generated filltab files into PDM.
unix> ImBaLoadFilltab -u {Oracle username} -d {directory containing
filltab files}
If this is a multi-site system, then filltab file workstation_name.rtds is not created by ImBaRvFilltab but must be
manually maintained. In that case the workstation_name.rtds file needs to be manually loaded into SQLPLUS as
follows:
SQL > truncate table workstation_name;
SQL > @ [DIR]/workstation_name.rtds;
SQL > commit;
Where DIR is the directory where the workstation_name.rtds file is being maintained.
For more information on maintaining the workstation_name.rtds filltab file, see the chapter “Control Tables for BA
and RTDS Subsystems” in the U0385 Primitive Database Maintenance User Guide.
5. ImBaRvIddug
Run ImBaRvIddug to reverse transfer the IDDUG information from on-line operational database to be loaded into
PDM. This step will dump out the IDDUGS for SCADA, RTDS/ CFE, SAM, REFERENCES, ICCP, CMCH, EA and
HIS records.
unix> ImBaRvIddug -l {directory where IDDUGS should be stored} -a
abcdefg -h y -u {Oracle username}
6. ImBaImportDirectory
Run ImBaImportDirectory with change detect turned off to import all the data exported from on-line operational
database into PDM.
unix> ImBaImportDirectory -u prime -d {directory containing
generated IDDUGS} -c N -e 1000 -r Y
7. ImEsCfeImport
If the system is configured with CFE, then run ImEsCfeImport as follows to load the default IDDUG:
unix> ImEsCfeImport -u prime -j {job name} -i
$SPECPATH/src/rdbms/ImEs/cfe_default_iddug3.0
8. ImBaRvUpdateIds
Before running UpdateIds to synchronize the internal numbers in PDM with on-line operational database, the HIS
Copy will need to be ABANDONED. To abandon the HIS Copy, log in as user “imdba” and run the ImCmAbandon
script as follows from the new Main:
unix> ImCmAbandon -u prime -h {HIS Copy host_name}

U0320 Revision: 1.0.0.0
Copy Management
Upon successful completion of ImCmAbandon, the host specified will have a status of ‘ABANDONED’ in the
copy_definition table of the Main.
Now run UpdateIds on the new Main:
unix> ImBaRvUpdateIds -u {Oracle username} -j {job name} -e Y
9. Re-synchronize the HIS Copy with the new Main by running the following commands on the new Main as UNIX
user ‘imdba’:
unix> ImCmResynch -u {oracle_username} -h {HIS Copy host_name} -d
HIS
The new Main will now be available for data processing and propagation.

U0320 Revision: 1.0.0.0
Job Status
4 Job Status
The job status identifies the state of the job. What actions a user may perform on a job is dependent on the current
state of the job. The possible job states are described below and the transitions between these states are detailed in
Table 5-1.
READY— The job is ready for either input of data or transfer to the offline operational database.
EDITING— Someone is currently connected to this job for data edit purposes. This is a transient state. When the
edit session is finished, the status of the job will be set to ready.
TRANSFER_IN_PROGRESS— In the process of transferring the changes associated with this job to the offline
operational database.
TRANSFERRED— This job has been transferred to the offline operational database.
ODB_ACTIVATE_IN_PROGRESS— In the process of activating this job from the offline operational database to
the online operational database.
If Remote Copies are defined and are ACTIVE, this job status also means that the job has been activated to the
online operational database and is pending activation to one or more Active Remote Copies.
ODB_ACTIVATED— This job has been activated into the online operational database.
If Remote Copies are defined, this status means that the job has been activated to the Remote Copies as well.
AA_ONLY_TRANSFERRED— This job affected only AA applications that have no activation program and all
affected applications have been transferred to the offline operational database.
AA_ONLY_SKIPPED— This job affected only AA applications that have no activation program and all affected
applications have been skipped.
ODB_DELETE_IN_PROGRESS— In the process of deleting the job from the operational database job log and
from Remote Copies (if defined).
ODB_DELETED— This job has been deleted from the operational database job log and from the Remote Copies
(if defined). The changes were applied to both the offline and online operational database, and to the Remote
Copies. The only option open to the user is to delete this job from the primitive database.
ODB_DELETE_FAILED— Deletion of this job from the operational database job log failed.
DELETING— In the process of deleting this job from the primitive database tables. This is a transient state. When
the delete is finished, this job no longer exists and the changes are permanent in both the primitive database and
the operational database.
DELETE_FAILED— Deleting of this job form the primitive database tables failed.
UNDOING— In the process of removing the changes made by this job from the primitive database tables. This is a
transient state.
UNDONE— The changes associated with this job have been removed from the primitive database tables. No
further changes may be made to primitive data through a job whose status is undone.
UNDO_FAILED— Undo of the changes associated with this job failed.
REDOING— In the process of re-applying the changes associated with this job to the primitive database tables.
This is a transient state. When the redo is finished, the status of the job is set to ready.
REDO_FAILED— Re-applying the changes associated with this job to the primitive database tables failed.
CANCELLING— In the process of cancelling this job from the primitive database tables. This is a transient state.
When the cancel is finished, this job no longer exists and the primitive database has been returned to its state prior
to this job.
CANCEL_FAILED— Canceling of this job from the primitive database tables failed.
U0320 Revision: 1.0.0.0
Job Status
CANCELLING_TASK— In the process of cancelling the last task of this job from the primitive database tables. This
is a transient state. When the cancel task is finished, the job state is set to ready.
CANCEL_TASK_FAILED— Canceling of the last task of this job from the primitive database tables failed.
OP_RDBMS_ONLY— This job affects only applications with an operational PDM. No transfer is required -- only
activation.
OTS_ONLY— Indicates this job has changes which only affect the OTS application.
ASR_WRITE_SUCCESS— Only relevant for CFE on AIX configurations. Transient state indicating a successful
write of the Bulk ASR Change Log file by ImAsrExportBulk.
Table 4-1: Job Status - Action and Results
Job Status Action Resulting Job Status
Edit EDITING
TRANSFER_IN_PROGRESS
Transfer or
OP_RDBMS_ONLY
READY
Undo UNDOING
CANCELLING
Cancel or
CANCELLING_TASK
EDITING (Complete) READY
Transfer TRANSFER_IN_PROGRESS
Cancel TRANSFER_IN_PROGRESS
TRANSFERRED (transfer)
or
TRANSFER_IN_PROGRESS (transfer)
TRANSFER_IN_PROGRESS (Complete) or
AA_ONLY_TRANSFERRED (transfer)
or
READY (cancel)
(Failed) TRANSFER_IN_PROGRESS (failure reported in

application_log/transfer_status)
Activate ODB_ACTIVATE_IN_PROGRESS
TRANSFERRED
Cancel TRANSFER_IN_PROGRESS

U0320 Revision: 1.0.0.0
Job Status
Activate ODB_ACTIVATE_IN_PROGRESS
Undo ODB_ACTIVATE_IN_PROGRESS
ODB_ACTIVATED (activate)
or
ODB_ACTIVATE_IN_PROGRESS ODB_ACTIVATE_IN_PROGRESS (activate to Remote
(Complete)
Copies)
or
TRANSFERRED (undo)
ODB_ACTIVATE_IN_PROGRESS (failure reported in

(Failed)
application_log/activate_status)
Undo ODB_ACTIVATE_IN_PROGRES
ODB_ACTIVATED
Delete ODB_DELETING
Delete ODB_DELETE_IN_PROGRESS
(Complete) PDM_ACTIVATED
PDM_ACTIVATING
PDM_ACTIVATED (Copy which failed to activate will be
(Failed)
ABANDONED)
Undo PDM_UNDOING
PDM_ACTIVATED
Delete PDM_DELETING
Complete) ODB_ACTIVATED
PDM_UNDOING
ODB_ACTIVATED (Copy which failed to undo will be
(Failed)
ABANDONED)
Delete ODB_DELETE_IN_PROGRESS
ODB_DELETED
(Complete) or
ODB_DELETE_IN_PROGRESS
ODB_DELETE_IN_PROGRESS
ODB_DELETE_IN_PROGRESS (failure reported in

(Failed)
application_log/delete_status)
ODB_DELETED Delete DELETING
PDM_DELETING (Complete) PDM_DELETED

U0320 Revision: 1.0.0.0
Job Status
PDM_DELETED (Copy which failed to delete will be

(Failed)
ABANDONED)
PDM_DELETED Delete ODB_DELETE_IN_PROGRESS

(Complete) UNDONE
UNDOING
(Failed) UNDO_FAILED
Redo REDOING
UNDONE
Cancel CANCELLING
(Complete) READY
REDOING
(Failed) REDO_FAILED
(Complete) Job cancelled. No longer in job log.
CANCELLING
(Failed) CANCEL_FAILED
(Complete) Job deleted. No longer in job log.
DELETING
(Failed) DELETE_FAILED
AA_ONLY_TRANSFERRED Delete DELETING
(Complete) READY
CANCELLING_TASK
(Failed) CANCEL_TASK_FAILED
Delete DELETING
AA_ONLY_SKIPPED
Cancel CANCELLING
OP_RDBMS_ONLY Activate ODB_ACTIVATE_IN_PROGR

U0320 Revision: 1.0.0.0
Application Status
5 Application Status
Job Transfer, being smart enough to know what data has changed and to which applications that data belongs, uses
this intelligence to write an entry into the Application Log for each affected application. First Job Transfer and then
ODB Activation use the Application Log to track what has been run and whether or not it was successfully completed.
The success or failure is registered in the Application log by using one of the following statuses. To understand the
transitions between these states refer to Table 5-1.
With Copy Management and PDM-Initiated Activation, Job Transfer has been enhanced to create an entry in the
Application Log for each Active Remote Copy that has been defined in the system. Depending on the type of data
change made, the activate_status in the Application Log is updated to either ‘Activation Required’ or ‘Not Required’.
5.1 Transfer status

READY— The application is ready to be transferred to the offline operational database for this job.
TRANSFERRING— In the process of transferring the changes associated with this job and application to the offline
operational database. This is a transient state.
TRANSFERRED— This job has been transferred to the offline operational database for this application.
TRANSFER_FAILED— A failure occurred during transfer for this application. The error must be corrected before
proceeding.
TRANSFER_SKIPPED— Transfer was skipped for this application and this job. Transfer should be run at some
later date to keep the primitive database and the operational database in sync.
NOT_NEEDED— Transfer is not needed for this application and this job. Activation will need to be run for this job
and application later. (Data changes affected this application and this job, but there is no transfer program for the
application, only an activation program.)
ODB_CANCELLING—In the process of undoing the changes from the offline operational database for this
application and removing the job from the operational database. This is a transient state.
ODB_CANCEL_FAILED—A failure occurred during cancel for this application and job.

U0320 Revision: 1.0.0.0
Application Status
5.2 Activation Status

ODB_READY— This application is ready to be activated to the online operational database for this job.
TEST_ACTIVATING— In the process of activating this application for this job from the offline operational to the test
operational database. This is a transient state.
TEST_ACTIVATED— This application has been transferred from the offline operational to the test operational
database for this job.
TEST_ACTIVATE_FAILED—Activation from the offline operational to the test operational database for this
application and job failed.
TEST_UNDOING— In the process of undoing the changes from the test operational database for this application
and job. The changes still exist in the offline operational database. This is a transient state.
TEST_UNDOING_FAILED— Undo of the changes from the test operational database failed. The changes still exist
in both the test and offline operational database.
ODB_ACTIVATING— In the process of activating this application for this job from the offline operational (or test
operational) to the online operational database.
ODB_ACTIVATE_FAILED— Activation from the offline operational (or test operational) database for this
application and job failed.
ODB_ACTIVATED— This application has been transferred from the offline operational (or test operational) to the
online operational database for this job.
ODB_UNDOING— In the process of undoing the changes from the online operational database for this application
and job. The changes still exist in the offline operational (or test operational) database. This is a transient state.
ODB_UNDO_FAILED— Undo of the changes from the online operational database failed. The changes still exist in
both the online and offline operational database (and the test operational if one exists).
INITSOS_NA_SERVER— No script exists to transfer this applications data changes to the online operational
database. To activate the data changes, the NA server must be INITSOSed
DONE_AS_PART_OF_BA— A separate activation is not required to transfer the data changes to the online
operational database for this application. The activation is done as part of the BA application transfer.
PDM_SEND_REQ— This job will require an activation from the online operational database to the PDM copy.
PDM_SENDING—In the process of activating this job from the online operational database to the PDM copy.
PDM_SENT— This job has been activated from the online operational database to the PDM Copy.
PDM_SEND_FAILED — Activation for this job from the online operational database to the PDM Copy failed.
PDM_UNDOING — In the process of undoing the changes associated with this job from the PDM Copy. The
changes still exist in the online operational database. This is a transient state.
PDM_UNDO_FAILED — Undo of the changes from the PDM Copy failed. The changes still exist in the PDM Copy.
HIS_NOT_NEEDED — The changes associated with this job are not required to be activated to the HIS Copy as
the changes are not HIS related.
HIS_ACTIVATION_REQ — The changes associated with this job require to be activated to the HIS Copy.
HIS_ACTIVATING — In the process of activating the HIS realted job changes to the HIS database on the HIS
Copy. This is a transient state.
HIS_ACTIVATED — The data changes have been successfully activated to the HIS database on the HIS Copy.
They are available for the collection programs running on the HIS database.

U0320 Revision: 1.0.0.0
Application Status
HIS_ACTIVATE_FAILED — The activation of the HIS data on the HIS Copy failed. The changes are not available
to the HIS database.
HIS_UNDOING — In the process of undoing the activation of the job from the HIS Copy. This is a transient state.
When the undo is finished, this job is no longer activated on the HIS Copy.
HIS_UNDO_FAILED — Undo of the activation of job from the HIS Copy failed. The changes are still activated to
the HIS database on the HIS Copy.
EA_NOT_NEEDED — The changes associated with this job are not required to be activated to the HIS Copy as
the changes are not EA related.
EA_ACTIVATION_REQ — The changes associated with this job require to be activated to the HIS Copy as there
are some EA related changes.
EA_ACTIVATING — In the process of activating the EA related job changes to the HIS database on the HIS Copy.
This is a transient state.
EA_ACTIVATED — The EA data changes have been successfully activated to the HIS database on the HIS Copy.
EA_ACTIVATE_FAILED — The activation of the EA data on the HIS Copy failed. The changes are not available to
the HIS database.
EA_UNDOING — In the process of undoing the activation of the EA related job changes from the HIS Copy. This is
a transient state. When the undo is finished, this job is no longer activated on the HIS Copy.
EA_UNDO_FAILED — Undo of activation of the EA related job changes from the HIS Copy failed. The changes
are still activated to the HIS database on the HIS Copy.
NOT_NEEDED/XFER SKIPPED— Indicates that an activation is unnecessary either because no activation is
defined for this application or because the user elected to skip the transfer.

U0320 Revision: 1.0.0.0
Application Status
5.3 Delete Status

NOT_NEEDED— Job deletion is not needed for this application and job.
OBD_DELETE_READY— Ready for delete of this job from operational job log for the application.
ODB_DELETING— In the process of deleting this job from the operational job log for this application.
ODB_DELETE_FAILED— Operational job log deletion failed.
DONE_AS_PART_OF_BA— Operation job log deletion is done as part of the BA application delete.
ODB_DELETED— Job has been successfully deleted from the Operational job log.
PDM_DELETING— In the process of deleting this job from the PDM Copy.
PDM_DELETE_FAILED— Job deletion on PDM Copy failed.

PDM_DELETED — Job has been successfully deleted on PDM Copy. The changes have been made permanent.
HIS_DELETE_READY— Ready for deletion of this job from the HIS Copy.
HIS_DELETE_FAILED— Job deletion on HIS Copy failed.
HIS_DELETED — Job has been successfully deleted on HIS Copy. The changes have been made permanent.
EA_DELETE_READY— Ready for deletion of this job from the HIS Copy.
EA_DELETE_FAILED— Job deletion on HIS Copy failed.
EA_DELETED — Job has been successfully deleted on HIS Copy. The changes have been made permanent.

U0320 Revision: 1.0.0.0
Application Status
Table 5-1: Application Log Status - Action and Results
Application Status Action Resulting Application Status

Transfer READY -> TRANSFERRING ->TRANSFERRED
Transfer Status
Cancel TRANSFERRED -> ODB_CANCELLING -> READY
ODB_READY -> ODB_TEST_ACTIVATING ->
BA Activate ODB_TEST_ACTIVATED -> ODB_ACTIVATING ->
Activate Status ODB_ACTIVATED
ODB_ACTIVATED -> ODB_UNDOING ->
Undo ODB_TEST_ACTIVATED -> ODB_TEST_UNDOING
-> ODB_READY
Delete Status Delete ODB_DELETE_READY -> ODB_DELETING ->
ODB_DELETED
Transfer Status Transfer READY -> TRANSFERRING ->TRANSFERRED
Cancel TRANSFERRED -> ODB_CANCELLING -> READY
ODB_READY -> ODB_TEST_ACTIVATING ->
ODB_TEST_ACTIVATED -> ODB_ACTIVATING ->
Activate ODB_ACTIVATED
or
DONE_AS_PART_OF_BA
Activate Status
AGC ODB_ACTIVATED -> ODB_UNDOING ->
ODB_TEST_ACTIVATED -> ODB_TEST_UNDOING ->
Undo ODB_READY
or
DONE_AS_PART_OF_BA
ODB_DELETE_READY -> ODB_DELETING ->
ODB_DELETED
Delete Status Delete
or
DONE_AS_PART_OF_BA
Transfer Status Transfer NOT_NEEDED
Activate ODB_READY -> ODB_ACTIVATING -> ODB_ACTIVATED
Activate Status
RDBMS Undo ODB_ACTIVATED -> ODB_UNDOING -> ODB_READY
ODB_DELETE_READY -> ODB_DELETING ->
Delete Status Delete
ODB_DELETED
Transfer READY -> TRANSFERRING -> TRANSFERRED
Transfer Status
Skip READY -> TRANSFERRED_SKIPPED
AA Applications
Activate Status Activate INITOS_NA_SERVER
Delete Status Delete NOT_NEEDED

U0320 Revision: 1.0.0.0
Job Interlocks
6 Job Interlocks
Job interlocks prevent different jobs from changing the same data. For example if job ‘crystal’ had a job interlock on the
B1 name of ‘crystal’ then only job ‘crystal’ would be allowed to modify any data in the ‘crystal’ B1 hierarchy. Note that
this includes all lower levels of the hierarchy also (e.g. B2 B3 Element and Info data for ‘crystal’).
Job interlocking is performed automatically whenever any user or application tries to change data. This includes import
forms and sql*plus. If a job does try to modify data that is locked by another job an error message that identifies the job
that holds the job interlock for this data is written to the MSG table and the change is rolled back.
Job interlocks are released when a job is deleted or cancelled.
6.1 B1 Hierarchy Job Interlocks

B1 hierarchy data will be locked at the B1, B2 or B3 level depending on what data was modified. This locking level can
best be illustrated using some examples:
Example 1.
If one job modified B1=crystal, then no other job may modify this B1 nor any of the B2, B3, element or infos below this
B1. A different job would be able to modify the data for any other B1.
Example 2.
If one job modified B1=crystal, B2=220K then no other job may modify this B2 nor any of the B3, element or infos
below this B1/B2. A different job would be able to modify the data for any other B2.
Example 3.
If one job modified B1=crystal, B2=220K and B3=BB1A, then no other job may modify this B3 nor any of the elements
or infos below this B1/B2/B3. A different job would be able to modify the data for any other B3.
Example 4.
If one job modified data for B1=crystal, B2=220K, B3=BRCST3, Element=CB 1, Info=CB trip, then the data is locked
for B3=BRCST3. No other job may modify this B3 nor any of the elements or infos below this B1/B2/B3. A different job
would be able to modify the data for any other B3.
6.2 ICCP Job Interlocks

There are two types of ICCP data interlocks: ICCP and ICCP_SYS.
The ICCP_SYS interlock type is used only for table iccp_system.
The ICCP interlock type allows for locking at the instance level for access and transfer points. All other tables are
locked at the level of the iccp remote.
6.3 Load Shed Job Interlocks

The Load Shed interlock type is a grouping of all Load Shed tables. Only one job may modify Load Shed data at a
time. This job must be transferred activated and deleted before any other job may edit Load Shed data.
6.4 Reference Job Interlocks

Reference data is locked by the B1 name listed in the b1_name_from_side column. For example if one job modified
the reference data where the b1_name_from_side=crystal then no other job may modify any reference data with a
value of ‘crystal’ in the b1_name_from_side column.

U0320 Revision: 1.0.0.0
Job Interlocks
6.5 RTDS/CFE Job Interlocks

The RTDS/CFE data job interlocks are of three types - RTDS, RTU, and CMCH.
The RTDS interlock type is a grouping of the following tables: rtu_protocol_type, scsi_adapter_module,
com_interface_adapter, channel, rtu_line, rtu_group. For example, if one job modified any data in any of these tables,
then no other job may modify these tables.
The RTU interlock type is for an RTU and its scan data. For example, if one job modified RTU=rtu_1, then no other job
may modify this RTU nor any of the scan data corresponding to this RTU.
The CMCH interlock type is for a characteristic curve and its data points, namely tables cmch and devchar.
6.6 Underfrequency Load Shed Job Interlocks

The Underfrequency Load Shed interlock type is a grouping of all Underfrequency Load Shed tables. Only one job may
modify Underfrequency Load Shed data at a time. This job must be transferred activated and deleted before any other
job may edit Underfrequency Load Shed data.
6.7 Voltage Reduction Job Interlocks

The Voltage Reduction interlock type is a grouping of all Voltage Reduction tables. Only one job may modify Voltage
Reduction data at a time. This job must be transferred activated and deleted before any other job may edit Voltage
Reduction data.
6.8 Voltage Set Range Job Interlocks

Voltage set range data is locked at the job level. Only one job may access this data at a time. This job must be
transferred activated and deleted before any other job may edit voltage set range data.
6.9 Energy Accounting Job Interlocks

The Energy Accounting Data job interlocks are of two types - ECTLA and EA.
The ECTLA job interlock type affects the ea_control_area table and the ea_tie_line table. The ea_tie_line table has a
foreign key reference to the ea_control_area table, so any ea_tie_line record which references a locked
ea_control_area will also be locked.
The EA job interlock type affects the ea_tie_corridor, ea_tie_line, and ea_tie_point tables.
6.10 AA Job Interlocks

AA data is locked at the record level. Only one job may access a particular record at a time. This job must be
transferred activated and deleted before any other job can edit the same record.
If script ImAaImport is run then all AA data is locked until the ImAaImport script has completed.

U0320 Revision: 1.0.0.0
Job Interlocks
6.11 Job Interlock Report

The job interlock report displays the current jobs and the data that is locked by the jobs. ImRptIlock.sql is the SQL*Plus
report script. The UNIX menu script ImRpt may also be used. An example usage is:
sql> @ImRptIlock
Enter value for report_output: ilock.out
Enter value for job_name: %
Job Name Job Id Task Name Task Id Lock Lock Lock Key1 Lock Key2 Lock Key3
Type level
------- --- ------------------ ---- ----- ----- ------- ---- ----

BRCREEK 2 pkg_import_ba. 2 BLOCK B1 BRCREEK

main
Star1 36 B3 3 BLOCK B3 Star1 220 Eth
The Job Interlock report may also be run from the REP form within Oracle Forms. See the PDM Forms User Guide -
U0325.

U0320 Revision: 1.0.0.0
General Notes on the Usage of the PDM Interface Scripts
7 General Notes on the Usage of the PDM Interface Scripts

7.1 Accessing the PDM Interface
The PDM Interface executes on the Spectrum Power 3 ADM server.
To utilize the PDM Interface, the user must log into the ADM server using a valid UNIX username. This login
establishes the Spectrum Power 3 user environment.
The PDM Interface accesses the PDM schema in the PDM EMP Oracle database. The PDM schema is owned by
Oracle user PRIME. Additional Oracle users may be created in the PDM EMP Oracle database that have the ability to
view (read) the data in the PDM schema and also change (insert, update and delete) the data using PDM Interface
jobs. See the Primitive Database Maintenance User Guide - U0385 for more information on creating the additional
Oracle users.
7.2 Im.profile and Im.kshrc

The environment setup which is unique to the PDM Interface is defined in the files Im.profile and Im.kshrc.
Im.profile defines the environment variables needed by Oracle. See the man page on Im.profile for more information.
Im.kshrc defines the korn shell aliases which allow the user easy maneuvering within the source UNIX directory tree.
See the man page on Im.kshrc for a description of the PDM Interface UNIX directory and a listing of the aliases. It is
strongly recommended that the user take the time to learn these aliases. They are very helpful in navigating around the
tree. An example of the alias which will change the users current directory to the location where the Oracle create table
source files reside is:
unix> cdtb
Compare this with typing the following:
unix> cd $SPECPATH/src/schema/pdm/owner/prime/table
7.3 PDM Interface Scripts

The PDM Interface functions are executed through a combination of UNIX scripts and SQL*Plus scripts. Throughout
this document, examples of executing UNIX scripts from the command line are show by:
unix> filename
Examples of executing sqlplus scripts from the Oracle SQL*Plus utility command line are shown by:
sql> @filename
Note that sqlplus scripts are executed by preceding the filename to be run with an @ sign. The @ command reads and
executes the contents of the file whose name is “filename.sql”. The extension “.sql” is automatically appended unless
the specified filename contains an extension. When supplying parameter values for sqlplus scripts, the wildcard
character % can be used in many cases. Refer to the Oracle SQL manual for more information on wildcard characters.

U0320 Revision: 1.0.0.0
7.4 man pages

Use the UNIX man command to see a description of PDM Interface scripts a list of all the available options and usage
examples. An example of man usage is:
unix> man Im.kshrc echora
The script echora contains echo statements for the various Oracle environment variables that might be of interest to an
Oracle user. For example:
unix> echora
ORACLE_SID= emp1
ORACLE_HOME= /u01/app/oracle/product/10.2.0/db_1
ORACLE_BASE= /u01/app/oracle
DBA= /u01/app/oracle/admin
ORACLE_PATH= /home/p/form
SQLPATH= /home/p/sys/rdbms
ORACLE_SERVER_HOME= /u01/app/oracle/product/10.2.0/db_1
ORACLE_ASM_HOME= /u01/app/oracle/product/10.2.0/asm_1
ORACLE_CRS_HOME= /u01/crs/oracle/product/10.2.0/crs_1
ORACLE_OID_HOME= /u01/app/oracle/product/10.1.4/oid_1
ORACLE_CLIENT_HOME= /u01/app/oracle/product/6.0.8/forms_1
TWO_TASK=
EMP_CONNECT= emp.world
GCS_CONNECT= gcs.world
OS_CONNECT= os.world
RDBMS_TOP_PN= /home/p
INCLUDE_TOP_PN= /home/p
SINCLUDE_PN= /home/p/src/rdbms/ImCustom
TABLESPACE_PN_FN= /home/p/sys/rdbms/ImOraDataTS
RUN_PN= /home/imdba
Current pwd = /home/imdba
For a description of the environment variables displayed by echora, use the command:
unix> echora ?
For a list of variables pertaining to PDM schema creation (ImOraSchema.plx), use the command:
unix> echora -i

U0320 Revision: 1.0.0.0
Refer to the echora man page for more information on script options.
When echora is used with the help option it gives a description of what the environment variable is used for. For
example:
unix> echora help
The database in Oracle that will be accessed is this SID.
ORACLE_SID= emp1
The location of the Oracle software is ORACLE_HOME.

ORACLE_HOME= /usr/oracle
For OFA, The location of the Oracle software owner’s home.

ORACLE_BASE= /u01/app/oracle
For OFA, the location of the Oracle software owner’s admin files.
DBA= /u01/app/oracle/admin
Oracle searches ORACLE_PATH for .frm files, glogin.sql and

login.sql.
ORACLE_PATH= /home/p/form
Oracle searches SQLPATH for scripts run from within a sqlplus

session.
SQLPATH= /home/p/sys/rdbms
The location of the Oracle server software is ORACLE_SERVER_HOME.

ORACLE_SERVER_HOME= /u01/app/oracle/product/10.2.0/db_1
The location of the Oracle client software is ORACLE_CLIENT_HOME.

ORACLE_CLIENT_HOME= /u01/app/oracle/product/6.0.8/forms_1
The default connection string used when a client connects to

ORACLE.
TWO_TASK=
The following connectstrings have been pre-defined for use by

programs (using OraConnect) and scripts (using OTL).
EMP_CONNECT= emp.world
GCS_CONNECT= gcs.world
OS_CONNECT= os.world
RDBMS Interface scripts use RDBMS_TOP_PN as the top part of the

path when locating source scripts and data.
RDBMS_TOP_PN= /home/p
INSTALL_CLUSTER= y
When set to 'y', the INSTALL_CCLUSTER variable. directs the Oracle
database build tools (e.g. ImOraInstall) to use the ‘raw device’
path for tablespace file creation. If unset the default
$ORACLE_HOME path is used.

U0320 Revision: 1.0.0.0
The connectivity strategy for Spectrum Power 3 programs that must

connect to an Oracle database is dependent on the existence of both
an environmental variable (xxx_CONNECT where ‘xxx’ = Oracle
database name) and the valid definition (in the /etc/tnsnames.ora
file) of a connect string. The current values of these specific
variables are reported by the echora script.
Parameter Substitution uses INCLUDE_TOP_PN for determining where to

get include files.
INCLUDE_TOP_PN= /home/p
Parameter Substitution uses SINCLUDE_PN for determining where to

get sinclude files (i.e. optional include files).

SINCLUDE_PN= /home/p/src/rdbms/ImCustom
RDBMS Interface scripts check that one runs from $RUN_PN.

RUN_PN= current value of variable RUN_PN
RDBMS Interface scripts, by default, puts output files in the

current working directory.
Current pwd = (current directory)
The end of the output from 'echora help' consists of the same information that is output by the command 'echora' (with
no options).
7.5 The “run” directory

Many of the PDM Interface scripts require that execution be initiated from what is known as the “run” directory. The run
directory is the value of the RUN_PN environment variable. echora may be used to see the current value of RUN_PN.
If the script is not initiated from the run directory, the following message will be displayed:
The current working directory is not the allowed run directory.
CWD= /home/p/src/schema/pdm/owner/prime/table
Change what is in environment variable RUN_PN or move via:
cd /home/imdba
The run directory was established to prevent the output files generated by scripts from cluttering up directories where
their existence may cause harm. Most notably the directories which contain Oracle schema source. The user may
override the default run directory location by placing the absolute path of the desired directory into the RUN_PN
environment variable.
7.6 Autonomous Transactions

The PDM Interface uses Oracle Autonomous Transactions to pass messages from the various scripts, programs,
procedures and forms to the Oracle message table MSG and trace table JOB_TRACE. PDM Interface Oracle
messages are created by calling Oracle package.procedure 'pkg_msg.issue' stored in Oracle, which in turn creates an
Autonomous Transaction to insert the requested message records in table MSG. Similarly, trace records are created
by calling PDM Interface Oracle package.procedure 'pkg_jobt.put_line', which also creates an Autonomous
Transaction to insert any trace records in table JOB_TRACE. This is done so that the code calling 'pkg_msg.issue'
and/or 'pkg_jobt.put_line' can then rollback any data changes causing errors without affecting the insertion of the
message and trace records to be used to determine the cause of data errors.

U0320 Revision: 1.0.0.0
Creating a Job/Connecting to a Job
8 Creating a Job/Connecting to a Job

A separate UNIX script does not exist to create a new job or connect to an existing job. Instead when a user executes
other PDM Interface scripts to accomplish a particular PDM Interface function (e.g. import) that script accepts a job
name as input and either creates the new job or connects to the existing job. Because there is no need to distinguish
between creating a new job and connecting to an existing job the phrase “connecting to a job” will be used to cover
both cases.
When selecting a new job name, choose one that has no more than 8 characters and one that does not have any
embedded blanks.
Only one user may be connected to a job at one time. If you are having trouble connecting to an existing job then
check to make sure the job is not currently in use. For example,
sql> @gjob mary

CURRENT_USERNAME
JOB_NAME STATUS CURRENT_DATE_TIME
LAST_USED_USERNAME
CREATION_USERNAME
JOB_ID LOCKED_BY_USER SESSION_ID LAST_USED_DATE_TIM
CREATION_DATE_TIME
-------- -------------- ------------------ ------------------
mary EDITING PRIME PRIME PRIME
39 02-SEP-94 10:42:42 02-SEP-94 10:01:01 24-AUG-94 20:31:43
2656
If the current_date_time, current_username or session_id columns are not null, then the job is currently in use. If this is
not the case, then use the utility script ImJmForceReady to set these columns to null. For example:
sql> @ImJmForceReady
Enter value for jobname: mary
Note: The ImJmForceReady script always forces the job state to ‘READY’ in addition to clearing the user locks. Thus
this script should only be used if the job state is ‘EDITING’. For other job states it is recommended to use the PDM job
management forms to reset the job states.

U0320 Revision: 1.0.0.0
Locking a Job/Unlocking a Job
9 Locking a Job/Unlocking a Job

ImJmLock is a UNIX script that locks a job to a particular oracle_username. When a job is locked, only the user who
locked the job may connect to the job. The associated SQL*Plus script ImJmLock.sql is also available. An example
usage is:
unix> ImJmLock -u oracle_username -j jobname
[-o output_file (default=ImJmLock.out)]
ImJmJobUnlock is a UNIX script that unlocks a job. When a job is not locked, any user may connect to the job. The
associated SQL*Plus script ImJmUnlock.sql is also available. An example usage is:
unix> ImJmUnlock -u oracle_username -j jobname
[-o output_file (default=ImJmUnLock.out)]
Locking and unlocking can also be performed from the form JOBL within Oracle Forms. See the PDM Forms User
Guide - U0325.
Hint. If you wish to create a new job and immediately lock the job, use the ImJmLock script using a new job name. This
will both create and lock the job. No other user will have a chance to connect to the job in between these two steps.

U0320 Revision: 1.0.0.0
Base Applications Import
10 Base Applications Import

Import reads data from an ASCII file and loads or removes the data into the primitive database. This ASCII file is
referred to as the IDDUG file. The data in the IDDUG file must follow the format described by the Base Applications
Import Data Definition User Guide (U0331).
10.1 Division of BA Data in Multiple IDDUG Files

The recommendation of how to divide up base application data between multiple IDDUG files is as follows.
All Voltage Set data should be stored in its own IDDUG file, and that file should be identified in such a way as to
ensure that it will be imported first -- ahead of all other data. For example, if the first importable file is called
Antipode, the Voltage Set records might be stored in a file called Aavoltage_set (or some other name that collates
ahead of Antipode). As an alternative, the Voltage Set data can be stored at the beginning of the first importable
file. Using the previous example, the Voltage Set records could be placed at the beginning of the file called
Antipode.
Each B1 hierarchy (i.e., each station) should be stored in its own IDDUG file.
All the reference records should be stored in one or more IDDUG files, and those files should be identified in such
a way as to ensure that they will be imported last—following the import of all other data (including Advanced
Application data).
The RTDS/CFE data should be stored in one or more IDDUG files.
Splitting up the data into multiple files is important for the following reasons. The operational database job
management is sized to handle a specific amount of data. One change to the primitive database may result in many
changes to the operational database. Therefore, keeping the amount of data in a job to a reasonable size will mean
that job transfer will not exceed maximums. Also, dividing B1 hierarchies into separate files will keep hierarchy errors
(e.g., record types out of order) from propagating beyond one B1.
Another recommendation is to use the B1 name as the job name.
10.2 Import and Data Removal

Import is run most often to “Import” or add data to the database but it can also be used to remove data from the
database. Import determines the direction in which data is flowing by looking at column 8 of the current IDDUG record.
If this column contains a “D,” the database entry represented by this record and all subordinate database entries will be
deleted. For more information see the Base Applications Import Data Definition User Guide (U0331).
10.3 Import and Job Management

Import is run under the control of job management. A job name must be supplied as a parameter to the import UNIX
script ImBaImport. If a new job name is supplied then a new job is created. If an existing job name is supplied, then two
new tasks within this job are created.
The import process consists of two steps. Each step is a separate task in the job.
Step 1 is the import bulk loading program, ImImpBulk. ImImpBulk reads the records from the IDDUG file. For each
record in the file it determines the key information from the location of the record within the hierarchy. For example, the
B1 name (station name) is used as a key for digital records. The import bulk program then loads the IM control table
import_bulk with the key information and the record image. The record images of continuation record types are
appended to the end of the record image of the major record type. For example, BUSBARA record types are appended
at the end of BUSBAR record image. Note that any rows in the import_bulk table which existed from a previous run
with the same job name are deleted prior to the start of a new run.
When the import bulk load step is done, the import_bulk table contains an image of all the records from the IDDUG file.
If any errors are detected during this step, (e.g., an unknown record type) the import run is halted at this point.
Step 2 is the import merge package, pkg_import_ba. This package reads the rows from the import_bulk table,
determines whether this record is going into the primitive database (insert or update) or is being removed from the
U0320 Revision: 1.0.0.0
primitive database (delete). A record marked for removal is deleted; all other records are handled as updates to an
existing row or inserts of a new row. The order in which the record types are merged is B1, B2, B3, Element, Info, and
RTDS record types. (CFE data is modeled using the RTDS record types.) As the primitive data tables are updated, the
PDM kernel triggers both validation and change detection.
10.4 Import and Validation

Validation of primitive data occurs during import. Error messages are written to the message table if any errors are
detected. The data is entered into the primitive data tables even if errors are detected. The only exception to this is that
if the data causes referential integrity errors, the data is not entered into the primitive database.
It is the user’s responsibility to check the messages and correct the errors.
10.5 Import and Change Detection

Change detection also occurs during import. Images of the new or modified primitive data table rows are written to the
change log. This allows job transfer to determine what needs to be transferred as well as allowing the user to “undo”
the changes made by the import job if so desired.
It is possible to disable change detection during import but this should only be done when initializing an empty primitive
database using reverse transfer.
CAUTION! If change detection is turned off there will be no record of what has changed in the primitive
database that needs to be transferred to the operational database. Also the data in this job will not be able to
be transferred to remote systems via Copy Management job processes.
10.6 Import and Job Interlock

Import employs job interlocking to maintain data integrity in both the primitive and the online databases. Job
interlocking keeps import from touching data already being edited by other jobs and issues an error message if import
tries to make such a change.
Although it is possible to disable interlocking during import, the practice is strongly discouraged.
CAUTION! Overriding job interlocks puts the responsibility for maintaining data integrity on the user. Both the
primitive database tools and job transfer rely on job interlocking as a way of sequencing events and overriding
the interlocks can cause serious data integrity problems.
This override exists to provide a way for the user to get a “quick” change into the primitive data base and across to the
online database without having to cancel outstanding jobs and without having to transfer extraneous pieces of data.
Consider the situation where a station’s data is undergoing an extensive overhaul in the primitive database when the
need arises to make a “quick” change to that station’s data. Without the override, the user would have to make the
“quick” change under the same job name as the overhaul and would force job transfer, which only transfers data by the
job, to prematurely activate overhauled data along with the “quick” change. The only other option would be to cancel
the overhauling job, thereby losing the original set of changes. By using the override and a fair amount of caution, a
skilled user could make the “quick” changes under a new job name and transfer just that job’s changes to the online
system.
If the locking job has no purpose (is the result of an import of reverse transferred data, for example), it is recommended
that the job status be changed to ‘ODB_DELETED’ and the job be deleted from the primitive database to release the
lock.
10.7 B1 Hierarchy and Auto Insert of Elements and Infos

When B1 hierarchy data is imported, some additional elements and infos are automatically inserted.
When a B1 or B2 is inserted, additional elements are inserted based on the block type. The element type for the auto
element is set to -null-. The user must set the element type to the desired value. If an IDDUG file contains an element
with the same name as the auto element, then the element type and the other attributes are updated to match the
contents of the IDDUG record.

U0320 Revision: 1.0.0.0
When a B3 is inserted, additional elements are inserted based on the block type and the topology type. The element
type for the auto elements is set to -null-. The user must set the element type to the desired value. If the IDDUG file
contains an element with the same name as the auto element, then the element type and the other attributes are
updated to match the contents of the IDDUG record.
Note about forms. When using forms some additional elements are automatically inserted that are not inserted during
import. These are the analog elements based on the network element group and their corresponding binary element.
When an element is inserted and the element name indicates that this is a binary element, then the associated binary
element is automatically inserted with the correct element type.
When an element is inserted and it contains an element type, or if the element type is updated from -null- to a value,
some infos will be automatically inserted. Specifically, those digital infos whose default value is non-zero. If the IDDUG
file contains an info with the same names as the auto info, then the attributes of the info are updated to match the
contents of the IDDUG record. Also, if the IDDUG file contains a digital info record containing only values identical to
the default values, this will not be inserted into Oracle. This is known as sparse digital.
10.8 RTDS Hierarchy and Auto Insert of Station RTDS components

When RTDS data is imported, a set of SCADA records is automatically created for it. Included in these SCADA records
are a B1 record for a pseudo station called “RTDS”, several B2 records -- one for each of the RTDS equipment types
(CIA, SAM, RTU and so forth), and one or more B3 records under each B2 record -- each of which represents an
actual piece of equipment. Other records, specifically ELEM and DIGITL records, are created as a part of the auto
insert of elements and infos (see “B1 Hierarchy and Auto Insert of Elements and Infos” on page 65).
A sampling of the automatically created RTDS SCADA records might look something like:
B1 RTDS B1 Syst RTDS 1
ELEM Bl Spec BlocTags B1 RTDS
B2 SAM B2 RTU SAM
ELEM Bl Spec BlocTags B1 RTDS B2 SAM

B3 SAM_R1 B3 RTU SAM_R1
ELEM Bl Spec BlocTags SAM_R1
ELEM SAMStat SAM SAM_R1
DIGITL Al 1 1
ELEM NET SAM SAM_R1
B3 SAM_R2 B3 RTU SAM_R2
ELEM Bl Spec BlocTags SAM_R2
ELEM SAMStat SAM SAM_R2
DIGITL Al 1 1
ELEM NET SAM SAM_R2
B2 CIA B2 RTU CIA
ELEM Bl Spec BlocTags B1 RTDS B2 CIA
B3 CIA01R1 B3 RTU CIA01R1
ELEM Bl Spec BlocTags CIA01R1
ELEM CIAStat CIA CIA01R1
Modifications to the RTDS equipment cannot be added or deleted via the RTDS pseudo station. This station is created
so that characteristics such as the technological area for signalling, one-line display names and local and global
decision tables may be modified to suit the project.

U0320 Revision: 1.0.0.0
10.9 Execute Import and Check Results

1. Execute import using the UNIX script ImBaImport. Refer to the man page for more information on the script
options.
unix> ImBaImport -u oracle_username -j jobname
-i iddug_filename
[-o Output path/file
Default=ImBaImport.out]
[-e Maximum number of errors issued before stop.
Default=100]
[-c Change detection flag (Y/N) Default=Y]
[-l Job Interlock flag (Y/N) Default=Y]

[-t Import trace level. Default=0]
A specific example to import station crystal using the station name as the job name is:
unix> ImBaImport -u oracle_username -j crystal -i crystal.iddug -e
99
Import can also be run from the PDM (Main) form within Oracle forms. See the PDM Forms User Guide -
U0325.
To run ImBaImport for some or all IDDUG files within a directory, use the tool ImBaImportDirectory (See
“ImBaImportDirectory” on page 163.)
2. Log into SQL*Plus and check the job trace. This can be done while ImBaImport is still executing and/or after it
has finished.
unix> sqlplus oracle_username/password

sql> @gtrace crystal
MESSAGE TIME
-------------------------------------------------------- --------
ImImpBulk routine started... 12:27:41
ImImpBulk final insert complete. 12:27:45
ImImpBulk complete. 0 errors. 686 rows inserted. 12:27:45
Start of Import run. Job name=crystal Job id=9 12:27:46
Processing STATN record types. 12:27:46
0 errors were issued for 1 STATN records. 12:27:47
.
.
Lines deleted here
.
.
End of Import run. Normal Termination. 8 errors were 12:28:13
issued for 686 total records.
Job Trace information may also be seen on the JOBT form within Oracle Forms. See the PDM Forms User
Guide - U0325.
Job trace could also be checked using the ImRptJobTrace report. For example:
sql> @ImRptJobTrace
Enter value for report_output: crystal.trace
Enter value for job_name: crystal
Enter value for task_id: %
U0320 Revision: 1.0.0.0
The Job Trace report may also be run from the REP form within Oracle Forms. See the PDM Forms User
Guide - U0325.
3. If any errors were issued, generate a report of the errors messages.
sql> @ImRptMsg
Enter value for report_output: crystal.msg
Enter value for job_name: crystal
An example import error message is:
Msg Site/
ID Date Time Message Source S Code Kid
-- --------- ---------------- -------- - ---- ---

3 19-JAN-94 “Operand Identifier” must be between CALC_OPERAND we
610
02:18:24 A and Z PKG_DOMAIN.VERIFY 107
import: line=556 file=/home/p/data/crystal
CALCOP a TA Crystal 33 E/MA Q MvMoment}
Note: the import line number printed with the error message corresponds to the linenumber in the IDDUG file of
the record in error. If the error occurred on a continuation record, the line number points to the major record, not
the continuation record.
Also note that the import stops when the max number of errors specified on the -e option is reached. If you
have an iddug with a large number of errors, you may have to specify a larger number on the -e option in order
to see them all. The default value is 100.
The Error Message report may also be run from the REP form within Oracle Forms. See the PDM Forms User
Guide - U0325.
4. Correct the errors in the IDDUG data file.
unix> vi crystal.iddug
5. If any errors were detected and corrected in the IDDUG data file, cancel the previous import job to remove any
changes made to primitive data. This will also clear out the error message, trace messages and import bulk
table rows for this job.
unix> ImJmCancel -u oracle_username -j crystal [-o output_file
(default=ImJmCancel.out)]
This script can also be run from the PDM (Main) form within Oracle forms. See the PDM Forms User Guide -
U0325.
Note, at this point the primitive database should be in the state it was prior to the previous import.
6. Rerun import. I.e., start again at step 1.

U0320 Revision: 1.0.0.0
10.10 Executing Import With Detailed Trace

It is possible to get more detailed trace by setting the job trace level value to a higher number using the- t switch of
ImBaImport. An example of executing import and the detailed trace messages which are produced follow. The name of
the procedure which issued the trace message is written before the colon.
unix> ImBaImport -u oracle_username -j jobname -i iddug_filename -t
99
sql> @gtrace jobname
MESSAGE TIME
-------------------------------------------- --------
ImImpBulk. Jobname=mary Jobid=54 07:42:53
ImImpBulk final insert complete. 07:42:55

ImImpBulk complete. 0 errors. 24 rows inserted. 07:42:55
Start of Import run. Job name=mary Job id=54 07:42:57
pkgimp_statn.merge: linenum=1 image=STATN Crystal Statio 07:43:01
n Crystal 1 Star1WG }
trbu_b1: begin 07:43:04
trbu_b1: end 07:43:04
trau_b1: begin 07:43:04
trau_b1: end 07:43:04
trbi_b1: begin 07:43:05
trbi_b1: end 07:43:05
trbir_b1: begin 07:43:05
PKG_B1.GET_B1_NUM: begin 07:43:06
PKG_JOBU.GET_INT_NUM: begin 07:43:06

PKG_JOBU.GET_INT_NUM: end 07:43:06
PKG_B1.GET_B1_NUM: end. num=2 07:43:06
pkgvl_b1.validate: begin 07:43:06
pkg_domain.verify: begin 07:43:06
pkg_domain.verify: end 07:43:06
PKG_B1.VAL_FIELD_BLOCK_TYPE: begin 07:43:06
PKG_B1.VAL_FIELD_BLOCK_TYPE: end 07:43:06
pkgvl_b1.validate: end 07:43:06
trbir_b1: end 07:43:06
trair_b1: begin 07:43:07
pkgcd_b1.change_detect: begin 07:43:07
pkgcd_b1.change_detect: just before insert into change log.
07:43:07
pkgcd_b1.change_detect: end 07:43:07
pkg_jobi.insert_ilock: begin 07:43:08
pkg_jobi.outside_job_ilock: begin 07:43:08
pkg_jobi.outside_job_ilock: end 07:43:08
pkg_jobi.current_job_ilock: begin 07:43:08
pkg_jobi.current_job_ilock: end 07:43:08
pkg_jobi.insert_ilock: end 07:43:08
pkg_mutating.hold_b1: begin 07:43:08
pkg_mutating.hold_b1: end 07:43:08
trair_b1: end 07:43:08
trai_b1: begin 07:43:08
pkg_mutating.put_b1: begin 07:43:08
pkg_mutating.put_b1: end 07:43:18
trai_b1: end 07:43:18

U0320 Revision: 1.0.0.0
.
lines deleted here
.
0 errors were issued for 22 DIGITL records. 07:43:45
pkg_import_ba.main: Deleting rows from import_bulk for 07:43:45
job mary.
End of Import. Normal Termination. 0 errors were issued 07:43:45
for 676 total records.
10.11 Deleting IMPORT_BULK Rows

ImJmClearImportBulk is a UNIX script that deletes the rows in the import_bulk table associated with a job. The
associated SQL*Plus script ImJmClearImportBulk.sql is also available. An example usage is:
unix> ImJmClearImportBulk -u oracle_username -j jobname [-o output_file

(default=ImJmClearImportBulk.out)]
Note that in a normal import run the import_bulk rows are deleted automatically if no errors are issued. Also, deleting or
cancelling a job also deletes the import_bulk rows. This script is a utility script which may be used when needed.

U0320 Revision: 1.0.0.0
Communications Import
11 Communications Import
Import of communications data is much like Base Applications Import. The main difference is the command executed
to perform the import. Be sure to run import for the B1 hierarchy before running any communication imports.
11.1 ICCP Import

Place all ICCP data in one IDDUG import file
Execute import using the UNIX Script ImIccpImport. Refer to the man page for more information on the script options.
unix> ImIccpImport -u oracle_username -j jobname
-i iddug_filename

Default=ImIccpImport.out]
Default=100]
A specific example to import ICCP data using iccp as the job name is:
unix> ImIccpImport -u oracle_username -j iccp -i iccp.iddug -e 99
Import can also be run from the PDM (Main) form within Oracle forms. See the PDM Forms User Guide - U0325.
Follow the directions for Base Applications Import to check results.
Check for inconsistencies within the data by running the ImGvICCP script.
unix> ImGvICCP -u oracle_username -j iccp [-v Row Level Validation
Flag (Y/N) Defaults to N [-o output_file (default=ImGvICCP.out)]
Global validation can also be run from the GLOV form within Oracle Forms. See the PDM Forms User Guide - U0325.

U0320 Revision: 1.0.0.0
Load Shed Import
12 Load Shed Import

Import of Load Shed data is much like Base Applications Import. The main difference is the command executed to
perform the import. Be sure to run import for the B1 hierarchy before running Load Shed import.
12.1 Load Shed Import

Place all Load Shed data in one IDDUG import file.
Execute import using the UNIX script ImLsImport. Refer to the man page for more information on the script options.
unix> ImLsImport -u oracle_username -j jobname
-i iddug_filename

Default=ImLsImport.out]
Default=100]
A specific example to import Load Shed data using LdShed as the job name is:
unix> ImLsImport -u oracle_username -j LdShed -i LsShed.iddug -e 99
Check for inconsistencies within the data by running the ImGvLs script.
unix> ImGvLs -u oracle_username -j LdShed [-v Row Level Validation Flag
(Y/N) Defaults to N [-o output_file (default=ImGvLs.out)]
Global validation can also be run from the GLOV form within Oracle forms. See the PDM Forms User Guide - U0325.

U0320 Revision: 1.0.0.0
Underfrequency Load Shed Import
13 Underfrequency Load Shed Import

Import of Underfrequency Load Shed data is much like Base Applications Import. The main difference is the command
executed to perform the import. Be sure to run import for the B1 hierarchy before running Underfrequency Load Shed
import.
13.1 Underfrequency Load Shed Import

Place all Underfrequency Load Shed data in one IDDUG import file.
Execute import using the UNIX script ImUlsImport. Refer to the man page for more information on the script options.
unix> ImUlsImport -u oracle_username -j jobname
-i iddug_filename

Default=ImUlsImport.out]
Default=100]
A specific example to import Underfrequency Load Shed data using UlsShed as the job name is:
unix> ImUlsImport -u oracle_username -j UlsShed -i UlsShed.iddug -e
99

Check for inconsistencies within the data by running the ImGvUls script.
unix> ImGvUls -u oracle_username -j UlsShed
[-v Row Level Validation Flag (Y/N) Defaults to N
[-o output_file (default=ImGvUls.out)]

U0320 Revision: 1.0.0.0
Voltage Reduction Import
14 Voltage Reduction Import

Import of Voltage Reduction data is much like Base Applications Import. The main difference is the command executed
to perform the import. Be sure to run import for the B1 hierarchy before running Voltage Reduction import.
14.1 Voltage Reduction Import

Place all Voltage Reduction data in one IDDUG import file.
Execute import using the UNIX script ImVrImport. Refer to the man page for more information on the script options.
unix> ImVrImport -u oracle_username -j jobname
-i iddug_filename

Default=ImVrImport.out]
Default=100]
A specific example to import Voltage Reduction data using VoltRed as the job name is:
unix> ImVrImport -u oracle_username -j VoltRed -i VrShed.iddug -e
99
Check for inconsistencies within the data by running the ImGvVr script.
unix> ImGvVr -u oracle_username -j VoltRed
[-v Row Level Validation Flag (Y/N) Defaults to N
[-o output_file (default=ImGvVr.out)]

U0320 Revision: 1.0.0.0
Energy Accounting Import
15 Energy Accounting Import

Import of Energy Accounting data is much like Base Applications Import. The main difference is the command
executed to perform the import. Be sure to run import for the B1 hierarchy before running Energy Accounting import.
15.1 Energy Accounting Import

Place all Energy Accounting data in one IDDUG import file.
Execute import using the UNIX scrip ImEaImport. Refer to the man page for more information on the script options.
unix> ImEaImport -u oracle_username -j jobname –I iddug_filename
[-o] Output path/file
Default=ImEaImport.out
[-e] Maximum number of errors issued before stop.
Default=100
[-c] Change detection flag (Y/N) Default=Y
[-l] Job Interlock flag (Y/N) Default=Y
[-t] Import trace level. Default=0
A specific example to import Energy Accounting data using EnergyA as a the job name is:
unix> ImEaImport -u oracle_username -j EnergyA -i EnergyA.iddug -e
99
Import can also be run the PDM (Main) for within Oracle forms. See the PDM Forms User Guide - U0325.
Check for inconsistencies within the data by running the ImGvEa script.
unix> ImGvEa -u oracle_username -j EnergyA

[-v] Row Level Validation Flag (Y/N) Defaults to N
[-0] output_file

U0320 Revision: 1.0.0.0
Advanced Applications Import, Validation and Export
16 Advanced Applications Import, Validation and Export

AA Import provides the ability to load data from ASCII files into the AA primitive database tables. The format of the data
in the ASCII files is described in the Advanced Applications Import Data Definition User Guide (IDDUG) - U0332.
Note that it is not necessary to go through all of the following steps every time. The AA Import Pre-processor step is
required only if some data in file DBNETD is changed. The AA Import step is necessary only when some data in file
DBNETD is changed and/or Oracle needs to be re-loaded.
16.1 AA Import Pre-processor

Run the AA import program using script ImAaImport. AA Import uses the AdbChkr output data files to insert or update
the AA primitive database tables. If you run ImAaImport for subsystem ALL it will first check to make sure there are no
other jobs with AA changes that exist in the primitive database. All AA jobs must be either cancelled or deleted before
you are able to truncate the AA tables.

You may also select a particular subsystem via the Subsystem [-s] parameter on the ImAaImport script. For all
subsystems other than PWA no table truncations are performed in the Primitive Database. If the PWA system is
selected the PWA tables in the Primitive Database are first truncated before the Import of the PWA tables is executed.
In addition you may select to only import a particular record type. If the [-r] parameter is used only those IDDUG
records which match the record name entered in the [-r] parameter are imported into the Primitive Database.
In each scenario it is important to note that for the import of U0332 data change detection in the Primitive Database is
disabled.
Note: The system no longer supports ADB based network apps. The presence of the string ‘ADB’ in Advanced
Applications path names or script names does not imply that ADB based network apps are supported.
The following files must be prepared by the user and placed in the $SPECPATH/par/adb directory prior to running the
pre-processor:
DBNETD - U0332 IDDUG data

reference_common- AA/Scada common references
reference_aa_only- External model AA only reference
data
TOTYDE - Topology Type definitions
The DBNETD file is the IDDUG datafile which can be generated by the user or from Oracle using AA Export. The
generated IDDUG file should be placed in the $SPECPATH/par/adb directory prior to running the pre-processor.
The reference_common file can be generated by the user or from Oracle using ImBaExport. The generated reference
file should be placed in the $SPECPATH/par/adb directory prior to running the pre-processor.
The reference_aa_only file can be generated by the user or from Oracle using ImBaExport. The generated reference
file should be placed in the $SPECPATH/par/adb directory prior to running the pre-processor.
The TOTYDE file contains the topology type definitions. The current definitions should be generated from Spectrum
using the AdbTOTYDE script. This script will create a new TOTYDE file in the $SPECPATH/par/adb directory.
unix> $SPECPATH/sys/adb/AdbTOTYDE [BQ | local | nimtypes]
Outputs are saved to the $SPECPATH/par/adb directory.
Option “BQ” produces a BQ dump with option “genjob on” of Spectrum relations TOTYNAME, ELNAME, and TOTYDE
to files totyname.j, elname.j, and totyde.j respectively. If no option is specified the default is “BQ”.
Option “Local” produces the files totyname.j, elname.j, and totyde.j in the local directory $SPECPATH/par/adb. The
files have the same format as those produced by a BQ dump with option “genjob on”.
Option “Nimtypes” produces the files totyname.j, elname.j, and totyde.j in the directory $SPECPATH/par/fillrel/nimtypes
named totyname.j_ENGLISH, elname.j, and totyde.j respectively.

U0320 Revision: 1.0.0.0
Once all the files are in the $SPECPATH/par/adb directory, to run the pre-processor:
unix> cd $ADBHOME
unix> AdbChkr
The validation errors and summary information produced by the pre-processor is in the file $ADBHOME/AdbChkr.out.
The pre-processor also creates the import datafiles: impPWA.dat, impNWA.dat, impSCA.dat, impOTS.dat, impAI.dat,
impDSA.dat in the $ADBHOME directory. These files are used by AA import.
16.2 AA Import
Run the AA import program using the script ImAaImport. AA Import uses the AdbChkr output data files to insert or
update the AA primitive database tables. If you run ImAaImport for subsystem ALL it will first check to make sure there
are no other jobs with AA changes that exist in the primitive database. All AA jobs must be either cancelled or deleted
before you are able to truncate the AA tables.

unix> ImAaImport -u oracle_username
[-s] Subsystem to import (PWA,NWA,SCA,OTS,AI,DSA)
Note: enclose multiple subsytems within double quotes.
(i.e.,”PWA NWA”)
Default=ALL
Note: Subsystem ALL will truncate AA tables before importing.
[-r] U0332 Record to import

Note: enclose multiple record types within double quotes.
(i.e.,”ZONE_0 STATN_0”)
Default=ALL
Output path/files are $ADBHOME/ImAaImport.out.

and $ADBHOME/AA_import_error.out.
Job Name is AAIMPORT

Change Detection is OFF
Job Interlocks are OFF
You will be prompted for the Oracle password when you run the script.
The output file $ADBHOME/ImAaImport.out stores the parameters used for the last ImAaImport run. It will also give
you a start and end date and time for the last ImAaImport run.
The output file $ADBHOME/AA_import_error.out is a report of all errors encountered during the last ImAaImport run.
16.3 AA Export
AA Export reads from the AA primitive database tables and writes an ASCII file back in IDDUG format. All six AA
scopes (PWA, NWA, SCA, OTS, AI, DSA) are exported. The output is written to the $ADBHOME directory.
unix> cd $ADBHOME
unix> ImAaExport -u oracle_username
Output path/files are $ADBHOME/ImAaExport.out and
$ADBHOME/DBNETD.export
You will be prompted for the Oracle password when you run the script.

U0320 Revision: 1.0.0.0
The output file $ADBHOME/ImAaExport.out will tell you the start and end date and time of the last ImAaExport run.
The ASCII file created by export is $ADBHOME/DBNETD.export. Base Applications Export (ImBaExport) is used to
export the reference data.

U0320 Revision: 1.0.0.0
Base Applications Export
17 Base Applications Export

Export extracts data from the primitive database and writes this data into ASCII files in IDDUG format. Export of Base
Application data is done as six separate hierarchies B1, Reference, Voltage Set, RTU, SAM, or CMCH.
17.1 Export UNIX Script—ImBaExport

1. The UNIX script ImBaExport is used to execute export. Refer to the man page for more information on the script
options.
unix> ImBaExport -u oracle_username -j jobname
-h Hierarchy name (b1/reference/voltage/rtu/sam/cmch)
e.g. -hrtu to export a rtu hierarchy
[-k Key value to be exported

e.g. -kRTU_1 for rtu named RTU_1 -kMinnetonka for B1 named
Minnetonka -kall for all names
Note, not used for reference hierarchy or the voltage hierarchy.
Multiple key names must be enclosed inside double quotes and must
be separated by commas! (i.e., “key1, key2”)]

(default=ImBaExport.out)]
[-a Directory to receive exported IDDUG files
Default=pwd/export###### where ######=UNIX pid]
Export can also be run from the PDM (Main) form within Oracle forms. See the PDM Forms User Guide - U0325.
The generated export files are written to the directory specified by the -a option. The naming convention used for
the export files is xxx.exp, where xxx is the name of the data which is exported. For example, file Minnetonka.exp
receives the data for the station Minnetonka.
Note, it is recommended that a new job name be chosen for export instead of using an existing job.
2. Check the ImBaExport script output file to verify that the export was successful. Also log into SQL*Plus and check
the job trace. This can be done while ImBaExport is still executing and/or after it has finished.
MESSAGE TIME
---------------------------------------------------- --------
Start of B1 export for “Vienna”. 12:27:41
Processing LN_BLK record types. 12:27:41
..
Lines deleted here
..
End of Export run. Normal Termination. 12:28:13
Job Trace information may also be seen on the JOBT form within Oracle Forms. See the PDM Forms User Guide -
U0325.
3. Cancel the export job.
unix> ImJmCancel -u oracle_username -j jobname
[-o output_file (default=ImJmCancel.out)]

U0320 Revision: 1.0.0.0
This script can also be run from the PDM (Main) form within Oracle forms. See the PDM Forms User Guide -
U0325
Note: ImJmCancel is used rather than ImJmDelete so that the job maybe removed without having to first change the
status to ODB_DELETED. Use ImJmCancel only if this job was used for export purposes only. If this job was used for
other purposes, then use ImJmDelete instead.
17.2 B1 Export
A specific example to export B1 crystal using the B1 name as the job name follows. The generated export filename is
./export/crystal.exp.
unix> ImBaExport -u oracle_username -j crystal -h b1 -k crystal -a
export
To export all B1 data use the following. One file for each B1 is created in directory ./export_b1.
unix> ImBaExport -u oracle_username -j exp_b1 -h b1 -k all -a
export_b1
Remember to check the output file ImBaExport.out and the job trace to verify that the export ran successfully. Also
remember to cancel the job when finished.
17.3 Reference Export

A specific example to export reference data follows. The generated export filename is ./export/reference.exp.
unix> ImBaExport -u oracle_username -j exp_ref -h reference -a
export
Exported data will be written to three files - one file for Advanced Applications references (called reference_aa.exp),
one file for Base Applications-only references or for those references that appear in both Advanced Applications and
Base Applications (called reference_ab), and one file for all other references (called reference_ba.exp).
17.4 RTU Export

A specific example to export RTU rtu_1 using the RTU name as the job name follows. The generated export filename
is ./export/rtu_1.exp.
Note, the RTU Protocol Type and RTU Group data is exported along with the RTU hierarchy even though the RTU
name is not a key to this data. If multiple RTUs are exported, then this data is contained in each of the generated files.
unix> ImBaExport -u oracle_username -j rtu_1 -h rtu -k rtu_1 -a
export
To export all RTU data use the following. One file for each RTU is created in directory ./export_rtu.
unix> ImBaExport -u oracle_username -j exp_rtu -h rtu -k all -a
export_rtu
This applies to both RTDS and CFE RTUs as they use the same IDDUG record types.

U0320 Revision: 1.0.0.0
17.5 Characteristic Curve (CMCH) Export

A specific example to export characteristic curve data follows. The generated export filename is ./export/cmch.exp.
unix> ImBaExport -u oracle_username -j exp_cmch -h cmch –a export
17.6 SAM Export

A specific example to export SAM sam_1 using the SAM name as the job name follows. The generated export
filename is ./export/sam_1.exp.
unix> ImBaExport -u oracle_username -j sam_1 -h sam -k sam_1 -a

export
To export all SAM data use the following. One file for each SAM is created in directory ./export_sam.
unix> ImBaExport -u oracle_username -j exp_sam -h sam -k all -a
export_sam
This applies to both RTDS and CFE data as CFE Servers are Modeled in PDM using the SAM data hierarchy.
17.7 Voltage Level Export

A specific example to export voltage level data follows. The generated export filename is ./export/ voltage.exp
unix> ImBaExport -u oracle_username -j exp_vol -h voltage -a export


U0320 Revision: 1.0.0.0
Communications Export
18 Communications Export
Export of communications data is much like Base Applications Export. The main difference is the command executed
to perform the Export.
18.1 Export UNIX Script—ImCommExport

The UNIX script ImCommExport is used to execute export. Refer to the man page for more information on the script
options.
unix> ImCommExport -u oracle_username -j jobname -h Hierarchy name
(elcom/iccp/wscc)
e.g. -h elcom to export an elcom hierarchy

(default=ImCommExport.out)]
Follow the directions for Base Applications Export to check results and cancel the export job.

U0320 Revision: 1.0.0.0
Load Shed Export
19 Load Shed Export

Export of Load Shed data is much like Base Applications Export. The main difference is the command executed to
perform the Export.
19.1 Export UNIX Script—ImLsExport

The UNIX script ImLsExport is used to execute export. Refer to the man page for more information on the script
options.
unix> ImLsExport -u oracle_username -j jobname

(default=ImLsExport.out)]

U0320 Revision: 1.0.0.0
Underfrequency Load Shed Export
20 Underfrequency Load Shed Export

Export of Underfrequency Load Shed data is much like Base Applications Export. The main difference is the command
executed to perform the Export.
20.1 Export UNIX Script—ImUlsExport

The UNIX script ImUlsExport is used to execute export. Refer to the man page for more information on the script
options.
unix> ImUlsExport -u oracle_username -j jobname
(default=ImUlsExport.out)]


U0320 Revision: 1.0.0.0
Voltage Reduction Export
21 Voltage Reduction Export

Export of Voltage Reduction data is much like Base Applications Export. The main difference is the command executed
to perform the Export.
21.1 Export UNIX Script—ImVrExport

The UNIX script ImVrExport is used to execute export. Refer to the man page for more information on the script
options.
unix> ImVrExport -u oracle_username -j jobname
(default=ImVrExport.out)]


U0320 Revision: 1.0.0.0
Energy Accounting Export
22 Energy Accounting Export

Export of Energy Accounting data is much like Base Applications Export. The main difference is the command
executed to perform the Export.
22.1 Export UNIX Script—ImEaExport

The UNIX script ImEaExport is used to execute export. Refer to the man page for more information on the script
options.
unix> ImEaExport -u oracle_username -j jobname
(default=ImVrExport.out)]


U0320 Revision: 1.0.0.0
Primitive Database Forms
23 Primitive Database Forms

Forms provide the ability to view and/or edit the contents of the primitive database through a GUI interface. See the
PDM Forms User Guide - U0325 - for a description of how to use the forms.
23.1 Executing Forms

The UNIX script ImForm is used to initiate forms. An example usage is:
unix> ImForm -u oracle_username
ImForm: Enter prime’s Oracle Password: <password>
ImForm: Access to Oracle User prime

ImForm: has been verified with sqlplus.
ORACLE_HOME=/usr/oracle
ORACLE_SID =emp1
ORACLE_PATH=/usr/emlib/public/im/bin:/home/s/lib/form
MENU_PN =/home/s/lib/form
Starting rdbms_interface main form and a PDM Interface window
should appear on your screen
If a window does not appear on your screen, verify that the UNIX environment variable DISPLAY contains the name of
your screen. If you received the following error message from ImForm, then use the xhost command to allow windows
from another server to be displayed on your screen.
Xlib: connection to “cronus:0.0” refused by server

Xlib: Client is not authorized to connect to Server
FRM-91111: Internal Error -- Window system startup failure.
If a window still does not appear, verify that files rdbms_interface.fmx and rdbms_interface_menu.mmx exist in the
directory pointed to by the UNIX environment variable MENU_PN.
23.2 Forms and Job Management

All editing of primitive data must be done under the control of a job. First connect to a job before using any of the forms
to make changes to primitive data. If you are not connected then insert, update, and delete privileges are disabled on
the forms.
To connect to a job enter the job name in the Job Name field on the RDBMS Interface window.

U0320 Revision: 1.0.0.0
Global Validation
24 Global Validation
Global validation verifies the contents of the primitive database. Global validation includes database-level validation
and may optionally include entry-level validation. If any errors are detected by global validation, error messages are
written to the MSG table.
Entry-level validation checks are the validation checks that are done when data is entered into the primitive database
tables. These are the same checks that are done during import or during the use of Forms. By default the entry-level
checks are not performed. To perform these checks include the -v Y option on the UNIX script.
Database-level validation checks are additional validity checks that ensure that the primitive database as a whole is
complete and consistent.
An example of a completeness check is the check that verifies that the number of absolute limits that are actually
defined for an element is the correct number for this element name and element type combination. If too many or too
few absolute limits are defined, an error message is issued.
An example of a consistency check is the check on the reference table that verifies that the B1/ B2/B3/Element names
entered do actually exist in either the SCADA tables or the Network Application tables.
Global validation should be executed after changing data in the primitive database and prior to job transfer. It is the
user’s responsibility to fix any errors identified by global validation.
24.1 Global Validation for a Job - ImGvJob

Global validation for a job re-executes the entry level validation on all data previously changed by the job and re issues
error messages to the MSG table. Global validation for a job may be done for the entire job or for a specific task within
the job. It is important to note that ImGvJob does not run any database-level checks. If database-level checking is
required, the user must run the individual global validation routines (i.e, ImGvB1).
Job global validation is only allowed if there are entries in the change log associated with the job. This is necessary
because the entries in the change log are used to determine which tables and rows were affected by the job and need
to be re-validated.
Job global validation executes as a separate task in the job with a task name of ‘job_validation’. All of the error
messages issued by job global validation are associated with this task.
The reason why a user might use job global validation is to generate an up-to-date listing of error messages associated
with the job after correcting existing error messages.
ImGvJob is the UNIX script that executes global validation for a job. An example usage is:
unix> ImGvJob -u oracle_username -j jobname -t % -d Y [-o
output_file (default=ImGvJob.out)]
24.2 Global Validation for B1 - ImGvB1

Global validation for B1 validates all data in the specified B1 hierarchy and writes error messages to the MSG table. It
performs the database-level validation checks and the entry-level checks if requested. B1 global validation may be
executed for a specific B1 or for all B1s currently defined in the primitive database.
B1 global validation executes as a separate task(s) in the job with a task name of ‘b1_global_val xxx’, where xxx is the
B1 name. One task is created for each B1 validated. All of the error messages issued by B1 global validation are
associated with this task(s).
ImGvB1 is the UNIX script that executes B1 global validation. An example usage for the B1 name of Vienna is:
unix> ImGvB1 -u oracle_username -j jobname -b Vienna -v N [-o
output_file (default=ImGvB1.out)]

U0320 Revision: 1.0.0.0
Global Validation
Note, if a % is entered for the value for the -b parameter then all B1s are validated.
24.3 Global Validation for B1 Miscellaneous – ImGvBaMisc

ImGvBaMisc performs global validation checks on BA data that do not pertain to a specific B1. For example, verify that
the correct number of voltage limit values are defined. A task name of ‘ba_misc_global_val’ is used. An example usage
is:
unix> ImGvBaMisc -u oracle_username -j jobname-v N [-o output_file
(default=ImGvBaMisc.out)]
24.4 Global Validation for Duplicate Names – ImGvSpecDupName

ImGvSpecDupName is a PDM Interface UNIX script that performs global validation to check for B1, B2, B3, and
Element names in Oracle database that will be interpreted as duplicates within the on-line opertational database. This
check is necessary because of the difference in the way Oracle and the on-line operational database handle upper and
lower case, blanks, and underscores. In Oracle the differences between these pairs is significant and Oracle will
interpret them to be unique.
“STAR1” and “star1”
“Mary 2” and “Mary2”
“Tbear_1” and “Tbear1”
In the on-line operational database, however, these pairs are interpreted to be identical.
This script will check the Oracle names and will issue messages if the names will form duplicates due to upper/lower
case, underscores, or blanks.
An example usage is:
unix> ImGvSpecDupName -u oracle_username -j jobname [-o output_file

(default=ImGvSpecDupName.out)]
24.5 Global Validation for References – ImGvReference

Global validation for references validates reference data and writes error messages to the MSG table. It performs the
database-level validation checks and the entry-level checks if requested for all records whose from-side B1 Name or
whose to-side B1 Name matches the B1 Name specified on the script’s -b switch. The B1/B2/B3/Element names listed
in the reference table must exist in either the BA tables or the AA tables or both. If the names are not found in at least
one of the two locations then an error message is generated.
Reference global validation executes as a separate task in the job with a task name of ‘ref_global_val’. All of the error
messages issued by reference global validation are associated with this task.
ImGvReference is the UNIX script that executes reference global validation. An example usage is:
unix> ImGvReference -u oracle_username -j jobname -b Vienna -v N [-
o output_file (default=ImGvReference.out)]
24.6 Global Validation for RTU (RTDS and CFE) ImGvRtu

Global validation for RTU validates all data in the specified RTU hierarchy and writes error messages to the MSG
table. It performs the database-level validation checks and the entry-level checks if requested. RTU global validation
may be executed for a specific RTU or for all RTUs currently defined in the primitive database.
RTU global validation executes as a separate task(s) in the job with a task name of ‘rtu_global_val xxx’, where xxx is
the RTU name. One task is created for each RTU validated. All of the error messages issued by RTU global validation
are associated with this task(s).
ImGvRtu is the UNIX script that executes RTU global validation. An example usage for the RTU name of rtu_1 is:
U0320 Revision: 1.0.0.0
Global Validation
unix> ImGvRtu -u oracle_username -j jobname -r rtu_1 -v N [-o

output_file (default=ImGvRtu.out)]
Note, if a % is entered for the value for the -r parameter then all RTUs are validated.
24.7 Global Validation for SAM (RTDS and CFE) ImGvSam

Global validation for SAM validates all data in the specified SAM hierarchy and writes error messages to the MSG
table. It performs the database-level validation checks and the entry-level checks if requested. SAM global validation
may be executed for a specific SAM or for all SAMs currently defined in the primitive database.
SAM global validation executes as a separate task(s) in the job with a task name of ‘sam_global_val xxx’, where xxx is
the SAM name. One task is created for each SAM validated. All of the error messages issued by SAM global validation
are associated with this task(s).

ImGvSam is the UNIX script that executes SAM global validation. An example usage for the SAM name of sam_1 is:
unix> ImGvSam -u oracle_username -j jobname -s sam_1 -v N [-o
output_file (default=ImGvSam.out)]
Note, if a % is entered for the value for the -r parameter then all SAMs are validated.
24.8 Global Validation for RTDS Miscellaneous – ImGvRtdsMisc

ImGvRtdsMisc performs global validation checks on RTDS/CFE data that do not pertain to a specific RTU or SAM. For
example, validate the contents of the rtu_group and rtu_protocol_type tables. A task name of ‘rtds_misc_global_val’ is
used. An example usage is:
unix> ImGvRtdsMisc -u oracle_username -j jobname [-o output_file

(default=ImGvRtdsMisc.out)]
24.9 Global Validation for ICCP – ImGvICCP

Global validation for ICCP validates all ICCP data and writes error messages to the MSG table. It performs the
database-level validation checks and the entry-level checks if requested.
ICCP global validation executes as a separate task in the job with a task name of ‘iccp_global_val’. All of the error
messages issued by ICCP global validation are associated with this task.
ImGvICCP is the UNIX script that executes ICCP global validation. An example usage is:
unix> ImGvICCP -u oracle_username -j iccp -v N [-o output_file
(default=ImGvICCP.out)]
24.10 Global Validation for Load Shed – ImGvLs

Global validation for Load Shed validates all Load Shed data and writes error messages to the MSG table. It performs
the database-level validation checks and the entry-level checks if requested.
Load Shed global validation executes as a separate task in the job with a task name of ‘ls_global_val’. All of the error
messages issued by Load Shed global validation are associated with this task.
ImGvLs is the UNIX script that executes Load Shed global validation. An example usage is:
unix> ImGvLs -u oracle_username -j LdShed -v N [-o output_file
(default=ImGvLs.out)]

U0320 Revision: 1.0.0.0
Global Validation
24.11 Global Validation for Underfrequency Load Shed – ImGvUls

Global validation for Underfrequency Load Shed validates all Underfrequency Load Shed data and writes error
messages to the MSG table. It performs the database-level validation checks and the entry-level checks if requested.
Underfrequency Load Shed global validation executes as a separate task in the job with a task name of
‘uls_global_val’. All of the error messages issued by Underfrequency Load Shed global validation are associated with
this task.
ImGvUls is the UNIX script that executes Underfrequency Load Shed global validation. An example usage is:
unix> ImGvUls -u oracle_username -j UldShed -v N [-o output_file
(default=ImGvUls.out)]
24.12 Global Validation for Voltage Reduction – ImGvVr

Global validation for Voltage Reduction validates all Voltage Reduction data and writes error messages to the MSG
table. It performs the database-level validation checks and the entry-level checks if requested.
Voltage Reduction global validation executes as a separate task in the job with a task name of ‘vr_global_val’. All of the
error messages issued by Voltage Reduction global validation are associated with this task.
ImGvVr is the UNIX script that executes Voltage Reduction global validation. An example usage is:
unix> ImGvVr -u oracle_username -j VoltRed -v N [-o output_file
(default=ImGvVr.out)]
24.13 Global Validation for Energy Accounting – ImGvEa

Global validation for Energy Accounting validates all Energy Accounting data and writes error messages to the MSG
table. It performs the database-level validation checks and the entry-level checks if requested.
Energy Accounting global validation executes as a separate task in the job with a task name of ‘ea_global_val’. All of
the error messages issued by Energy Accounting global validation are associated with this task.
ImGvEa is the UNIX script that executes Energy Accounting global validation. An example usage is:
unix> ImGvEa -u oracle_username -j EnerAcc -v N [-o output_file
(default=ImGvVr.out)]
24.14 Global Validation for all Base Application Data – ImGvBaAll

The procedure ImGvBaAll validates all base application data and writes error messages to the MSG table. It performs
the database-level validation checks and the entry-level checks if requested. ImGvBaAll is, in fact, a script that
sequentially runs the following secondary scripts:
ImGvB1
ImGvReference
ImGvBaMisc
ImGvSpecDupName
ImGvSam
ImGvRtu
ImGvRtdsMisc

U0320 Revision: 1.0.0.0
Global Validation
ImGvICCP
ImGvLs
ImGvUls
ImGvVr
ImGvEa
Each secondary script run within ImGvBaAll executes as a separate task within the job. Each task name is derived
from the type of data being validated. See the sections above for the exact task name for each global validation script.
All of the error messages issued by ImGvBaAll are associated with these tasks.
ImGvBaAll is the UNIX script that executes all the base application global validation scripts. An example usage is:
unix> ImGvBaAll -u oracle_username -j BaAll -v N [-o output_file

(default=ImGvBaAll.out)]
Global validation can also be run from the PDM (Main) form within Oracle forms. See the PDM Forms User Guide –
U0325.

U0320 Revision: 1.0.0.0
Deleting Primitive Data
25 Deleting Primitive Data

A delete transaction can be initiated from a form, during a run of import or during an SQL*Plus session. Deleting from a
form is simply a matter of choosing the correct form, locating the record to be deleted, and pressing the Delete button.
Deleting during an import run requires that a flag be set in the import IDDUG record. Deleting during an SQL*Plus
session requires that the user compose a DELETE statement to remove the correct record from the correct table. In
any case, the results will be the same: the removal of one (or more) records from the database. The scope of the
delete (in other words, how much data is removed) is based on whether or not cascade delete is in effect.
25.1 Cascade Delete

A cascade delete action specifies that when records which have dependent child records are deleted from the
database, the child records are deleted as well. For example, if the record in the B1 table that defines the B1 block
called PORT is being deleted, all records that reference PORT, no matter where they reside in the data base, will be
removed or revised.
Delete actions that originate from a form or from an import automatically run with cascade delete turned on. Delete
actions that originate during an SQL*Plus session automatically run with cascade delete turned off. To turn on cascade
delete from within an SQL*Plus session, enter the following command:
sql> exec pkg_jobm.setpv_cascade_delete (‘Y’);
sql> delete from b1 where b1_name = ‘Star1’; /* or some other
delete statement/*
Cascade delete will be active for the duration of the session.
25.2 Scope of Cascade Delete

The scope of cascade delete is programmable1 and is defined when you parameterize your database.
25.3 Cascade Delete and SCADA Data

Cascade delete begins from wherever the delete is initiated and ripples out from that point, removing all dependent
records beneath it. If the cascade delete begins at the info level (analog or accumulator) or higher within the SCADA
hierarchy it can possibly remove not only the dependent records within its own hierarchy but also those records from
the Reference, RTU, TCI, Load Shed Underfrequency Load Shed Voltage Reduction Communication and Advanced
Application hierarchies where there is a parent/child relationship.
You may experience a long delay during a delete transaction, since a lot of activity is taking place beneath the surface.
In fact, it is recommended that a delete action that removes large amounts of data be broken down into several smaller
delete actions. For example, it is better, when working with a large station, to delete each B2 block individually rather
than deleting the entire B1. Attempting a too large delete can cause the Oracle error, ORA 1555 - Snapshot too old
(rollback segment too small), especially if the system is busy.
The following scenario offers a way to see the impact that a cascade delete has had on the system. It shows an
excerpt from a message table report for a job named ‘cascdel’. In this example the B3 form was used to perform a
cascade delete operation on the TA where the B1 name is PORT, the B2 name is 230K, and the B3 name is PRTLD2.
1 The dependency of child records, as defined in the FK_TABLE and FK_COLUMN tables, does not necessarily ensure
that cascade delete will occur since setting the CASCADE_DELETE field in the FK_TABLE table to “N” turns off the
cascade delete function for that relationship. See the U0385 - PDM Interface Maintenance User Guide for more
information.

U0320 Revision: 1.0.0.0
============================ START OF EXCERPT =============================

Job Name: cascdel
Job Id: 73
Task Name/
Task Id Msg Id Date Time Message
----------------- --------- ----------------- --------------------------------------------------------------------------------
task_DEL ...... ....................... Cascade Delete initiated from Table “B3” by “B3
2 Form” (Using change log sequence numbers aaa..bbb)
Keys are: B1=”PORT”;B2=”230K”;B3=”PRTLD2”
..... ....................... Cascade Delete touched subsystem “BA” Table
“ABSOLUTE_LIMIT”.
“ANALOG”.
“B3”.
“ELEMENT”.
“REFERENCE”.
“LS_FDR”.
..... ....................... Cascade Delete touched subsystem “RTDS” Table
“RTU_SCAN_ORDER”.
============================ END OF EXCERPT ============================
Notice that the actual task name has been replaced by “task_DEL” and that the actual start and end sequence
numbers have been replaced by “aaa” and “bbb”. When the cascade delete routine starts a delete, it generates a new
task name by combining the current task name with the suffix “_DEL”. If several deletes occur within the same job,
each delete task will be assigned the same name. These sibling tasks can only be distinguished, one from the other,
by looking at their task id numbers.
NOTE: Each cascade delete operation causes a new task to be created. This is done so that the user can cancel the
effects of a single delete operation -- even if other changes have already been made using the form.
If the user needs to see the data from the individual records touched by a cascade delete operation, the utility
ImRptChgLog can be used.

U0320 Revision: 1.0.0.0
25.4 Cascade Delete and Calc Operand Data

The rule of cascade delete states that if a parent record is deleted, its child records will also be deleted. But, like most
good rules, this one has an exception. In this case, the exception is the calc operand record that is based on a digital
parent. If a calculation is subordinate to a digital record and the delete action originates with its digital parent, the calc
operand record is NOT removed. Though this may seem strange, it is based on the fact that digital records are stored
“sparingly” in the PDM database. If the parent element uses default digital information, there is no need to store the
digital info in the PDM database. Later, however, when the element is transferred to the off line operational database,
the digital information is expanded to include the default infos. Therefore, removing a digital info from the Oracle
database does not imply that the digital info does not exist. If this calc operand record needs to be deleted, it must be
removed by hand.
In addition to the standard child/parent relationship, the Calc Operand record has a second set of fields that also forms
a child-like relationship with the parent tables. These secondary fields, operand_station_name, operand_voltage_level,
operand_b3, operand_element_name and operand_info_name, must be considered during a cascade delete.
Using an example where the B3 form performs a cascade delete operation on the TA where:
the B1 name = PORT,
the B2 name is 230K,
and the B3 name is PRTLD2,
any Calc Operand record whose b1_name/b2_name/b3_name matches these values or whose
operand_station_name/operand_voltage_level/operand_b3 matches these values will be deleted. Here, too, the
“sparse” digital exception applies. If the delete action originates with a digital info, it will not cascade into the calc
operand table. If this calc operand record needs to be deleted, it must be removed by hand.
25.5 Cascade Delete and Reference Data

In addition to the standard child/parent relationship in which the principle key fields, b1_name_from_side,
b2_name_from_side, b3_name_from_side, and term_name_from_side, map back to a higher level parent record, the
Reference record has a second set of fields that also forms a child-like relationship with the parent tables. These
secondary fields, b1_name_to_side, b2_name_to_side, b3_name_to_side, and term_name_to_side, must be
considered during a cascade delete.
Using an example where the B3 form performs a cascade delete operation on the TA where:
the B1 name = PORT,
the B2 name is 230K,
and the B3 name is PRTLD2,
any Reference record whose b1_name_from_side/b2_name_from_side/b3_name_from_side matches these values or
whose b1_name_to_side/b2_name_to_side/b3_name_to_side matches these values will be deleted.
If cascade delete is turned off between Base Applications and Advanced Applications (see “Scope of Cascade Delete”
on page 102), a delete of a B3 will not delete a reference if that reference points to an existing Advanced Applications
equipment. Similarly, a delete of an Advanced Applications equipment will not delete a reference if that reference
points to an existing Base Applications equipment.
If cascade delete crosses between Base Applications and Advanced Applications, all affected references will be
deleted.
25.6 Cascade Delete and RTU Scan Order Data

When cascade delete removes a B1, B2, B3, element, or info, it will also look to see if the RTU scan order table
references any of the deleted data. In most case, if it finds a reference, it does not remove the record, since the record
is needed as a place holder in the scan order table. Rather, it creates a spare record by resetting the sub_type field
and the tap_conversion_type field to 0 and “nulling out” all of the remaining non key fields. This rule does, however,
have an exception. If the scan order record refers to a digital record and the delete action originates with the digital

U0320 Revision: 1.0.0.0
record, the scan order record is NOT blanked out. Though this may seem strange, it is based on the fact that digital
records are stored “sparingly” in the PDM database. If the parent element uses default digital information, there is no
need to store the digital info in the PDM database. Later, however, when the element is transferred to the off line
operational database, the digital information is expanded to include the default infos. Therefore, removing a digital info
from the Oracle database does not imply that the digital info does not exist. If this scan order record needs to be
blanked out, it must be done by hand.
25.7 Cascade Delete and Advanced Applications Data

Cascade delete is available through the forms or SQL*Plus. It can also occur during a cascade delete action in the
Base Applications hierarchy if cascade delete between these two subsystems has been turned on.1
Running ImAaImport for subsystem ALL will delete the entire Advanced Applications model and import a new model
1 Cascade delete between Base Applications and Advanced Applications is unidirectional. A cascade delete originating
in the Base Applications hierarchy can ripple over into the Advanced Applications hierarchy. A delete in the Advanced
Applications hierarchy, however, does not cross over into Base Applications.
Cascade delete can also be defined to cross between the two subsystems at specific levels. For instance, the mapping
for the delete can begin at the company level, the station level, or any other selective level.
See the U0385 - PDM Interface User Guide for more information on how to parameterize a cascade delete.

U0320 Revision: 1.0.0.0
Modeling Primitive Data
26 Modeling Primitive Data

Modeling allows you to pick an existing set of data from the base application and/ or the advanced application data
model and use it as a template for creating a new set of data. A model transaction can be initiated from a form or by
calling a UNIX script. The scope of the modeling action (in other words, how much data is copied) is based on what
level of modeling you choose.
26.1 Modeling
ImTAModel is a PDM Interface UNIX script that copies a TA and its hierarchical data in the base applications and/or
the advanced applications database.
ImTAModel will prompt the user for the Oracle Password if it has not been passed to ImTAModel in environment
variable PASSWD.
Modeling can be done on one of four levels - B1/station, B2/voltage level, B3/equipment or Element - and may or may
not include the references.
The TA modeling task will appear as task name ‘ta_model’ in the task list for the job and all generated messages will
be associated with that job/task.
ImTAModel is the UNIX script that executes the modeling function. An example usage is:
unix> ImTAModel -u username -j myjob -s1 star1 -s2 110v -d1 star2 -
d2 110v -l 2 -aa N -r N
Modeling can also be run from the Model form within Oracle forms. See the PDM Forms User Guide - U0325.
26.2 Scope of Model

There are several switches that you can set to control the scope of the model that you are creating.
To begin with, you must set the -l or level switch. This switch can be set to:
1 - B1/Station Model
2 - B2/Voltage Level Model
3 - B3/Equipment Model
4 - Element Model
By default, the level is assumed to be level one.
Depending on what model level you choose, you must also select one or more pairs of source and destination
switches. These switches include:
s1/d1 - source and destination B1 (station) name. This switch is required for all modeling levels.
s2/d2 - source and destination B2 (voltage level) name. This switch is required for modeling levels 2, 3, and 4.
s3/d3 - source and destination B3 (equipment) name. This switch is required for modeling levels 3 and 4.
s4/d4 - source and destination Element name. This switch is required for modeling level 4.
If the name associated with any source or destination switch contains an embedded blank, be sure to enclose that
name between double quotes (i.e,. “b1 name”).
In addition to the setting the level option, you can direct the program to leave out specific pieces of data by setting the
hierarchy switches. These switches are:
ba - Copy the data in the base application hierarchy
aa - Copy the data in the advanced application hierarchy
r - Copy the reference data
U0320 Revision: 1.0.0.0
Modeling Primitive Data
By default the hierarchy switches are all set to Y, meaning that all data will be copied.
For a complete discussion of the switch options, see the man page for this script.

U0320 Revision: 1.0.0.0
PDM Interface Reports
27 PDM Interface Reports

PDM Interface reports provide the ability to produce an ASCII file displaying the contents of the PDM Interface control
tables and also some Oracle data dictionary tables. These ASCII files may then be printed.
ImRpt is a UNIX script that displays a menu of the available PDM Interface control and maintenance reports. From this
menu the user can select the desired report. This script may also be run in batch mode by supplying the correct
options. Refer to the ImRpt man page for an explanation of the switches and information on what each report contains.
unix> ImRpt -u oracle_username
[-o output_file (default=ImRpt.out)]
ImRpt Main Menu
----------------------------------------------------
Select the ImRpt Step to Perform on emp1
----------------------------------------------------
1) ImRptApplDefn
2) ImRptChgLog (extra wide)
3) ImRptChgLogHist (extra wide)
4) ImRptColumn
5) ImRptDomain
6) ImRptFk
7) ImRptIddug
8) ImRptIlock
9) ImRptIlockCtrl
10) ImRptJobLog
11) ImRptJobLogHist
12) ImRptJobTrace
13) ImRptMsg
14) ImRptMsg179 (extra wide)
15) ImRptMsgOk
16) ImRptMsgNoJobId0
17) ImRptTable
18) ImRptTablespace
19) ImRptTransferCtrl
20) ImRptCopyDefHist
21) ImRptCopyDefLog
22) ImRptHisChgLog (extra wide)
23) ImRptHisChgLogHist (extra wide)
24) ImRptCalcOpDelete
q) Exit this Session.-----------------------------------------
Enter choice:
These reports may also be run from the REP form within Oracle Forms. See the PDM Forms User Guide - U0325.

U0320 Revision: 1.0.0.0
Base Application Reports
28 Base Application Reports

Base Application reports provide the ability to produce an ASCII file displaying the contents of the BA primitive
database tables. These ASCII files may then be printed.
ImBaRpt is a UNIX script that displays a menu of the available BA reports. From this menu the user can select the
desired report. This script may also be run in batch mode by supplying the correct options. Refer to the ImBaRpt man
page for an explanation of the switches and information on what each report contains. An example usage is:
unix> ImBaRpt -u oracle_username
[-o output_file (default=ImBaRpt.out)]
ImBaRpt Main Menu

----------------------------------------------------
Select the ImBaRpt Step to Perform on emp1
----------------------------------------------------
1) ImBaRptB1
2) ImBaRptRef
3) ImBaRptRtds
4) ImBaRptRtu
5) ImBaRptAaB1Map
6) ImBaRptVol
Reports 7-14 are not available because TCI is not configured.
15) ImBaRptCfe
16) ImBaRptRegBus
17) ImBaRptCharCurve
18) ImBaRptRefDesc
19) ImBaRptTopDesc
20) ImBaRptMsCCNam
21) ImBaRptAdPreset
22) ImBaRptFxWGName
23) ImBaRptElinName
24) ImBaRptBtypname
25) ImBaRptElNameType
26) ImBaRptEtypname
27) ImBaRtpTotyname
28) ImBaRptRtuConn
q) Exit this Session.-------------------------------------------
Enter choice:

U0320 Revision: 1.0.0.0
Communication Protocol Reports
29 Communication Protocol Reports

Communication Protocol reports provide the ability to produce an ASCII file displaying the contents of the
Communication Protocol primitive database tables. These ASCII files may then be printed.
ImCommRpt is a UNIX script that displays a menu of the available reports. From this menu the user can select the
desired report. This script may also be run in batch mode by supplying the correct options. Refer to the ImCommRpt
man page for an explanation of the switches and information on what each report contains. An example usage is:
unix> ImCommRpt -u oracle_username
[-o output_file (default=ImCommRpt.out)]
ImCommRpt Main Menu

----------------------------------------------------
Select the ImCommRpt Step to Perform on emp1
----------------------------------------------------
1) ImCommRptICCP
2) ImCommRptB1ICCP
a) ImCommRptICCP & ImCommRptB1ICCP
q) Exit this Session.-------------------------------
Enter choice:

U0320 Revision: 1.0.0.0
Load Shed Reports
30 Load Shed Reports

Load Shed reports provide the ability to produce an ASCII file displaying the contents of the Load Shed primitive
database tables. These ASCII files may then be printed.
ImLsRpt is a UNIX script that displays a menu of the available reports. From this menu the user can select the desired
report. This script may also be run in batch mode by supplying the correct options. Refer to the ImLsRpt man page for
an explanation of the switches and information on what each report contains. An example usage is:
unix> ImLsRpt -u oracle_username
[-o output_file (default=ImLsRpt.out)]
ImLsRpt Main Menu

----------------------------------------------------
Select the ImLsRpt Step to Perform on emp1
----------------------------------------------------
1) ImLsRptAreaSeqFdr
2) ImLsRptSeqFdr
3) ImLsRptFdrSwh
4) ImLsRptUnused
5) ImLsRptFdrInArea
Enter choice:

U0320 Revision: 1.0.0.0
Underfrequency Load Shed Reports
31 Underfrequency Load Shed Reports

Underfrequency Load Shed reports provide the ability to produce an ASCII file displaying the contents of the
Underfrequency Load Shed primitive database tables. These ASCII files may then be printed.
ImUlsRpt is a UNIX script that displays a menu of the available reports. From this menu the user can select the desired
report. This script may also be run in batch mode by supplying the correct options. Refer to the ImUlsRpt man page for
unix> ImUlsRpt -u oracle_username
[-o output_file (default=ImUlsRpt.out)]
ImUlsRpt Main Menu

----------------------------------------------------
Select the ImUlsRpt Step to Perform on emp1
----------------------------------------------------
1) IImUlsRptFreqRlyFdr
2) ImUlsRptRlyFdr
3) ImUlsRptFdrSwh
4) ImUlsRptUnused
5) ImUlsRptFdrInFreq
Enter choice:

U0320 Revision: 1.0.0.0
Voltage Reduction Reports
32 Voltage Reduction Reports

Voltage Reduction report provide the ability to produce an ASCII file displaying the contents of the Voltage Reduction
primitive database tables. These ASCII files may then be printed.
ImVrRpt is a UNIX script that displays a menu of the available reports. From this menu the user can select the desired
report. This script may also be run in batch mode by supplying the correct options. Refer to the ImVrRpt man page for
unix> ImVrRpt -u oracle_username
[-o output_file (default=ImVrRpt.out)]
ImVrRpt Main Menu

----------------------------------------------------
Select the ImVrRpt Step to Perform on emp1
----------------------------------------------------
1) ImVrRptBusElem
Enter choice:

U0320 Revision: 1.0.0.0
Energy Accounting Reports
33 Energy Accounting Reports

Energy Accounting report provide the ability to produce an ASCII file displaying the contents of the Energy Accounting
primitive database tables. These ASCII files may then be printed.
ImEaRpt is a UNIX script that displays a menu of the available reports. From this menu the user can select the desired
report. This script may also be run in batch mode by supplying the correct options. Refer to the ImEaRpt man page for
unix> ImEaRpt -u oracle_username
[-o output_file (default=ImEaRpt.out)]
ImEaRpt Main Menu

----------------------------------------------------
Select the ImEaRpt Step to Perform on emp1
----------------------------------------------------
1) Energy Accounting
Enter choice:
These reports may also be run from the REP form within Oracle Forms. See the PDM Forms User Guide - U0325

U0320 Revision: 1.0.0.0
Editing using SQL*Plus
34 Editing using SQL*Plus

It is possible to interactively edit primitive data by entering SQL statements using the Oracle utility SQL*Plus. A note of
caution, although it is possible to interactively edit primitive data, this is almost never done. Because of all the inter-
relationships between the Oracle tables which contain the primitive data, it is difficult to determine which tables need to
be modified to make the desired change unless one is very familiar with the primitive data model. The normal, and
strongly suggested, practice is to use import or forms.
The SQL*Plus script ImJmEdit.sql is used to connect to a job in edit mode. The corresponding script ImJmEndEdit.sql
must be used to end the edit mode and disconnect from the job. An example of an SQL*Plus editing session is:
sql> @ImJmJobList
Note, this will display a list of the currently defined jobs.
sql> @ImJmEdit
sql> Enter desired SQL statements.

Note, all changes to primitive data will be captured in the
change log and associated with job ‘mary’.
sql> @ImJmEndEdit
sql> exit
unix>
If you mistakenly exit an SQL*Plus editing session without using the ImJmEdit.sql script, the job log will incorrectly
indicate that the job is currently being used and will list the job status as EDITING. Furthermore, no user will be allowed
to connect to the job using the normal scripts. To remedy this situation, the SQL*Plus script ImJmForceReady.sql
should be used to correct the row in the job log table. This script will change the status of the specified job name to
READY and set the current_username, current_date_time and session_id columns to null. The user must be careful
when using this script. A job that has been transferred to the operational database should never be changed back to
ready using this script. An example usage is:
sql> @ImJmForceReady

U0320 Revision: 1.0.0.0
Change Log
35 Change Log
The change log contains information about each change that was made to the primitive database. This information
includes the job id, the oracle_username who made the change, the date and time of the change, information which
identifies the table and row that was changed, whether the change was an insert, update or delete, and the before and
after image of the row which was changed.
ImRptChgLog.sql is an SQL*Plus script that generates a detailed report of the change log. This script may be executed
from SQL*Plus or through the UNIX script ImRpt. An example usage is:
sql> @ImRptChgLog
Enter value for report_output: change_log.jobname
Enter value for job_name: jobname
This report may also be run from the REP form within Oracle Forms. See the PDM Forms User Guide - U0325.

U0320 Revision: 1.0.0.0
Job Trace
36 Job Trace
A trace of a job shows what has occurred during the execution of the job. Multiple levels of job trace exist. The default
level is level zero. Level zero shows the major steps which have occurred during execution of the job. Levels greater
than zero provide more detailed trace. See the PDM Interface Maintenance User Guide U0385 for more details. An
example of job trace output is:
MESSAGE TIME
--------------------------------------------------------- --------
Start of Import run. Job name=star1 Job id=1 01:57:45
Processing V_LEVL record types. 01:57:46

0 errors were issued for 1 V_LEVL records. 01:57:48
.
.
.
End of Import run. Normal Termination. 45 errors were 01:58:25
issued for 686 total records.
To increase the level of job trace, enter the following command at the sql prompt:
sql> exec pkg_jobt.set_level (50); /* The value 50 will become the
new trace level. */
You can also reset the trace level of a job from within forms by reentering the job trace level value on the JOBL form.
See the PDM Forms User Guide - U0325 for additional information.
Use the following list to determine what information is added to the trace report as the level is increased. Please note
that the trace levels are cumulative. If the trace level is set to 50, the trace report will contain all messages for level 50
and below.
Trace level Description
--------- ------------------------
0 Major steps in programs are traced. This is the default.
10 Message page is traced.
20 Validation packages are traced.
30 Import merge packages are traced.
40 Change detection packages are traced.
50 Job management triggers are traced.
60 Statement triggers are traced.
70 Row triggers are traced.
The new trace level will remain in effect for the duration of the SQL*Plus session or until it is changed by another call to
pkg_jobt.set_level.
The SQL*Plus script gtrace lists the trace messages and the time each message was issued for a job. The “g” in gtrace
stands for “get”. The above sample output was produced by gtrace. An example usage is:
ImRptJobTrace.sql is an SQL*Plus script that generates a report of the trace messages for a job.This script may be
executed from SQL*Plus or through the UNIX script ImRpt. An example usage is:
sql> @ImRptJobTrace
Enter value for report_output: jobname.trace

U0320 Revision: 1.0.0.0
Job Trace
Enter value for task_id:%

ImJmClearTrace is a UNIX script that deletes the trace messages associated with a job. The associated SQL*Plus
script ImJmClearTrace.sql is also available. An example usage is:
unix> ImJmClearTrace -u oracle_username -j jobname
[-o output_file (default=ImJmClearTrace.out)]

U0320 Revision: 1.0.0.0
Validation Error Messages
37 Validation Error Messages

Validation of data occurs during entry of data into the primitive database. Error messages are issued if the data values
violate the validation rules. The error messages are stored in the Oracle table MSG. Each error message is associated
with a job.
37.1 Error Message Reports

ImRptMsg.sql is a SQL*Plus script that generates a report of the error messages associated with a job. The report
output uses 129 columns which is easily viewed in a maximized xterm window. This script may be executed from
SQL*Plus or through the UNIX script ImRpt. An example usage is:
sql> @ImRptMsg
Enter value for report_output: jobname.msg

To print a hardcopy of the 129-column report, use the following UNIX command:
unix> enscript -l -fCourier7 -d<print_queue> filename
ImRptMsg179.sql is a SQL*Plus script that generates the same report as ImRptMsg.sql. The difference is that the
report output uses 179 columns which corresponds to a landscape format for printing. Usage of 179 columns allows
more data to be printed per page. This script may be executed from SQL*Plus or through the UNIX script ImRpt. An
example usage is:
sql> @ImRptMsg179

To print a hardcopy of the 179-column report, use the following UNIX command:
unix> enscript -r -l -fCourier7 -d<print_queue> filename
The SQL*Plus script gmsg lists the error message for one message id. The “g” in gmsg stands for “get”. An example
usage is:
sql> @gmsg 5

U0320 Revision: 1.0.0.0
37.2 Creating an Error Summary

If you prefer you can run an error report that condenses the error information and produces a summary similar to the
one shown below.
To run this report enter sqlplus and at the sql prompt type the following commands:
sql> set linesize 100
sql> spool <file_name>
The report will go to a file called <file_name>.
lst sql> @gmsgdist <name_of_job>
You may use % to retrieve error summaries for all jobs
Report Output ...
sql> spool off

Don’t be alarmed as data speeds by you on the screen. This same data is also being placed in the file called
<file_name>.lst and can be viewed by using your editor of choice. The report will contain information that looks
something like this:
===============================
Message counts by source name
===============================
Count Job Message Source
----- --- ----------------- -- ------------------
162 % ImImpBulk
5 % ImTrJobTransfer
11 % PKGIMP_B1.MERGE
96 % PKG_ACCUMULATOR.VAL_RECORD_ACCUMULATOR
24 % PKG_ANALOG.VAL_RECORD_ANALOG
1 % PKG_APPL.SET_SKIP
3 % PKG_B1.no_RTDS_insert
66 % PKG_B3.VAL_RECORD_B3
117 % PKG_DIGITAL.VAL_RECORD_DIGITAL
18 % PKG_RTU_SCAN_ORDER.VAL_RECORD_RTU_SCAN_ORDER
38 % pkg_calc_operand.val_calc_operand
3 % pkg_digital.vl_initial_value
2 % pkg_elcom_gv.val_elcom
2 % pkg_import_ba.main
1 % pkg_import_elcom.main
1 % pkg_import_wscc.main
==============================================
Message counts by Message Code and Site Code
==============================================
Count Job Msg Code Site
----- ---- ------ ---
13518 % 102 e
2 % 103 e
17601 % 104 e
3 % 108 e
10 % 123 e
30 % 151 e
1 % 224 e
U0320 Revision: 1.0.0.0
14 % 10237 e
=======================================
Message counts by Job Name and Job_Id
=======================================
Job Name Job Id Count
------- ----- -----
Carver 25 123
Castillo 26 12
GvRtsMis 109 3
ImGvB1 86 96
LdShed 110 13
Line 45 3
London 47 12
MPLS 48 51
=====================================
Message counts by source_table name

=====================================
Count Job SourceTable

---- --- ---------
96 % ACCUMULATOR
51 % ANALOG
3 % B1
3 % B2
66 % B3
38 % CALC_OPERAND
117 % DIGITAL
1362 % ELCOM_PARTNER_ACCESS
24587 % None
3 % RTU_PROTOCOL_TYPE
==============================================
Message counts by Message Code and Site Code

==============================================
Count Msg Code Site Message_Template

------- -------- ----- ------------------------
13518 102 e Unanticipated exception. Oracle message follows. %1
2 103 e Cascade Error. Error returned from %1. %2.
17601 104 e %1
3 108 e %1” must be %2 %3
10 123 e The B1/B2/B3/Element/Info “%1”/”%2”/”%3”/”%4”/”%5” is used as an incoming
point for both %6 and %7. This will cause on of the applications to overwrite
data from the other. Remove the TA from one of the applications.
30 151 %1
224 e %1 transfer for job %2 was skipped. Oracle and the on-line database are no
longer in sync for this application.
1410 237 e No matching RTU scan order record with a subtype of 8 (analog-to-digital-tap)
was found for the RTU scan order record with a subtype of 1 (single pole digital)
and a tap conversion type of 0 (no tap conversion). RTU name “%1”, B1 name
“%2”, B2 name “%3”, B3 name “%4”, element “% information name “%6”. A
match must exist with the same B1/B2/B3 block and in the same RTU since the
norm element type for the digital info is TapChan.
U0320 Revision: 1.0.0.0
5 10238 e The info type of the B1/B2/B3/Element/Info specified on the scan order record
for rtu “%1”, scan order number “%2” is not defined as controllable, but a
Control Address is defined for it. Setpoints cannot be operator initiated from
one-lines for non-controllable infos.
9 10245 e The field “%1” for RTU “%2” and RTU Scan Group “%3” is superfluous because
the Scheduling Type field for Channel “%4” is equal to “%5”.
37.3 Deleting Error Messages

ImJmClearMsg is a UNIX script that deletes the error messages associated with a job. The associated SQL*Plus script
ImJmClearMsg.sql is also available. An example usage is:
unix> ImJmClearMsg -u oracle_username -j jobname -t taskid
[-o output_file (default=ImJmClearMsg.out)]
This may also be run from the PDM (Main) form within Oracle Forms. See the PDM Forms User Guide - U0325.

U0320 Revision: 1.0.0.0
Job Undo/Job Redo
38 Job Undo/Job Redo

Job undo removes the changes that were made to primitive data by the job. The primitive database is restored to its
state prior to the job.
ImJmUndo is a UNIX script that executes job undo. The associated SQL*Plus script ImJmUndo.sql is also available.
unix> ImJmUndo -u oracle_username -j jobname
[-o output_file (default=ImJmUndo.out)]
Job redo re-applies the change made by a job to the primitive data tables. A redo is allowed only for a job with a status
of UNDONE.
ImJmRedo is a UNIX script that executes job redo. The associated SQL*Plus script ImJmRedo.sql is also available. An
example usage is:

unix> ImJmRedo -u oracle_username -j jobname
[-o output_file (default=ImJmRedo.out)]
The Job Undo and Job Redo functions are also available through the PDM (Main) form within Oracle Forms. See the
PDM Forms User Guide - U0325.

U0320 Revision: 1.0.0.0
Task Cancel
39 Task Cancel
It is possible to cancel tasks from a job in reverse order. Cancelling a task removes the changes associated with the
last task from the primitive data and from the change log. This ability allows the user to remove some of the changes
associated with a job, and then continue using the job. Note that it is always the last task that is cancelled.
The restrictions which apply to job undo also apply to cancelling a task. If the data involved in a task is required to
satisfy a foreign key constraint, the cancel of the task will not be allowed. One difference between job undo and task
cancel is that the job undo can be reversed by a job redo. A cancel of a task is not reversible.
ImJmCancelTask is a UNIX script that cancels a task. The associated SQL*Plus script ImJmCancelTask.sql is also
available. An example usage is:
unix> ImJmCancelTask -u oracle_username -j jobname
[-o output_file (default=ImJmCancelTask.out)]

The task cancelling function is also available through the TASL and JOBL forms within Oracle Forms. See the PDM
Forms User Guide - U0325.

U0320 Revision: 1.0.0.0
Job Transfer
40 Job Transfer
Job transfer provides the ability to transfer a job from the primitive database to the operational database. Job transfer
uses the change log to determine what has changed, extracts the modified data from the primitive database and writes
the data into the offline operational database as part of a DBA job.
The execution of job transfer may be accomplished manually by executing a series of scripts or by using the PDM
(Main) form within Oracle Forms. The PDM (Main) form is the recommended approach as it will handle the proper
setting of job statuses through out the life of a job. See the PDM Forms User Guide - U0325 for more information on
the PDM (Main) form.
40.1 Execute Job Transfer

ImBaJobTransfer is the UNIX script that executes job transfer. The job name specified by the “-j” option is the primitive
database job name. A corresponding DBA job is created in the offline operational database with the same name,
except the name is forced to upper case. If the user desires both job names to be identical, the user must create the
primitive job name in upper case. Refer to the man page for more information about this script and its options. An
example usage is:
unix> ImBaJobTransfer -u oracle_username -j jobname
[-o output_file (default=ImBaJobTransfer.out)]
The Job Transfer function is also available through the PDM (Main) form within Oracle Forms. See the PDM Forms
User Guide - U0325.
If an error occurs and the messages are not clear, debug may be enabled by using the -t, -d, and –e switches during
the job run.
If the -s switch (Stable Data Model) is Y, then it is assumed that DMX_CONF/config parameter StableDM is set to true
and nimset numbers are not re-used. If Stable Data Model is N, then nimset numbers are being re-used and transfer
will force jobs with deletes to complete before jobs with inserts are allowed to proceed.
The -t switch should not normally be used; it is needed for bulk transfer operations in conjunction with the “full” transfer
option and is set internally. If the -t switch is set improperly (requesting a transfer that would allow the Oracle database
and the off-line operational database to become “unsynchronized”), the transfer program will terminate with an error
message.
The -d switch enables additional output messages for a specific object. For example, “-d 1” issues additional messages
about the b1 object, “-d 2” issues additional messages about the b2 object, and so forth.
Setting the -e switch to 1 will turn on additional output messages that do not pertain to a specific object. Setting this
switch will produce prodigious amounts of information. Beware of its verbosity. It is possible to get more detailed trace
by setting the job trace level value to a higher number using the -l switch.
After ImBaJobTransfer has finished execution, the BA transfer status for the job is set to TRANSFERRED
(TRANSFER_FAILED if unsuccessful), and the changes are in the offline operational database. The DBA subsystem
may be used to view the DBA job in the offline operational database. Refer to the DBA Editor’s user guide (U0310) for
more information on the DBA subsystem.

U0320 Revision: 1.0.0.0
Job Transfer
40.2 Check Job Transfer Output

After executing script ImBaJobTransfer, the user must check if any errors were issued. Check the UNIX output file, the
error message table, and the ADM console log. Use ImRptMsg to generate a report of the error messages related to
the job transfer task. An example usage is:
sql> @ImRptMsg
Enter value for task_id: 3 <-- Enter task id of job
transfer
The message report is also available through the PDM (Main) form within Oracle Forms. See the PDM Forms User
Guide - U0325.
Use grep to list the job transfer error messages in the ADM console log. An example usage is:
unix> tail -2000 /var/adm/messages | grep ImTrJo
Note: If nothing returns when working with the grep, try the tail without the grep. It is possible for the
/var/adm/messages file to get full.
Example error messages resulting from this command are:
Mar 14 14:33:24 mm01_dem2 ImTrJo 2803 .dopb1 4 3 0
Use man to get additional information about the ADM console log error messages. There are three parameters for
man. The first is the name of the .err file which contains the error text, the second is “err”, and the third is the error
number. An example usage is:
unix> man dopobj_b1 err 2803
In the case of job transfer, it may take some effort to translate the console message into the appropriate parameter
values for man. Unlike most other Spectrum Power 3 subsystems, the user cannot simply use the application name
from the console message (the third field within the message, ImTrJo in the example above).
ADM console messages for job transfer originate from the object functions that are called. An identifier for the object
function is found in the fifth field of the console message (.dopb1 in the example above). The object function identifying
field for job transfer console messages always starts with “.dop”. In most cases, the name of the .err file that contains
the error text can be generated by removing the initial “.” and inserting “obj_” between “.dop” and whatever follows it.
(“.dopb1” in the example console message translates to “dopobj_b1” as the example parameter for man which
indicates that the dopobj_b1.err file contains the error text for that console message.) Since there are several
exceptions to this rule, Table 41-1 is provided to help map the application names and the console messages to their
corresponding .err files.
Table 40-1: Mapping an Application Name to an Error File Name
Application Console Message Corresponding .err file name
Application Name
Accumulator Info .dopinac dopobj_in_ac
Analog Info .dopinan dopobj_in_an
B1 .dopb1 dopobj_b1
B2 .dopb2 dopobj_b2
B3 .dopb3 dopobj_b3
Characteristic Curves .dopcc dopobj_cc
Common Link Users Interface .dopclui dopobj_clui

U0320 Revision: 1.0.0.0
Job Transfer
Application Console Message Corresponding .err file name

Application Name
Digital Info .dopindg dopobj_in_dg
Element .dopelem dopobj_elem
Expert System Protection .dopespr dopobj_espr
Expert System Protection Symbol .dopessy dopobj_essy
ICCP .dopiccp dopobj_iccp
Load Shed - Area Object .doplsar dopobj_lsarea

Load Shed - Feeder Object .doplsfd dopobj_lsfdr
Load Shed - Priority Object .doplspr dopobj_prio
Load Shed - Sequence Object .doplssq dopobj_lsseq

Load Shed - Switch Object .doplssw dopobj_lsswh
Multisite .dopms dopobj_ms
Operand .dopoper dopobj_oper

Reference .dopref dopobj_ref
RTDS - Channel .dopchan dopobj_chan

RTDS - Communication Interface Adapter (CIA) .dopcia dopobj_cia
RTDS - Line .dopline dopobj_line

RTDS - RTU .doprtu dopobj_rtu
RTDS - RTU Group .doprtug dopobj_rtu_group

RTDS - RTU Protocol .doprtup dopobj_rtu_proto
RTDS - RTU Scan .doprtus dopobj_rtu_scan
RTDS - RTU Scan 3X .doprtu3 dopobj_rtu_scan_3x
RTDS - Scan Order .doprtuo dopobj_rtu_scan_order
RTDS - Scan Subgroup .doprtub dopobj_rtu_scan_sub
RTDS - SCSI Adapter Module (SAM) .dopsam dopobj_sam
Underfrequency Load Shed - Feeder .dopulsf dopobj_ulsfdr
Underfrequency Load Shed - Frequency .dopulsq dopobj_ulsfreq
Underfrequency Load Shed - Relay .dopulsr dopobj_ulsrly
Underfrequency Load Shed - Switch .dopulss dopobj_ulsswh
Voltage Set .dopvols dopobj_voltage_set
Voltage Reduction - Bus .dopvrb dopobj_vrbus
Voltage Reduction - Element .dopvre dopobj_vrelem

U0320 Revision: 1.0.0.0
Job Transfer
40.3 DBA Job Management

DBA Job Management can be managed in several ways. Either through the DBA Editors, the PDM (Main) form within
Oracle, or the script ImDBAJobMgmt. If the DBA Editors are used, then the Oracle job statuses will have to be
maintained by the users. If the PDM (Main) form or ImDBAJobMgmt is used, then the Oracle job statuses will be
automatically updated to reflect the current action.
The parameters for ImDBAJobMgmt are:
ImDBAJobMgmt -u user -j job_name -f dba_function -a application -c command line
[-o output_file] [-d debug_switch]
Where user = Oracle user name
passwd = Oracle password
job_name = job management job name assoc with this run;

dba_function = DBA function to process
A - Activate (copy 1 to copy 0)
AF - Force Activate (copy 1 to copy 0)
C - Cancel (cancel from copy 1)
U - Undo (undo from copy 0)
UF - Force Undo (undo from copy 0)
D - Delete (delete activated job)
T - Server Test Connected
application = BA
AGC
output_file = Output path/file Default=pwd/ImBaDBAJobMgmt.out
command line = Script is being executed from the UNIX command line
execution
Y - Is being executed from command line (default)
N - Is being executed from the PDM (Main) form
debug_switch = Debug switch
40.4 Cancel the DBA Job

If any errors were issued that need to be corrected in the primitive database, the data transfer must be reversed. The
following options will remove the changes from the offline operational database and reset the job status to READY
within the primitive database.
Using the PDM (Main) form: select CANCEL.
Using ImDBAJobMgmt:
unix> ImDBAJobMgmt -u oracle_username -j jobname -f C -a BA
[-o output_file (default=ImBaDBAJobMgmt.out)]

U0320 Revision: 1.0.0.0
Job Transfer
40.5 Use the DBA Editors to Make Additional Changes

After the job has been successfully transferred without errors, the user may make additions to this job using the DBA
Editors. The most common example would be to use the graphics editors to modify the world maps to use the new
data entered via the primitive database. Note, data which originates in the primitive data base may be viewed via the
DBA editors (Display Mode), but not modified. This would be the data defined by the Block, Element, TelAssign,
Measurand, Counter, Reference, Chae, and RTDS editors.
Refer to the DBA Editors User Guide (U0310) and the Graphics Editor User Guide (U0240).
40.6 Activate the DBA Job

Activating a DBA job causes the changes that were made to the offline operational database to be applied to the online
operational database. The following options will activate the changes in the online operational database and set the
activate status to ODB_ACTIVATED within the primitive database.

Using the PDM (Main) form: select ACTIVATE.
Using ImDBAJobMgmt:
unix> ImDBAJobMgmt -u oracle_username -j jobname -f A -a BA
In the event that activation fails, you might consider using the -f AF option. This is comparable to Forced Activation
option that is available on the DBA menu and is subject to the same limitations.
After activating the DBA job, the user has two choices - to either delete or cancel the job. If the user wishes to accept
the changes made by the job, the user should delete the job. If the user wishes to remove the changes made by the
job, the user should cancel the job. The next two sections in this chapter describe how to delete or cancel an activated
DBA job.
40.7 Delete the DBA Job

After the DBA job has been activated and the user has verified that the online operational database is operating as
desired, the DBA job should be deleted. The following options will delete the DBA job leaving the data changes in the
offline and online operational database, reset the job status to ODB_DELETED within the primitive database and
delete the job from the primitive database.
Using the PDM (Main) form: select DELETE.
Using ImDBAJobMgmt:
unix> ImDBAJobMgmt -u oracle_username -j jobname -f D -a BA
40.8 Undo the DBA Job

After a job has been activated, the user may decide to undo the activation. This removes the changes from the online
operational database only. The following options will undo the changes in the online operational database and reset
the activate status to ODB_READY within the primitive database.
Using the PDM (Main) form: select UNDO.
Using ImDBAJobMgmt:
unix> ImDBAJobMgmt -u oracle_username -j jobname -f U -a BA
In the event that the undo fails, you might consider using the -f UF option. This is comparable to Forced Undo option
that is available on the DBA menu and is subject to the same limitations.

U0320 Revision: 1.0.0.0
Job Transfer
40.9 Caution
In some cases, the order of job execution is important within the operational database. In Oracle, PDM provides data
interlocking which prevents the user from modifying data which has been modified by another job. In the operational
database, there are internal numbers that are generated outside this interlock process.
Consider the following scenario.
$SPECPATH/par/DMX_CONF/config parameter StableDatMod is set to false. This means that the operational internal
nimset numbers may be re-used.
Job A executes a cascade delete of a B3 and successfully transfers this data to the offline operational database. Note
that this makes available some previously used nimset numbers.
Job B defines a new B1 and its subordinate data and is also successfully transferred to the offline operational
database. During this process, some of its data is assigned nimset numbers that were made available by the deletes in
Job A.
If either Job A is deleted from the offline operational database and/or Job B is activated to the online operational
database, a situation where a nimset number is assigned to more than one equipment can occur.
In order to prevent this from occurring, the -s (StableDM) switch has been added to the transfer program. This switch
defaults to N (to align with StableDatMod=false). This switch will cause an additional check against the entries in the
change_log. If the specified job is a FULL TRANSFER or there are inserts of B1, B2, B3, ELEMENT or RTU data and
there are one or more other jobs which delete data from any of the same tables, the transfer will be aborted and the
user will be recommended to cancel or transfer/activate/delete all jobs which contain the data deletes.
This error condition can be overridden by setting the -s switch to Y. Just be sure to process a job from start to finish.

U0320 Revision: 1.0.0.0
Build and Transfer Advanced Application Databases
41 Build and Transfer Advanced Application Databases

This section describes how all the Advanced Application databases (relations and SNAP) are to be built.
To build and transfer all the Advanced Application databases at once (except for the databases using relations), use
the following script:
unix> AADbBldAll
Each of the following sections describes how to build specific databases; the applications are grouped according to the
database they use.
41.1 Transfer the Relation Databases

41.1.1 Transfer AGC Relations

AGCpop transfers the AGC database relations from the primitive database. The following steps must have been
performed prior to running AGCpop:
1. Ensure all AGC blocks and elements exist in SCADA Oracle.
2. Activate any SCADA jobs defining AGC blocks and elements.
AGCpop transfers AGC relations containing curve and combination (mapping) data as well as AD values and boolean
relations with unit, fuel area, interchange and system data.
The UNIX command to execute adtransfer is:
unix> AGCpop -u oracle_password -j jobname
You will be prompted for the Oracle password when you run this script. The jobname must match the jobname used to
import or edit data using forms.
The output file, AGCpop.out is written to the local directory.
41.1.2 Transfer Load Forecast Relations (LFTRAN)

Lftran transfers the short term Load Forecast relations from the primitive database. However, not all the data required
for the Load Forecast relations resides in Oracle. Before executing lftran, insure that the following have been done:
1. The Load Forecast function is installed with the number of users and forecast areas required. In particular, the
number of areas defined in the Load Forecast on-line operational database relations must equal or exceed the
number defined in Oracle.
2. The import of Scheduling Application data from IDDUG format to Oracle must be completed (sca_import).
The Load Forecast relations are defined only on the ADM and only for copy 0. The Load Forecast population can be
completed in a single step by executing lftran on the ADM. The UNIX command to execute lftran is:
unix> lftran
The following data items from Oracle are used to transfer the applicable Load Forecast relations:
Forecast area names
Day types
Advance interval definition
Anomaly thresholds
Pattern matching weighting factors
Similar day load and deviation patterns

U0320 Revision: 1.0.0.0
Build and Transfer Advanced Application Databases
41.2 Transfer the Oracle databases
41.2.1 Transfer Unit Commitment (UC) data

PdbUcPop transfers the Unit Commitment Application data from the primitive database. The UNIX command to
execute this script is:
unix> $SPECPATH/sys/gcs/mro_uc/PdbUcPop.cmd
The data is transferred to the first UC user in the gcs1 sid on the GCS/GCNA/GCNE box. PdbUcPop.cmd will create a
log file during the transfer to hold error messages, this files is called $ADBHOME/MRO_UC.out.

U0320 Revision: 1.0.0.0
Job Delete
42 Job Delete
Job delete is used to clean up the primitive database control tables after the job has been taken through the normal
steps of being transferred to the offline operational database, activated into the online operational database and
deleted from the operational database job management control relations. After a job has been deleted, the changes
made by the job are permanent in both the primitive database and operational database. In contrast, job cancel is used
to clean up the primitive database when the changes made by the job should be removed from existence.
ImJmDelete is a UNIX script that deletes a job which has been activated into the online operational database. When a
job is deleted, the job log entry is moved to the job log history table, the status is set to ODB_DELETED, all task
information is removed, and the change log entries associated with the job are moved to the change log history table.
The associated SQL*Plus script ImJmDelete.sql is also available. An example usage is:
unix> ImJmDelete -u oracle_username -j jobname
[-o output_file (default=ImJmDelete.out)]

Jobs may also be deleted using the PDM (Main) form within Oracle Forms. See the PDM Forms User Guide - U0325.

U0320 Revision: 1.0.0.0
Job Cancel
43 Job Cancel
Cancelling a job returns the primitive database to its original state prior to the job’s existence. A job cancel is allowed
only if the job has never been transferred to the operational database, or, if it was previously transferred, then it must
also have been cancelled out of the operational database.
ImJmCancel is a UNIX script that cancels a job. When a job is cancelled, the job log entry is moved to the job log
history table with a status indicating the job was cancelled. If any changes were made to primitive data, the changes
are undone. The change log entries are not saved in the change log history. The associated SQL*Plus script
ImJmCancel.sql is also available. An example usage is:
unix> ImJmCancel -u oracle_username -j jobname
[-o output_file (default=ImJmCancel.out)]
Jobs may also be cancelled using the PDM (Main) form within Oracle Forms. See the PDM Forms User Guide -
U0325.
ImRptJobLogHist.sql is an SQL*Plus script that generates a report of the jobs which have been deleted or cancelled.
This script may be executed from SQL*Plus or through the UNIX script ImRpt. An example usage is:
sql> @ImRptJobLogHist
Enter value for report_output: joblog.history
This report may also be run from the PDM (Main) form within Oracle Forms. See the PDM Forms User Guide - U0325.

U0320 Revision: 1.0.0.0
Job History
44 Job History
Information about a job is saved for historic purposes. The length of time this job history is saved is a decision that is
made by each Spectrum Power 3 customer.
44.1 Job Log History

The job log history contains a record of the jobs which have existed in the past. The job log history identifies whether
the job was activated into the operational database or whether it was cancelled.
ImRptJobLogHist.sql is an SQL*Plus script that generates a report of the job log history table. This script may be
executed from SQL*Plus or through the UNIX script ImRpt. An example usage is:
sql> @ImRptJobLogHist
Enter value for report_output: joblog.history

44.2 Change Log History

Rows are entered into the change log history table when a job is deleted. ImRptChgLogHist.sql is an SQL*Plus script
that generates a detailed report of the change log history table. This script may be executed from SQL*Plus or through
the UNIX script ImRpt. An example usage is:
sql> @ImRptChgLogHist
Enter value for report_output: chgloghist.jobname
The change log history table will continue to grow until it is manually cleared out. Because of the large number of rows
which may accumulate per job, the amount of free space in this table should be monitored. Use the Oracle DBA views
(specifically DBA_FREE_SPACE) to see current space utilization.
ImJmClearChangeLogHistory is a UNIX script that deletes the change log history entries for a job. The associated
SQL*Plus script ImJmClearChangeLogHistory.sql is also available. An example usage is:
unix> ImJmClearChangeLogHistory -u oracle_username -j jobid
[-o output_file (dflt=ImJmClearChangeLogHistory.out)]
44.3 Deleting Job Log and Change Log History

The Job Log history and the Change Log history can be removed from the database on a job-by-job basis or based
upon the date when the historical data was created.
To delete all of the entries from your job log and change log, use the UNIX script ImJmJobHistoryDelete as follows:
unix> ImJmJobHistoryDelete -u oracle_username -j ALL
This command will delete the job log history and change log history entries for the job whose job_id is 90.
unix> ImJmJobHistoryDelete -u oracle_username -j 90
This command will delete job log history and change log history entries older than September 24, 1995.
unix> ImJmJobHistoryDelete -u oracle_username -d 09/24/95
Refer to the man page for more information on the script options.

U0320 Revision: 1.0.0.0
Base Applications Reverse Transfer
45 Base Applications Reverse Transfer

Reverse transfer provides the ability to initialize SCADA, Reference, RTDS/CFE, ICCP, and Energy Accounting data in
an empty primitive database from an existing operational database. The reverse-transferred data falls into two
categories: IDDUG data (also known as customer data or base data) and filltab data (also known as control table data).
Each data type has its own reverse transfer procedure.
To reverse transfer IDDUG data, use the script ImBaRvIddug. Choose your processing options by selecting the
appropriate parameters from the following list:
ImBaRvIddug
[-l] Location (directory) to write IDDUG Files
-- One IDDUG file per B1
-- One Refer IDDUG file called ‘references’

-- One RTDS IDDUG file called ‘rtds_dat’
-- One Voltage Set IDDUG file called ‘volt_set’
[-a] Application to export.
Default = abcdef if options ‘-b’, ‘-r’, ‘-s’ not
specified;
otherwise the default is the corresponding application
‘a’, ‘b’, or ‘ab’.
a - SCADA
b - RTDS
SAM
c - References
d - Miscellaneous
Voltage Set Limits
e - ICCP
f - CMCH
g - EA
Default=pwd/ImBaRvIddug.out
[-b] B1 Name
[-r] RTU Name
-- If ‘all’, one IDDUG file per RTU in ‘-1’ location
-- If one actual RTU name, one IDDUG file for that RTU
only in ‘-1’ location
-- If neither ‘-s’ option nor ‘-r’ is specified, value
‘all’ will be set and one IDDUG file per RTU/SAM in
‘-1’ location
[-s] SAM Name
-- If ‘all’, one IDDUG file per SAM in ‘-1’ location
-- If one actual SAM name, one IDDUG file for that SAM
only in ‘-1’ location
-- If neither ‘-s’ option nor ‘-r’ is specified, value
‘all’ will be set and one IDDUG file per RTU/SAM in
‘-1’ location
[-h] Include HIS records. (y/n) default=n
[-u] Oracle Username (PDM EMP database)
[-n] Copy number. Default=1

U0320 Revision: 1.0.0.0
[-d] Debug Level. Default=0

Note that the directories specified by the -l and/or -o parameters must be created before execution of reverse transfer.
To reverse transfer filltab data, use the script ImBaRvFilltab. Choose your processing options by selecting the
unix> ImBaRvFilltab
-p Path (directory) for filltab files
[-n] copy number. Default = 0
[-c] commit_interval. Number of records before each
commit statement in filltab files. Default = 100.
[-d] Debug file
Note: Use redirection of standard output for error file.
A reverse transfer consists of the following steps:

1. Extract the IDDUG data from the operational database. The IDDUG-formatted data is written to the specified
directory in IDDUG format. The BA control table data is written to the specified directory in filltab file format
containing SQL insert statements.
Note that these BA control table filltab files should be loaded into the Oracle database instead of the corresponding
filltab files in directory $SPECPATH/src/schema/pdm/owner/prime/data. This is because the filltab files created by
reverse transfer contain the control data (e.g., block types, topology types, info names, etc.) that correspond to the
project data.
2. Load the BA control table filltab files into the primitive database using the ImBaLoadFilltab script.
3. Import the unchanged IDDUG files into the primitive database with change detection turned off because it will not
be necessary to transfer the job to the operational database. Refer to the section “Execute Import and Check
Results” on page 67.
It is recommended that the SCADA station data be imported first, followed by the RTDS data in rtds_dat.
4. Update the id numbers (e.g., B1 number, RTU number, etc.) in the primitive database to match those of the
operational database. The symbolic name is what is used to find the match. If a name was changed in the primitive
database, no match will be found. ImBaRvUpdateIds is the UNIX script that updates the id numbers. See the man
page for more details. An example usage is:
unix> ImBaRvUpdateIds -u oracle_username -j jobname -n
odb_copy_number -d debug_filename >out_error 2>out_debug
After ImBaRvUpdateIds has finished check the output. Make sure that the constraints and triggers have been re-
enabled.
Note, Oracle DBA view ‘user_constraints’ may be queried to see the status of the constraints (xxxx = UNQ_B1_B1,
UNQ_B2_B1NB2, and UNQ_B3_B1NB2NB3). The status for constraints must be ‘enabled’.
sql> select status from user_constraints where
constraint_name=’xxxx’
Note, Oracle DBA view ‘user_triggers’ may be queried to see the status of the triggers (xxxx = B1, B2, B3,
SCSI_ADAPTER_MODULE, COM_INTERFACE_ADAPTER, CHANNEL, RTU_LINE, RTU, RTU_GROUP, and
RTU_SCAN_GROUP). The status for triggers should be either ‘enabled’ or ‘error’.
sql> select trigger_name,trigger_type,status from user_triggers
where table_name=’xxxx’
A status of ‘disabled’ for either constraints or triggers should be looked into.
5. After a reverse transfer and import, it is not necessary to do a job transfer. Use the following steps to delete the
primitive database job;
sql> update job_log set status=‘ODB_DELETED’ where job_name=’xxxx’;
Note, replace the xxxx with the import job name.

U0320 Revision: 1.0.0.0
sql> commit;
sql> exit;
unix> ImJmDelete -u oracle_username -j jobname

U0320 Revision: 1.0.0.0
Full Transfer
46 Full Transfer
Full transfer provides the ability to transfer a B1, RTU, SAM, ICCP, LS, ULS, and VR hierarchy of data from the
primitive database to the operational database. The difference between full transfer and job transfer is in what is used
to determine the data to be transferred. Job transfer uses the change log whereas full transfer uses key information
supplied by the user.
It is important to note that Copy Management does not support deployment of `full' transfer jobs to the `Copy' system -
if it is determined that a `full' transfer is needed on the Main and Copy systems, the `full' transfer must be manually
executed on the `Copy' system.
To do a full transfer of data, use the script ImBaJobTransfer. Choose your processing options by selecting the
unix> ImBaJobTransfer
-u Oracle Username(table owner)
-j Job Name
Default=pwd/${SN}.out
[-f] Full Transfer
(b1/rtu/sam/elcom/iccp/wscc/ls/uls/vr)
[-k] Key value for full transfer
[-s] Stable Data Model flag (Y/N)
Default=N
[-t] Test switches
SCADA
a = b1 (1) b = b2 (2)
c = b3 (3) d = elem (4)
e = accum (5) f = analog, voltage set range (6)
g = digital (7) h = reference (8)
RTDS/CFE
j = sam (10) k = rtu_proto (11)
l = cia (12) m = chan (13)
n = line (14) o = rtu_group (15)
p = rtu (16) q = rtu_scan_3x (17
r = rtu_so (18) s = rtu_scan (19)
t = rtu_sub (20)
COMM
u = iccp (21)
Load Shed
A = fdr (24) B = swh (24)
C = seq (24) D = area (24)
E = prio (24)
UnderFrequency LoadShed
G = fdr (25) H = swh (25)
I = rly (25) J = freq (25)
Voltage Reduction
L = bus (26) M = bus_element (26)
z = guid (28) Guid_TA processing
[-c] Command Line Execution (Y/N)
Default=Y

U0320 Revision: 1.0.0.0
Full Transfer
[-d] Debug Level, see the bracketed numbers given for

the -t switch. Use these numbers to set the debug
level. For example, the debug level for the full
transfer of an element would be 4.
[-e] Debug Level 2
[-l] Trace Level
A DBA job is created for the full transfer. A corresponding job is created within the primitive database for error reporting
purposes only.
To transfer a B1 hierarchy, use the UNIX script ImBaJobTransfer as follows:
unix> ImBaJobTransfer -u oracle_username -f b1 -j jobname -k
b1_name
Note, if the b1_name contains blanks, enclose the name in double quotes. For example, “b1 name”.
To transfer all SAM hierarchy, use the UNIX script ImBaJobTransfer as follows:
unix> ImBaJobTransfer -u oracle_username -f sam -j jobname
This command will transfer RtuPrototype, RtuGroup, Sam, Cia, Channel, and RtuLine data.
To transfer a RTU hierarchy, use the UNIX script ImBaJobTransfer as follows:
unix> ImBaJobTransfer -u oracle_username -f rtu -j jobname -k
rtu_name
This command will transfer Rtu, RtuScan3x, RtuScanOrder, RtuScanGrp, and RtuScanSubGrp data for the specified
key. To force the transfer of RtuPrototype, Channel, and RtuGroup data within the full transfer of an Rtu, you must
explicitly set the -t switch to look like this:
unix> ImBaJobTransfer -u oracle_username -f rtu -j jobname -k

rtu_name -t kmopqrst
To transfer all ICCP information, use the UNIX script ImBaJobTransfer as follows:
unix> ImBaJobTransfer -u oracle_username -f iccp -j jobname
To transfer all Load Shed information, use the UNIX script ImBaJobTransfer as follows:
unix> ImBaJobTransfer -u oracle_username -f ls -j jobname
To transfer all Underfrequency Load Shed information, use the UNIX script ImBaJobTransfer as follows:
unix> ImBaJobTransfer -u oracle_username -f uls -j jobname
To transfer all Voltage Reduction information, use the UNIX script ImBaJobTransfer as follows:
unix> ImBaJobTransfer -u oracle_username -f vr -j jobname
It is not possible to delete data from the operational database using full transfer. Only updating or inserting data is
possible.
After the completion of a full transfer follow the steps outlined in the chapter on Job Transfer (page 139) for more
details related to DBA job activate/delete/cancel.

U0320 Revision: 1.0.0.0
Operating Modes
47 Operating Modes
OTS and TEST operating modes are supported by the use of a separate primitive database. The steps to create this
separate database are:
Configure an OTS or TEST system. This includes a separate ADM/DEMS server in Training or Test mode. This
server must have its own Oracle database. The Oracle database must have the Spectrum Power 3 schema
installed, just as it exists on the Process ADM server.
Execute reverse transfer on the on-line operational database.
Execute import on the Training or Test ADM server using the generated IDDUGs.
Execute update ids on the Training or Test ADM server to synchronize off-line operational database and Oracle
internal numbers.
At this point an OTS/TEST primitive database is ready for use. The user may perform data manipulation activities on
the OTS/TEST Oracle database via Forms, Import, etc. and transfer the data changes to OTS/TEST online.
If the changes are to be moved to the Process ADM, do the following:
Execute export (ImBaExport, ImCommExport, etc.) for the data that is to be moved.
Move the generated IDDUG files to the Process ADM.
Import the IDDUG files, job transfer, and activate change

U0320 Revision: 1.0.0.0
IM Tools
48 IM Tools
48.1 ImBaDeleteTA
ImBaDeleteTA is a UNIX script that can perform cascading delete operations from the user-supplied B1, B2, B3 or
ELEMENT names.
The B1/B2/B3/Element names can also include Oracle wildcard symbols (%). If these characters are included in the
options, Oracle will search for and delete data where the % can represent any character string present in the database.
48.1.1 Executing ImBaDeleteTA

To delete the data in the database associated with B1 name “PORT”:
unix> ImBaDeleteTA -u oracle_user -j Job2 -ta1 PORT

To delete the data in the database associated with the B1/B2/B3 address “PORT/230K/PRTLD%”:
unix> ImBaDeleteTA -u oracle_user -j b3job -ta3 PORT 230K PRTLD%
Note that the wildcard character (%) in PRTLD% will match any B3 name beginning with the string PRTLD under
B1/B2 PORT/230k.
Refer to the man page for more information on script options
48.2 ImBaImportDirectory
ImBaImportDirectory is a UNIX tool that creates a script that runs ImBaImport for all of the files in a directory. The
generated script can be edited before it is run. If you choose, you can skip the edit and go directly to Import by
executing ImBaImportDirectory in “Run Mode.”
ImBaImport Directory uses the file names in the specified IDDUG directory to build an ImBaImport command. Each file
in the directory will cause a new ImBaImport command to be generated. The first 8 characters of the file name are
used as the job name and the output file name.
48.2.1 Executing ImBaImportDirectory

To create a script that will run ImBaImport for some or all of the files in a directory, use the following command:
unix> ImBaImportDirectory -u oracle_user -d $HOME/iddugs
To create a script that will run ImBaImport for files that match the pattern *.r30 and save the import script to a file called
import_iddugs in the current directory, use the following command:
unix> ImBaImportDirectory -u user -d $HOME/iddugs -o import_iddugs
-x *.r30
To create a script that imports all of the files in the $HOME/iddugs directory and then runs that script, use the following
command:
unix> ImBaImportDirectory -u user -d $HOME/iddugs -r Y

U0320 Revision: 1.0.0.0
IM Tools
48.3 ImBaLoadFilltab
ImBaLoadFilltab is a UNIX script that processes Filltab files. This script handles the deletion of old Filltab data and the
insertion of new Filltab data into the Oracle database.
48.3.1 Executing ImBaLoadFilltab

To load filltab files into the Oracle database, use the script as follows:
unix> ImBaLoadFilltab -u oracle_username -d filltab_directory_path
-o outfile
This script will access whatever Oracle database is identified by the ORACLE_SID environment variable.
48.4 ImIddugCompare
ImIddugCompare is a UNIX script that compares two IDDUG files. The checking routines produce several reports: a
report of only-in-iddug-file1 records, a report of only-in-iddug-file2 records, and a report that summarizes records
common to both IDDUG files that have different values in their non-keyed fields1.
48.4.1 Executing ImIddugCompare

ImIddugCompare can be called in two different ways:
unix> ImIddugCompare -u <user> -i1 <iddugfile1> -i2 <iddugfile2> -o
<outputfile>
or
unix> ImIddugCompare -u <user> -i1 <directory1> -i2 <directory2> -o

<outputdirectory>
The second way expects IDDUG files in the two directories, which have the same base name (the extension can be
different). The output files are written into the directory specified by the -o switch.
If the switch -d is set to ‘n’, then no comparison for the ‘DIGITL’ records is performed -- a feature which can increase
performance.
1 The following differences in the IDDUG image are not considered to be technological differences and are not
shown as differences in the report output:
o The attribute in one IDDUG file contains no value and its comparable attribute in the second iddug file
contains the default value.
o The attribute is a number and the subtraction of the two values is zero.

U0320 Revision: 1.0.0.0
IM Tools
48.5 ImCompare
ImCompare is a UNIX script that checks for existence of objects in Primitive Database (Oracle), i.e., PDB and on-line
operational database relations, i.e., SDB. It compares the key, number and name, wherever applicable, in the Base
Apps, RTDS, ICCP and Filltab hierarchy data. Thus, this script checks for orphans that exist in either database.
The script produces a report that shows the orphaned object printed on the side of database where it exists. Thus, if an
object ABC exists on the PDB side and not on the SDB side, then the object ABC will be printed on the PDB side in the
report.
The script compares the following Base Application tables:
b1, b2, b3, element.
The script compares the following RTDS/CFE tables:
Rtu, Rtu Scan Order, Rtu Scan Group, Rtu Scan SubGroup, Rtu Group, SAM, Cia, Channel, Line and Rtu
Scan 3X.
The script compares the following filltab files:
btypname, bltyde, cmch, elname, etypname, eltyde, elinname, infodef, inname, intyde, itypname, nede,
netyname, ngname, totyde, totyname.
The script compares the following ICCP tables:
IccpAccess, IccpAccessAcct, IccpAccessDevice, IccpAccessMsg, IccpGroup, IccpLink, IccpRemote, IccpTransfer,
IccpTransferAcct, IccpTransferdevice, IccpTransferMatrix, IccpTransferMsg
48.5.1 Executing ImCompare

To compare BaseApps hierarchy data in the PDB and SDB:
unix> ImCompare -u oracle_username -j oracle_jobname -a a

The comparison report is stored in file $HOME/ImCompare.rpt and the output is stored in file $HOME/ImCompare.out.
To compare RTDS hierarchy data in the PDB and SDB:
unix> ImCompare -u oracle_username -j oracle_jobname -a b
To compare ICCP hierarchy data in the POB and SOB:
UNIX> ImCompare -u oracle_username -j oracle_jobname -ai
To compare the filltab files in the PDB and SDB
unix> ImCompare -u oracle_username -j oracle_jobname -a f
Note that the options a, b and f for application parameter, a, in the script, ImCompare are mutually exclusive and
cannot be used together in any combination.

U0320 Revision: 1.0.0.0
IM Tools
48.5.2 Corrective Action

If there are no untransferred jobs in the PDM database and differences are detected by ImCompare, the following
processes should be used to get the PDM and the off-line operational database back in synch:
1. Objects in PDM, not in the off-line operational database: perform “full” transfers for the missing objects.
Note that if the ImCompare process is run while pending (untransferred) PDM jobs exist, it will be the correct
situation to have objects in the PDM that do not exist in the off-line operational database.
2. Objects in the off-line operational database, not in PDM: obtain or create (using ImRvIddug) complete IDDUG
files for the missing objects in the off-line operational database, import the IDDUG file(s) and run the update id
process ImBaRvUpdateIds to set the missing object internal numbers properly.
3. Objects with a mismatch of numbers between PDM and the off-line operational database: this should not
happen unless an error in parameterization has occurred: a typical situation would be if the off-line operational
database element number was changed in the Spectrum Power 3 parametrization, but the corresponding
change was not made in the PDM database. The fix in this case would be for the DBA to manually change the
PDM objects to match the Spectrum Power 3 parametrization.
48.6 ImOraDumpLoad
ImOraDumpLoad can, as its name implies, can dump both and load the Oracle database. The resulting dump might be
used as a simple backup (archive) of user data, or it might be used to carry “user” data forward following a software
upgrade. It uses Oracle’s Import and Export to dump and load user data and is faster than using the recommended
ImXxxExport/ImXxxImport method.
Before you begin, be sure you understand the Action options (-a). Reading the following caveats and instructions will
help to ensure success.
WA R N I N G
Entering data into the database when the triggers have been disabled is risky business. Be certain when using
this tool that you are not going to lose trigger-generated data.
Pay particular attention to any new fields or records that have been added as part of the software upgrade. If
new data is generated in full or in part by a trigger, it will not be populated during ImOraDumpLoad.
ImOraDumpLoad coordinates the disabling and enabling of constraints, the dropping and restoring of triggers (when
run with the "-a upgrade" mode), preserving sequence numbers and provides a way to verify the dump/load process.
To use ImOraDumpLoad during a software upgrade (Figure 49-1):
1. Run ImOraDumpLoad to dump the user data from Oracle using the -a upgrade option - note that if it is
certain that the PDM schema will be recreated immediately after the dump the, "-r n" switch may be
specified to speed up this script (see specific examples below).
2. Apply the software upgrade
3. Run ImOraDumpLoad to load user data. Be sure to set the -a switch to “upgrade”. If this is not set, the newly
created triggers will be overwritten by the contents of the dumped database.
4. Run global validation with the row level option.
Please note that filltab data is not dumped during an ImOraDumpLoad1. This data should always come from the filltab
files and should be loaded during the installation process.
1.A flag in the table TABLE_DEFINITION indicates which tables are filltab tables. These tables are not dumped during
an ImOraDumpLoad dump unless they are specified explicitly on the -t switch.

U0320 Revision: 1.0.0.0
IM Tools
(1) ImOraDumpLoad
Oracle Database DUMP

(2) Apply software Upgrade

ImOraSchema.plx
Oracle Database
(3) ImOraDumpLoad
(4) Global Validation
Figure 48-1: ImOraDumpLoad Process Flow
48.6.1 Setting up to run ImOraDumpLoad

Before you begin the dump/load process:
1. Verify that the ORACLE_SID environment variable is set to the database that you want to dump and/or load.
2. Verify that no other Oracle users are logged into the database. The dump and load process may disable
triggers and constraints -- a situation that can be disastrous to an unknowing user.
3. Verify that no outstanding jobs exist. Before using ImOraDumpLoad, all jobs in Oracle must be fully
processed (i.e., transferred and deleted or canceled).
4. Verify that an adequate amount of disk space exists. Be sure there is enough disk space to dump the Oracle
data. Use the following SELECT statement to give you an approximation of the amount of room needed to
dump the data.
sql> SELECT SUM(bytes/1024) k_bytes FROM user_segments WHERE
segment_type = ‘TABLE’;
K_BYTES

U0320 Revision: 1.0.0.0
IM Tools
----------
99896
If your Oracle storage parameters are set up for a large amount of data expansion, you will see that the
actual disk space needed to dump the tables is much less.
unix> du -k
16784 ./emp1_dump
5. Select a safe place to keep your dump files. Since the files created during an ImOraDumpLoad dump may
be used to load the data back into Oracle after a software upgrade, it is important that these files are not
accidentally deleted during the upgrade process.
48.6.2 Executing ImOraDumpLoad

To dump/load/verify data, use the script ImOraDumpLoad and choose your processing options by selecting the
appropriate parameters from this list.
You MUST log in as UNIX user ImOraDumpLoad before you can run this script.
unix> ImOraDumpLoad
-u Oracle User
-a Action: [backup], [load], [upgrade] [verify]
[-d] Dump Directory (created during dump)
default= ./Mar05.dmp
[-f] Dump Filename Prefix
default <ORACLE_SID>_<ORA_USER>
[-o] Log File
default= ./Mar05_emp1_user_action.log
[-t] Tables to process
default= all
[-r] If dumping, Restore Triggers
default= y
[-e] If loading, Enable Constraints and Triggers
default= y
[-m] Mode: [batch], [interactive]
default= interactive
WA R N I N G
Ensure that nobody is using the database while you perform the following steps.
1. Dump your data.
For a software upgrade, use the command: (note that the `-r' switch should only be set to `n' if the 'the
PDM schema will be recreated immediately after the dump, because this option will leave the Oracle
triggers disabled after running, which makes the PDM un-usable):
unix>ImOraDumpLoad -u oracle_user -a upgrade -d
dump_directory_name -r n
For a database backup, use the command:
unix>ImOraDumpLoad -u oracle_user -a backup -d
dump_directory_name
2. For Upgrade users only. Apply the software upgrade. This means the new software has been installed and
the PDM schema has been recreated by ImOraSchema.plx; a database in which the tables have been
created, control information has been loaded, but where no user data exists.

U0320 Revision: 1.0.0.0
IM Tools
3. To reload the data use the command

unix> ImOraDumpLoad -u oracle_user -a load -d
dump_directory_name -f <dump_file_prefix>
This step may involve more than one iteration. For instance, consider the following situation.
If a software upgrade involves a structure change to a particular user data table, ImOraDumpLoad may not
be able to enable the table’s constraints once the data has been loaded. These errors will be reported in the
ImOraDumpLoad output file. It is then up to you to modify the data so that the constraints can be enabled.
The EXCEPTIONS table can aid in finding the problem rows of data.
ImOraDumpLoad can be run multiple times in “verify” mode with the enable option until you receive no
errors. For example:
unix> ImOraDumpLoad -u oracle_user -a verify -d

dump_directory_name -f <dump_file_prefix> -e y
A software upgrade may also involve a structure change to a table such that the data for the table cannot be
loaded. It is up to you to follow the steps necessary to get the data loaded. ImOraDumpLoad can be run
multiple times in “load” mode for a particular table.
unix> ImOraDumpLoad -u oracle_user -a load -d
dump_directory_name -f <dump_file_prefix> -t “element”
4. Run global validation with the row level option.
48.6.3 Using ImOraDumpLoad to Dump and Load Other Databases

ImOraDumpLoad may be used to dump and load data from other Oracle databases. When determining whether or not
to use this tool to process non-EMP databases, consider the following points.
1. Since the TABLE_DEFINITION table may not exist in the database, ImOraDumpLoad will prompt you to
verify that ALL tables should be dumped when “all” tables is specified.
2. If the database is needed after an ImOraDumpLoad (dump) is performed and you must consider which
setting of the -a switch was used.
If the ‘-a upgrade’ option was used, then the dropped triggers must be loaded back into Oracle before
allowing users back on the system. The -r option may or may not work depending on where the source
of the trigger code is kept.
If the ‘-a backup’ option was used, then the existing triggers will be dumped along with the table data
and will be re-loaded with the table data: this may require you to re-create the table triggers (e.g. if the
triggers have changed after this data was dumped).
3. ImOraDumpLoad does not automatically know if there are tables whose source data comes from the
install process. Normally the TABLE_DEFINITION table contains this information about each table. So
when the data is reloaded, all of this user’s tables will be re-loaded from the dump - this may affect ‘filltab’
control tables if those values have changed after this data was dumped.
4. If TABLE_DEFINITION is not used, some other steps may have to be taken during the dump or load
process in order to coordinate the data coming from the install verses the data coming from the dump.

U0320 Revision: 1.0.0.0
IM Tools
48.7 IndentTrace
IndentTrace is a script that reads the output file created during a run of ImRptJobTrace.sql or a run of gtrace.sql and
indents the report lines based upon the level in the call stack.
48.7.1 Executing IndentTrace

Create a file using the Oracle command @gtrace. Then run the following command to put the indented listing in a file.
unix> IndentTrace [gtrace_output_file] > indented_datafile
Create a file using the Oracle command @ImRptJobTrace. Then run the following command to put the indented listing
in a file.
unix> IndentTrace -trim [report_file] > indented_datafile
Check for recursion in the output of a gtrace command.

unix> IndentTrace -r -s [gtrace_output_file] > /dev/null

U0320 Revision: 1.0.0.0
Creating Oracle Users
49 Creating Oracle Users

ImOraAddUser is a script used for the creation and control of additional Oracle users in the PDM schema of the EMP
Oracle database.
After ImOraSchema.plx creates the PDM schema (including Oracle user PRIME in that schema), ImOraAddUser may
be used to create additional Oracle users in the PDM schema that have access to user PRIME's objects. These
additional Oracle users are assigned to the proper temporary tablespace (TEMP) and default tablespace
(PRIME_DEFAULT). The new user is also assigned to the selected predefined Oracle role and profile. The new user
is granted quota on the selected schema.
Oracle roles and profiles are configured by ImOraSchema.plx during PDM schema creation. The PDM schema roles
and profiles may be found in directories:

$SPECPATH/src/schema/pdm/role
$SPECPATH/src/schema/pdm/profile
See the Primitive Database Maintenance User Guide - U0385 for more information on creating additional Oracle users.

U0320 Revision: 1.0.0.0
CFE on AIX
50 CFE on AIX
50.1 Modeling CFE Data
For Customers who have CFE (Communication Front End) in a PDM Master configuration data is maintained in PDM
using the SAM and RTDS hierarchies just as if it were RTDS. A flag called FRONT_END_TYPE in the PDM table
SCSI_ADAPTER_MODULE determines whether a given server is CFE or RTDS. If this flag is set to ’CFA’ then this
SAM is considered to be a CFE server. Additionally, any RTU connected to a line belonging to a CFE server is
considered to be a CFE RTU. It is possible to have a mix of CFE and RTDS servers in the system.
50.2 CFE Defaults IDDUG

Not all CFE attributes are available in PDM. Additionally, even for those which are available it isn’t always required for
the user to enter a value. Defaults for CFE attributes can be set globally using PDM Control Tables (see Chapter on
PDM Control Tables for CFE on AIX in U0385).
A second level of defaults is provided via the CFE default iddug. This iddug allows the user to set defaults at the
protocol level. This iddug can be found in directory:
$SPECPATH/src/rdbms/ImEs/cfe_default_iddug3.0.
To load this IDDUG, run the following script:
ImEsCfeImport -u prime -j <job_name>
-i $SPECPATH/src/rdbms/ImEs/cfe_default_iddug3.0
There is no change_log involved with running this script; it first truncates the tables it writes to and then updates them
from the IDDUG. After running this script the job should be checked for errors by running ImRpt:
ImRpt -u prime -j <job_name> -m 13
If there are no errors listed in the ImRptMsg.out file then the job can be cancelled and the user can proceed. If errors
are found, then the cfe_defaults_iddug3.0 file needs to be corrected and the import script re-run.
50.3 ImArsExportBulk
On initial set-up for the CFE on AIX, the usre needs to first import the CFE default iddug. Next PDM job(s) need to be
created to model the CFE data. Once these things have been accomplished the user would next run script
ImAsrExportBulk. This script reads through all of the CFE data modeled in PDM and produces a bulk ASR change log
file. ASR is short for Application Suite Repository, which describes a type of file in PowerCC. The bulk ASR change log
consists of a binary file of linked lists. Each list links PowerCC data types which model CFE data.
After Running ImAsrExportBulk the user can attempt to INITSOS the CFEP and CFE server types. Part of the INITSOS
process involves copying the Bulk ASR change log from the ADM and loading it into the database used by the CFE
applications on the CFE servers.
The only other time it sould be necessary for the user to manually run ImAsrExportBulk is if there is a change to the
CFE data model schema.
50.4 ImAsrExportCfe and Job Transfer

Once the system has been initially brought up following the ImAsrExportBulk run, then any subsequent changes to
CFE data will be made via incremental ASR change logs. At job transfer time a check is made to determine if the job
contains CFE changes. If it does, then the ImBaJobTransfer script will call ImAsrExportCfe to produce an incremental
ASR change log for the job. When the job is activated this change log is copied to the CFE servers and applied to the
database there. The ImAsrExportCfe script is called exclusively from ImBaJobTransfer; there should never be a
reason for the user to invoke it manually.

U0320 Revision: 1.0.0.0
CFE on AIX
50.5 Skipping Incremental ASR Generation

Occaisionally projects will need to perform some type of global change, say making a modification to every RTU in the
system. ImAsrExportCfe can take a long time to complete if it has to examine every RTU. For these rare cases the
user can run ImBaJobTransfer with the –x option set to ‘Y’. This causes ImBaJobTransfer to skip running
ImAsrExportCfe to produce an incremental ASR Change Log. The trade-off is the user must then immediately run
ImAsrExportBulk after the job is activated to create a Bulk ASR Change Log containing those global changes. Then the
CFE servers will all need to be INITSOSed.

U0320 Revision: 1.0.0.0
Putting It All Together - A Process Flow
51 Putting It All Together - A Process Flow

All of the preceding chapters address the individual steps in the process of building and maintaining the PDM. This
chapter suggests how to put all of those pieces together into a process flow.
Table 51-1: Process Flow
Step Process Description For More Information,
See
1 Prepare the IDDUG file. “Division of BA Data in Multiple IDDUG Files” on page 37
“Communications Import” on page 44
“Load Shed Import” on page 45

“Communications Export” on page 55
“Load Shed Export” on page 56
“Underfrequency Load Shed Export” on page 57
“Voltage Reduction Export” on page 58
“Base Applications Reverse Transfer” on page 100
2 Execute import. “Base Applications Import” on page 37

“Load Shed Import” on page 45
“Underfrequency Load Shed Import” on page 46

“Voltage Reduction Import” on page 47
3 Report and view errors using ImRptMsg. “Error Message Reports” on page 83
4 Report and view job trace using @gtrace or “Job Trace” on page 81
ImRptJobTrace. “IndentTrace” on page 113
5 If errors are found:
5a Correct the data in the IDDUG file or use ”Primitive Database Forms” on page 60
Oracle Forms to correct the Primitive
Database,
If IDDUG was corrected, cancel the job in “Job Cancel” on page 98

the Primitive Database and return to step 2,
5b otherwise continue.
6 Execute global validation “Global Validation” on page 61
7 Report and view errors Using ImRptMsg “Error Message Reports” on page 83

U0320 Revision: 1.0.0.0

See
ImRptJobTrace.
9 If errors are found
9a Cancel the job in the Primitive Database, “Job Cancel” on page 98
9b Correct the data in the IDDUG file or use “Primitive Database Forms” on page 60
Database,
9c If IDDUG was corrected, return to Step 2,

otherwise continue.
10 Execute Job Transfer. “Execute Job Transfer” on page 89

“Full Transfer” on page 103
11 Report and view errors using ImRptMsg. “Error Message Reports” on page 83
ImRptJobTrace.
13 View the console log for error messages.

14a Cancel the DBA job, “Cancel the DBA Job” on page 92
14b Cancel the job in the Primitive Database, “Job Cancel” on page 98
14c Correct the data in the IDDUG file or use “Primitive Database Forms” on page 60
Database,
14d If IDDUG was corrected, return to Step 2,

otherwise continue.
15 Activate the DBA job. “Activate the DBA Job” on page 93
15a Activate to Remote Copies “Activate All” on page 7
16 View the console log for activation error messages

U0320 Revision: 1.0.0.0

See
. 17aa Undo from Remote Copies “Undo All” on page 8
17a Undo the DBA job, “Undo the DBA Job” on page 93
17b Correct the errors,

17c Return to step 15.
18 Delete the job from Remote Copies DBA and

primitive.
18a Delete from Remote Copies job “Delete Job” on page 8
18b Delete job from DBA “Delete the DBA Job” on page 93
18c Delete the Primitive Database “Job Delete” on page 97


U0320 Revision: 1.0.0.0

U0320

Hochgeladen von

Dokumentinformationen

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

U0320

Hochgeladen von

Copyright:

Verfügbare Formate

SIEMENS

Configuration ID: U0320

Document Revision: 1.0.0.0

Author: _____________________ ______________

Reviewer: _____________________ ______________

Int. Approval: _____________________ ______________

Spectrum Power 3 PDM Interface, User Guide

2.7 Job and Application Log Report ............................................................................ 4

3.4 Abandoning a Copy (ImCmAbandon) ................................................................... 13

Spectrum Power 3 PDM Interface, User Guide Page iv

6.6 Underfrequency Load Shed Job Interlocks ............................................................ 29

7.4 man pages ...................................................................................................... 32

10.8 RTDS Hierarchy and Auto Insert of Station RTDS components.................................. 39

Spectrum Power 3 PDM Interface, User Guide Page v

16.2 AA Import ....................................................................................................... 50

18 Communications Export .......................................................................55

23.1 Executing Forms .............................................................................................. 60

Spectrum Power 3 PDM Interface, User Guide Page vi

25.1 Cascade Delete ................................................................................................ 66

27 PDM Interface Reports .........................................................................72

37.1 Error Message Reports ...................................................................................... 83

41.1.1 Transfer AGC Relations ....................................................................................... 95

45 Base Applications Reverse Transfer.....................................................100

48.5 ImCompare.................................................................................................... 108

Spectrum Power 3 PDM Interface, User Guide Page viii

Spectrum Power 3 PDM Interface, User Guide Page ix

Spectrum Power 3 PDM Interface, User Guide Page 1

2 Job Management Overview

2.2 Viewing the Current Jobs

star1 READY PRIME PRIME

Spectrum Power 3 PDM Interface, User Guide Page 2

2.4 Viewing the Tasks of a Job

star1 import_bulk PRIME

2.5 Job and Task Report

Spectrum Power 3 PDM Interface, User Guide Page 3

2.6 Application Log

2.7 Job and Application Log Report

Spectrum Power 3 PDM Interface, User Guide Page 4

Spectrum Power 3 PDM Interface, User Guide Page 5

3.1 PDM Initiated Activation

Spectrum Power 3 PDM Interface, User Guide Page 6

3.2 Forms Interface for PDM Initiated Activation

3.2.1 Remote Activation Form

PDM Backup Copy PDM_SEND_REQ

3.2.2 Activate All

Spectrum Power 3 PDM Interface, User Guide Page 7

3.2.3 Undo All

3.2.4 Delete Job

Spectrum Power 3 PDM Interface, User Guide Page 9

3.3 Script Interface for PDM Initiated Activation

--> EA_ACTIVATION_REQ/EA_NOT_NEEDED (for EA changes)

Spectrum Power 3 PDM Interface, User Guide Page 10

The individual activation script for PDM Copy is:

Spectrum Power 3 PDM Interface, User Guide Page 11

unix> ImEaJobMgmt -u {Oracle username} -j {job_name} -f U -h

unix> ImCmPDMReset -u {Oracle username} -j {job_name} -h host_name}

the job delete must be executed in the following order:

Spectrum Power 3 PDM Interface, User Guide Page 12

3.4 Abandoning a Copy (ImCmAbandon)

appropriate synchronization procedure detailed later in the chapter.

3.5 Synchronizing the Copies with the Main (ImCmResynch)

3.5.1 Synchronizing the PDM Copy with the Main

Spectrum Power 3 PDM Interface, User Guide Page 13

host_name link status db_type

Author: _______

Reviewer: _______

Int. Approval: _______