Anda di halaman 1dari 1024

Automation Engine

User Guide

Automic Software GmbH

iiCopyright

Copyright
Automic and the Automic logo are trademarks owned by Automic Software GmbH (Automic). All
such trademarks can be used by permission only and are subject to the written license terms. This
software/computer program is proprietary and confidential to Automic Software and is only available
for access and use under approved written license terms.
This software/computer program is further protected by copyright laws, international treaties and
other domestic and international laws and any unauthorized access or use gives rise to civil and
criminal penalties. Unauthorized copying or other reproduction of any form (in whole or in part),
disassembly, decompilation, reverse engineering, modification, and development of any derivative
works are all strictly prohibited, and any party or person engaging in such will be prosecuted by
Automic.
No liability is accepted for any changes, mistakes, printing or production errors. Reproduction in
whole or in part without permission is prohibited.
Copyright Automic Software GmbH. All rights reserved.

Automation Engine

iii

Contents
1 Getting Started Guide

1.1 Welcome!

1.2 Preliminary Checklist

1.3 First Logon to the UserInterface

Lesson 1
1.4 Exploring the User Interface
Lesson 2
1.5 Creating an Object
Lesson 3
1.6 Executing an Object

2
3
3
4
4
7

Lesson 4

Exercise

1.7 Statistics and Reports

Lesson 5

Exercise

10

1.8 FileTransfers

10

Lesson 6

10

Exercises

12

1.9 Automation via Schedules

12

Lesson 7

12

Exercise

15

1.10 Calendar Conditions

15

Lesson 8

15

Exercise

19

1.11 Using Workflow Objects

19

Lesson 9

19

Exercise

21

1.12 Information through Notification

21

Lesson 10

21

Exercise

26

1.13 Using Groups

27

Lesson 11

27
28

iv

Contents

1.14 Forecasts

28

Lesson 12

28

Exercise

30

1.15 Navigation in the UserInterface

31

Lesson 13

31

Exercise

34

1.16 Personal Settings

34

Lesson 14

34

Exercise

35

1.17 Last but not Least


2 UserInterface

35
36

2.1 Introduction

36

2.2 Login

36

Description

37

2.3 Using Desktop Modes

38

2.4 Buttons in the Toolbar of the UserInterface

39

Standard Commands

39

Commands for Handling Objects

41

Special Commands of the Activity Window

42

2.5 Keyboard Shortcuts

43

General

43

Menu bar

44

Desktop

44

Objects

44

2.6 Settings of the UserInterface

45

2.7 UC4 Explorer

55

2.7.1 UC4 Explorer

55

General Information

55

Folder

56

Objects

57

2.7.2 Context Menu of the UC4 Explorer

60

2.7.3 UC4 Recycle Bin

61

2.7.4 UC4 Transport Case

62

2.7.5 Version Management for Objects

64

Automation Engine

2.7.6 Favorites

67

2.7.7 Recent Objects

67

2.8 Search

68

2.8.1 Search

68

Objects

68

Date

69

Further Options

70

2.8.2 Searching for Object Usage

72

2.8.3 Searching and Replacing Texts

74

2.9 Activity Window


2.9.1 Activity Window
Activity Window Views
2.9.2 Activities Window Selection

76
76
78
79

Objects

79

Status

80

Host

81

Archive Keys

83

2.9.3 Context Menu of the Activity Window


2.10 Comments in Tasks
Script

84
87
89

2.11 Message Window

89

2.12 Detail Window

91

2.12.1 Detail Window

91

Details in the Editing and Monitor View of Objects

92

Details in the Activity Window

93

Details in the Statistical Overview

93

Details in the Forecast Window

93

2.12.2 Detail Window Contents


2.13 Forecasts

93
97

2.13.1 Forecast

97

Usage

97

Forecast Window

98

List View

99

Script Elements

100

vi

Contents

2.13.2 Auto Forecast

100

Preparation Work Required by the UC4 Administrator

101

Use

101

Restrictions

102

2.14 System Overview

103

2.14.1 System Overview

103

2.14.2 Usage

104

2.14.3 Clients

105

2.14.4 Automation Engine/Server

107

Context Menu

108

Properties

109

Usage

113

Workload - message analysis

114

Workload - message statistics

115

2.14.5 Agents

116

Context menu

117

Properties

119

2.14.6 AgentGroups

123

Context menu

123

Properties

124

Simulation view

125

2.14.7 Queues
Context menu
2.14.8 Agent Assignment

125
126
127

Description

128

Context menu

128

2.14.9 Users

128

2.14.10

128

User States

129

Context menu

129

2.14.11 Messages

130

2.14.12 Database

132

2.14.13 License

133

License abbreviation

134

Automation Engine

2.14.14 ILM

vii

136

Partition tab

137

History tab

138

2.14.15 Cache

138

2.14.16 Password Exit

140

2.14.17 Quarantine

140

Reaction to invalid messages

141

Releasing messages

142

Context menu

142

2.15 Quick Search


2.15.1 Quick Access

143
143

Client-wide quick search

143

Quick Access

144

2.15.2 Quick Search Function for Lists

145

General information

145

Wildcards

146

Pushbuttons of the Quick Search bar

146

2.15.3 Quick Search / Quick Access in Objects

147

Quick Search

147

Quick Access

149

2.15.4 Quick Search in Workflows

151

Pushbuttons of the Quick Search bar

151

Wildcards

152

Connect to

153

2.16 Importing and Exporting Objects


3 Objects
3.1 Introduction
3.1.1 UC4's Object Orientation

153
156
156
156

Opening Objects

156

3.1.2 Object Classes

157

Executable Objects

157

Active Objects

157

Passive Objects

158

System Objects

158

viii

Contents

3.1.3 Object Types


Other Object Types
3.1.4 Variables in UC4
3.2 Alphabetical Listing

159
161
161
163

3.2.1 Agent

163

Agent

163

Header tab

163

Description
Attributes Tab
Description
Agent Tab
Description
Authorizations tab

164
164
164
165
166
166

Description

167

Documentation Tabs

167

Structured Documentation

168

Agent Variables

170

3.2.2 AgentGroup

174

AgentGroup

174

Header tab

175

Description

175

AgentGroup Tab

175

Description

176

Authorizations tab

178

Description

179

Documentation Tabs

179

Structured Documentation

180

AgentGroup Monitor

182

AgentGroup Attributes

184

AgentGroups

184

Creation

185

Mode

185

View

186

Execution

186

Automation Engine

ix

3.2.3 Agent/Client Assignment

186

Agent/Client Assignment

186

Simulation
Header tab
Description
Filter Tab
Description
Authorizations tab

187
188
188
188
189
190

Description

190

Documentation Tabs

191

Structured Documentation

191

3.2.4 Calendar

193

Calendar

193

Header Tab

194

Description
Calendar Tab
Description
Types of Calendar Keywords

195
196
196
199

Static

199

Yearly

202

Monthly

204

Weekly

206

Group

207

Roll

209

Documentation Tabs
Structured Documentation

211
211

3.2.5 Client

213

Client

213

System Client 0000

214

Local Clients 0001 to 9999

214

Header tab
Description

214
215

Attributes Tab

215

Contents

216

Contents

Settings Tab

216

Documentation Tabs

217

Structured Documentation

218

3.2.6 Cockpit

219

Cockpit

219

Creating Cockpits

220

Procedure
Header tab
Description
Sync Tab

220
220
221
222

Description

223

Cockpit - Cockpit Tab

223

Creating and positioning display elements

224

Defining Properties

225

Display of Elements

225

Function of Elements

225

Data Source of the Elements

226

Variables & Prompts Tab

226

Runtime tab

229

Description

229

Comments

231

Process Tab

232

Description

232

Documentation Tabs

233

Structured Documentation

233

Cockpit - Monitor

235

Cockpit Attributes

236

3.2.7 CodeTable

238

CodeTable

238

Description
Header tab
Description
Code Tab
Description

238
239
240
240
240

Automation Engine

Documentation Tabs
Structured Documentation
CodeTable - Usage

xi

241
242
244

Diagram of Data Traffic

245

UC4 Automation Engine

245

Agent

246

Agent - Job Execution

246

Agent - FileTransfer

247

3.2.8 Connection

247

Connection

247

Header tab

247

Description
Attributes Tab
Description
Remote Function Call Tab

248
248
249
249

General tab

249

Secure Network Connection tab

251

Interfaces tab

252

Internet Tab
Description

255
255

DB Tab

256

Documentation Tabs

257

Structured Documentation

258

3.2.9 Dashboard

260

Dashboard

260

Header tab

260

Description

261

Documentation Tabs

261

Structured Documentation
3.2.10 Documentation

262
264

Documentation

264

Header tab

264

Description

265

Documentation Tabs

265

xii

Contents

Structured Documentation
3.2.11 Event

266
268

Event

268

Header tab

269

Description
Sync Tab

270
270

Description

271

Event - Calendar Tab

272

Description

272

Attributes Tab
Description
Event Tab

273
274
275

Description

276

File System Tab

277

Description

277

Comments

279

Console Tab

280

BS2000

281

Description

281

Comments

282

z/OS

282

Description

282

Comments

283

OS/400

283

Description

283

Comments

284

SAP

284

ABAP Event History

285

Description

285

Comments

285

Java Event History

286

Description

286

Comments

287

XI Communication Channels

287

Automation Engine

xiii

Description

287

Comments

288

Windows

288

Description

289

Comments

290

Database Tab

290

SQL query

291

Statistical value

293

Variable object

293

Runtime tab

293

Description

294

Comments

296

Variables & Prompts Tab

297

Rollback Tab

299

Process Tab

301

Description
! Process Tab

301
302

Description

302

Documentation Tabs

303

Structured Documentation
Event - Execution
Type-Specific Features
Event - Restart
Type-Specific Features
Event Attributes

303
305
305
306
306
306

Attributes for all Event Types

306

Attributes for the Event Type "Time Event"

310

Attributes for the Event Type "File System"

310

Attribute for the Event Type "Database"

313

Attributes for Event Type "Console"

316

3.2.12 FileTransfer

318

FileTransfer

318

Creating FileTransfers

318

Procedure

318

xiv

Contents

Header tab
Description
Sync Tab
Description

318
319
320
321

Attributes Tab

321

Contents

322

FileTransfer Tab

324

Description

325

Comments

328

Platform-Specific Features

328

Runtime tab

328

Description

329

Comments

331

Variables & Prompts Tab

332

Rollback Tab

334

Process Tab

338

Description
Output ScanTab
Description
Post-Process Tab

338
339
340
341

Description

341

Documentation Tabs

342

Structured Documentation

343

Partially Qualified FileTransfer

344

Old FileTransfer Protocol

344

New FileTransfer Protocol

345

FileTransfer - Execution

347

Object-Type specific Features

347

Transferring Files

348

AgentGroups

348

Compression

349

End Status

349

UNIX and MPE

349

VMS

350

Automation Engine

FileTransfer - Restarts
Object-Type specific Features
FileTransfer - Statistics/Report

xv

350
350
351

Structure

351

For example

352

FileTransfer Attributes

352

3.2.13 Filter

361

Filter

361

Header tab

362

Description
Filter Tab

362
362

Description

363

Documentation Tabs

365

Structured Documentation
3.2.14 Group

366
367

Group

367

Creating Groups

367

Procedure
Header tab
Description
Sync Tab

368
368
369
370

Description

371

Group - Attributes Tab

371

Description

372

Runtime tab

372

Description

373

Comments

375

Variables & Prompts Tab

376

Rollback Tab

378

Group - Process Tab

380

Description

380

Documentation Tabs

380

Structured Documentation
Group - Execution

381
383

xvi

Contents

Object-type-specific Features

383

Activation of an Application Order

384

Activation of Application during a Queue

384

Restart
Object-type-specific Features

385
385

Group - Monitor

385

Group Attributes

386

3.2.15 Include

389

Include

389

Header tab

389

Description
Process Tab

389
390

Description

390

Documentation Tabs

391

Structured Documentation
3.2.16 Job

391
393

Job

393

Creating Jobs - Basics

393

Procedure
Creating Jobs - Details

394
394

BS2000

394

GCOS8

395

JMX

395

MPE

395

NSK

395

Oracle Applications

395

z/OS

395

OS/400

396

PeopleSoft

396

SAP

396

Siebel

396

SQL

396

UNIX

397

VMS

397

Automation Engine

xvii

Windows

397

Header tab

397

Description

398

Output Tab

399

Sync Tab

400

Description
Attributes Tab

401
402

Description

402

Host Attributes Tabs

405

Host Attributes Tab

405

BS2000

405

GCOS8

407

JMX

408

MPE

411

NSK

412

Oracle Applications

413

OS/400

414

PeopleSoft

416

RA

417

SAP

419

Siebel

422

SQL

423

UNIX

425

VMS

427

Windows

428

z/OS

430

Runtime tab

434

Description

434

Comments

437

Step List for z/OS Jobs

437

Variables & Prompts Tab

439

Rollback Tab

441

Output ScanTab

445

Description

446

xviii

Contents

Form Tabs

447

Form tab (JMX)

447

Form Tab (PeopleSoft)

449

Form Tab (SAP)

452

Form tab (SQL)

455

Script Tabs

457

Pre Process Tab

457

Process Tab

459

Post-Process Tab

460

Child Post-Process tab(SAP)

461

Documentation Tabs
Structured Documentation
Job - Execution

462
463
465

Object-Type specific Features

465

Database

465

MPE

466

UNIX

466

Job - Include

466

Generated Jobs

468

Job - Statistics/Report

469

Object-type-specific Features
Job Report - PeopleSoft
PeopleSoft Process Log File
Job Attributes

469
470
470
471

Job Attributes

471

BS2000

478

GCOS8

480

JMX

481

MPE

483

NSK

485

Oracle Applications

487

z/OS

488

OS/400

492

PeopleSoft

494

Automation Engine

xix

SAP

495

Siebel

500

SQL

503

UNIX

505

VMS

506

Windows

508

3.2.17 Login

510

Login

510

Creating Login Objects

510

Procedure
Header tab
Description
Login Tab

511
511
511
512

Description

512

Comments

513

Login Information Format

513

Platform-specific Features

514

Documentation Tabs
Structured Documentation
3.2.18 Notification
Notification
Notification Monitor
Creating Notifications

514
515
517
517
518
518

Selecting a Template

518

Which Tabs to Use

519

Procedure

520

Header tab
Description
Sync Tab
Description
Attributes Tab
Description
Notification tab
Description

520
520
521
522
523
523
525
526

xx

Contents

Recipients tab
Description
Runtime tab

527
528
529

Description

529

Comments

531

Variables & Prompts Tab

532

Rollback Tab

534

ProcessTab

536

Description

536

Documentation Tabs

537

Structured Documentation
Notification - Execution
Object-Type-Specific Features
Notification - Monitor

537
539
539
541

Message

543

Request

544

Alert

545

Notification - Object Type ALARM

546

General information

546

Script

547

Notification Attributes
3.2.19 PromptSet

549
553

PromptSet

553

Header tab

553

Description
Designer Tab

554
554

Control Elements

555

Element Properties

559

Table Overview - Elements and Properties

572

Documentation Tabs
Structured Documentation
PromptSet - Activation

573
574
575

Prompt

576

Input Assistant

577

Automation Engine

xxi

Displayed default values

577

Input restrictions

578

Modifications at runtime

578

Restart behavior

578

Dynamic PromptSet Dialogs


Examples:
3.2.20 Queue

579
580
582

Queue

582

Header tab

582

Description
Attributes Tab

583
583

Description

584

Documentation Tabs

586

Structured Documentation
Consideration of Estimated Runtime for Calculation

587
589

Example 1

590

Example 2

591

Using Queue Objects

592

Queue Assignment

592

Start /Stop

593

Exceptions

594

Queue - Modifications

594

Edit

595

Modify

595

MODIFY_SYSTEM

595

Ignore Queue limit

595

Client Queue

596

3.2.21 RA Solution

596

RA Solution

596

Header tab

596

Description

597

Documentation Tabs

597

Structured Documentation
3.2.22 RemoteTaskManager

598
600

xxii

Contents

RemoteTaskManager

600

Header tab

601

Description
Sync Tab
Description
Attributes Tab
Description
PeopleSoft and SAP Tab

601
602
603
603
604
606

PeopleSoft Processes

606

All SAP Jobs

607

Intercepted SAP Jobs

608

Java Scheduler Jobs in SAP

609

Process Chains in SAP

610

Runtime tab

611

Description

612

Comments

614

Variables & Prompts Tab

614

Rollback Tab

617

Process Tab

618

Description
Output ScanTab
Description
Post-Process Tab
Description

619
619
620
621
622

Child Post-Process Tab

623

Documentation Tabs

623

Structured Documentation
RemoteTaskManager - Execution

624
626

Displaying and tracing non-UC4 operations

626

Controlling the queue

627

Stop/Go

627

Canceling

627

Ending

628

RemoteTaskManager Attributes

628

Automation Engine

3.2.23 Schedule

xxiii

632

Schedule

632

Creating Schedules

633

Procedure

633

Header tab
Description
Sync Tab
Description
Attributes Tab
Description
Schedule Tab

633
633
634
635
636
636
638

Schedule Tab

638

Properties of Objects

640

Properties of Objects

640

Start-Time Tab

641

Variables & Prompts Tab

643

Calendar Tab

644

Runtime tab

646

Result Tab

648

Runtime tab

650

Description

651

Comments

653

Variables & Prompts Tab

653

Process Tab

656

Description

656

Documentation Tabs

657

Structured Documentation
Schedule - Execution

657
659

Object-Type specific Features

659

Termination or Period Turnaround of a Schedule that includes active tasks

660

Schedule - Monitor

661

Schedule Monitor during Execution

663

Schedule Monitor after Execution

664

Schedule Attributes

665

xxiv

Contents

Modifications in Active Schedules

668

Schedule object

669

Schedule monitor

669

3.2.24 Script

670

Script

670

Header tab

670

Description
Sync Tab
Description
Attributes Tab
Description
Runtime tab

671
672
673
673
674
675

Description

676

Comments

678

Variables & Prompts Tab

678

Rollback Tab

681

Process Tab

682

Description

683

Documentation Tabs

683

Structured Documentation
Script - Execution
Object-Type specific Features
Script Attributes

684
686
686
687

3.2.25 Server

690

Header tab

690

Description
Attributes Tab

690
690

Description

691

Documentation Tabs

692

Structured Documentation
3.2.26 StyleSheet

692
694

StyleSheet

694

Header tab

695

Description

695

Automation Engine

xxv

StyleSheet Tab

695

Documentation Tabs

696

Structured Documentation
3.2.27 Sync

697
698

Sync

698

Header tab

699

Description
Attributes Tab
Description
Sync Tab

699
700
700
701

Description

701

Documentation Tabs

702

Structured Documentation

702

Sync - Monitor

704

Using Sync Objects

706

Synchronizing Workflows Using Sync Objects

711

3.2.28 TimeZone

715

TimeZone

715

Header tab

715

Description
Attributes Tab

716
716

Description

717

Documentation Tabs

719

Structured Documentation
3.2.29 User
User

720
722
722

Users in System Client 0000

723

Users in Local Clients 0001 to 9999

723

Header tab
Description
User Tab
Description
Authorizations tab
Description

723
723
724
724
726
727

xxvi

Contents

Privileges Tab

732

Description

733

UserGroups Tab

737

Description

737

Documentation Tabs

738

Structured Documentation
3.2.30 UserGroup
UserGroup
Description
Header tab
Description
UserGroup Tab
Description
Authorizations tab
Description
Privileges Tab

738
740
740
740
741
741
742
742
743
743
749

Description

750

Documentation Tabs

753

Structured Documentation
3.2.31 Variable

754
756

Variable

756

Creating Variables

757

Procedure

757

Header tab
Description
Attributes Tab

758
758
759

Description

759

Scope Examples

765

Variable Objects in System Client 0000

765

Variable Tab
General Information

767
767

Static

768

SQL

769

SQL SECURE

771

Automation Engine

xxvii

SQL - internal

775

SQL - internal SECURE

778

Multi

780

Filelist

782

Backend

783

Documentation Tabs
Structured Documentation
Using Variable Objects

788
788
790

Direct usage in objects

791

Resolving dynamic variables

791

Attributes for predefined variables

792

3.2.32 Workflow

797

Workflow

797

Creating Workflows

798

Procedure

798

Header tab
Description
Sync Tab
Description
Attributes Tab
Description
Workflow tab

798
799
800
801
801
802
804

Workflow tab

804

Properties of Objects

811

Object Properties

811

General Tab

811

Earliest tab

814

Preconditions Tab

816

Dependencies tab

825

Variables & Prompts Tab

828

Calendar Tab

834

Runtime tab

835

Postconditions tab

837

Solution Tab

847

xxviii

Contents

External Dependency Tab


Logic tab
IF Workflows

847
852
852

General Information

853

Defining IF Workflows

853

Processing IF Workflows

860

ForEach Workflows

860

General Information

861

Defining ForEach Workflows

861

Processing IF Workflows

864

Runtime tab

864

Description

865

Comments

867

Variables & Prompts Tab

868

Rollback Tab

870

Deployment Tab

872

Process Tab

873

Description

874

Documentation Tabs

874

Structured Documentation
External Workflow Dependencies

874
876

External Workflow Dependencies

876

Lead Time Satisfaction for External Dependencies

879

Re-using AgentGroup Calculation


Example

881
882

Special Workflow Types

883

Workflow - Execution

884

Object-type-specific Features
Workflow - Restart
Object-type-specific Features
Workflow Monitor

884
885
885
885

Display

885

Modifications

887

After the Execution

890

Automation Engine

xxix

Workflow Attributes

891

Modifications to Active Workflows

895

General

895

Procedure

895

Important notes

897

Script

897

Processing a Rollback

897

Backup

898

Rollback

898

Rollback of Workflows

900

Specific Rollback Commands

901

3.3 Working with Objects


3.3.1 Executing Activatable Objects
Execution with Options

901
901
901

Once

902

Recurring

904

Frequency tab

904

Time-Frame tab

906

Days tab

908

Range tab

909

Restart
Scheduling Recurring Tasks

910
912

Display

912

Changing recurring Settings

913

Procedure

913

Restarting Executable Objects

914

Display

914

Procedure

915

Script

916

Status Symbols of Tasks

916

Archive Keys

917

Object Properties

917

General

917

Authorizations

918

xxx

Contents

UC_CAUSE* ReadBuffer Variables


3.3.2 Reading and Modifying Attributes
Attributes
UC4.DBChange
Attribute Dialog
3.3.3 Reports

919
920
920
921
921
923

About Reports

923

Report Types

925

Registered Job Output

925

Report for Executable Objects

928

Special Reports for SAP Jobs

929

UC4 and XBP 2.0

929

XBP 3.0

929

Report for Servers and Agents

930

Client Reports

931

Extended Reports

932

About Extended Reports

932

Extended Report for Script

932

Extended Report for JCL

933

Extended Report for Object Access

934

3.3.4 Return Codes


System Return Codes of Executable Objects

935
935

System return codes and Assigned Task States in the Workflow / Schedule

935

System return codes and Assigned Task States During Execution

937

Manual Modification of Task States

941

User Return Codes of Executable Objects

942

Defining User Return Codes

942

Setting User Return Codes

943

Script

943

Windows

943

UNIX

943

BS2000

943

3.3.5 Statistics

944

About Statistics

944

Automation Engine

Statistics of Executable Objects


Statistics Overview

xxxi

945
945
945

Statistics of Child Objects and Parent Objects

946

Statistics for Servers and Agents

947

User and Client Statistics

948

Selective Statistics

949

General

950

Period

950

Objects

951

Status/RunID

952

Archive Keys

953

Host

954

Host

955

3.3.6 Pedefined Variables

956

General Information

956

Syntax
Using Predefined Variables

957
957

Script

957

Attributes

958

Variable Picker

959

List of Predefined Variables for System and Object Values

963

UC4 System

963

Object

964

Return codes of script functions

964

Attributes

968

Date and Time Formats


Glossary

977
981

.1 A

981

.2 B

982

.3 C

982

.4 D

982

.5 E

983

.6 F

983

xxxii

Contents

.7 G

984

.8 H

984

.9 I

984

.10 J

984

.11 K

985

.12 L

985

.13 M

985

.14 N

985

.15 O

986

.16 P

986

.17 Q

987

.18 R

987

.19 S

989

.20 T

989

.21 U

990

.22 V

992

.23 W

992

.24 X

992

Automation Engine

1 Getting Started Guide


1.1 Welcome!
The Automation Engine offers a wide range of functions! Are you eager to quench your thirst for
knowledge about the efficient use of all the provided functions? We have put great effort into the
development of this introductory chapter. It intends to quickly familiarize you with the basics of
UC4 and enables you to deal with the fine tunings and settings of the Automation Engine.
This chapter serves to introduce you to the Automation Engine through lessons in which the
functions of the UserInterface are explained step by step. Practice working with the Automation
Engine by engaging in the examples. From lesson 4 onwards ("Executing an Object"), additional
exercises are included at the end of each document. They can be used to apply the new contents
and learn even more about additional functionality aspects. The completion of the whole
introductory chapter prepares you very well for more complex functionalities.
The UC4 Documentation is at your disposal. Just click the F1 key and the documentation opens
at exactly the page that contains the description for the currently selected window.
Enjoy exploring the Automation Engine!

1.2 Preliminary Checklist


To be able to participate in the following examples and practices, your UC4 system must fulfill
some basic requirements.
Present this list to your UC4 administrator. It communicates the specifications that must be
provided.
A UC4 system with the following minimum installations:
l

At least 1 UC4 Automation Engine (consisting of 1 work process and 1 communication


process)
At least 2 agents (a Windows and a UNIX computer are used in the examples. You can use
any operating system that is supported by the Automation Engine).

The UC4 system requires:


l
l
l

At least 1 client (in addition to the system client 0000)


Login objects for the installed agents
User objects for logging on to the UC4 system

Your computer requires:


l
l
l

A UserInterface
Some files in order to test file transfers in UC4
Your personal login data for the UC4 system

Chapter1 Getting Started Guide

Have you met all the above requirements? Now you're ready to go!

1.3 First Logon to the UserInterface


Aim:
- Logging on to the UserInterface
- Changing the password
Lesson 1
Our very first step is to log on to the Automation Engine. This is done via the UserInterface - the
user interface for managing your UC4 system. Start the UserInterface as shown below:
l
l

Under Windows: Call Start -> Programs -> UC4 -> UC4.Dialog.
Under UNIX: Call the file ucdj.sh.

The following login mask opens:

Ask your UC4 administrator for the appropriate login data.


1. Select the UC4 system to which you want to connect.
2. Enter the client, your name, department and password.
3. The user interface of the UserInterface can be displayed in German, English and French.
Select your preferred language.
4. You can also define a color. It is shown in the form of a line below the title bar of windows. It
symbolizes the connection to a particular UC4 system and client.
5. Click the button OK.
If you log on using the password "pass", you will be requested to change it immediately.
Regardless, you can change your password at any time. Just click on System in the menu bar of
the UserInterface and select the command Change Password.

Automation Engine

1.4 Exploring the User Interface


Aim:
- Familiarize yourself with the UserInterface
Lesson 2
When your logon has been successful, the UserInterface is displayed. The top area shows the
menu and the toolbar. The remaining area can be used as a work space. As this is your first logon,
the three main windows are displayed.

UC4 Explorer - tasks managed by the Automation Engine are defined via objects and
stored here.

Activity Window - displays the current activities of your client.

Message Window - outputs information messages.

These windows can be moved and also changed in size. If you close a Window, it can be reopened
at any time using the corresponding button in the toolbar.
You can also open several UC4 Explorers at a time, the same holds true for the Activity Window. If
you click on the button , a window opens in which filters can be specified for the Activity Window.
By default, no filter is set which means that all activities are displayed. Use the tabs to specify

Chapter1 Getting Started Guide

filters for various areas. Then Click OK tab and the Activity Window opens. The status bar displays
your specified filter settings.
Window views can be refreshed at any time - just press the F5 key.

1.5 Creating an Object


Aim:
- Understanding the object orientation of the Automation Engine
- Creating folders
- Creating a Job
Lesson 3
Activities and processes managed with the Automation Engine are shown in the form of objects.
This brings about significant advantages:
l

Distributed operations
Complex processes can be handled in simple individual steps.
Re-usability
Partial tasks can be integrated in various processes.
Simple maintenance
Modifications can easily be assumed.
Clarity
Processes have a clear structure.
Expandability
New requirements can easily be integrated.

What types of objects are available? Refer to the document Object Classes which lists all object
types and briefly describes the tasks for which the particular objects can be used. In this lesson and
the following ones, various object types are used to familiarize you with the functioning of the
Automation Engine and present some suggestions of how you might structure your own processes.
Let's start creating an extra folder for our examples. Note that objects are created, edited and
administered in the UC4 Explorer.
1. Highlight the particular folder in the UC4 Explorer in which you want to insert a new folder.
Highlight the main node if your client does not yet contain any folders at all. The main node's
name consists of the UC4 system's name and the client number.
2. Click the button in the toolbar. A window listing all the available object types opens.
The content of your Templates window can look different from the one shown here, as the
UC4 administrator can influence the object types that should be displayed.

Automation Engine

3. Select the object type FOLD (Folder).

4. Assign an appropriate folder name.


To rename an object, subsequently highlight it in the UC4 Explorer and press the F2 key.
The next step serves to create a Job. This job is then used as the basis for our future examples. Job
objects can be used to execute commands on computers or in Enterprise Business Solutions (SAP,
PeopleSoft, Oracle Applications, Siebel). Commands, therefore, are widely used in this object type.
Note that there are individual Job objects available for each supported platform.
1. Open the folder created beforehand
2. Re-click the button in the toolbar.
3. Now select the object type JOBS.WIN (Windows Job).
4. As before in the Folder object, you can now assign a suitable name for the Job object.
5.
UC4 strongly recommends using naming conventions for your objects!
6. Then the object is opened automatically.
The following illustration displays the result in the UC4 Explorer:

Chapter1 Getting Started Guide

Now let's focus on the content of the Job object:


1. Open the Job object by double-clicking on it, if its not already opened.
2. Take a look at every individual table. Each object type consists of tabs in which lots of
properties can be specified. Some tabs are available in each object type whereas others are
only available in particular ones. No worry, the pre-specified default values are suitable in
most cases. They only need to be adapted for special cases.
Note that using the F1 key opens the UC4 Documentation at exactly the page at which
the tab and its settings are described.
3. Open the Notification tab
4. Select the computer from "Host" and the appropriate "Login object" required in order to log on
to this computer.
Contact your UC4 administrator if questions concerning Login objects arise.

The content of the Attributes tabis the same in all platforms, regardless if it belongs to an
z/OS Job, SAP Job, UNIX JOB etc.
5. Change to the Process tab.
6. The commands that should be processed can be stored here. Enter some Windows
commands. The follow illustration shows an example.

Automation Engine

7. Store modifications that you have made in objects by using the


8. Close the Job object.

button in the toolbar.

1.6 Executing an Object


Aim:
- Manually executing the Job
Lesson 4
The previous lesson explained how to create a Job object. This job should now be executed.
Executed objects are also referred to as tasks. Hence the processing of objects is described
whenever the UC4 Documentation refers to tasks.
1. Highlight the Job object in the UC4 Explorer.
2. Start processing it with the toolbar button.
3. The task is now displayed in the Activity Window. How long it remains there depends on the
commands that have been specified in its Process tab. Comprehensive scripts produce
longer job runtimes whereas simple commands have the effect that the job remains in the
Activity Window only for a few seconds.
When the job ends, the task is by default removed from the Activity Window. The
Attributes tab of the Job object, however, can be used to change this setting.

The Activity Window contains many columns which provide information about tasks such
as object name, start time and RunID. The RunID is a run number which is used in
executions.

Chapter1 Getting Started Guide


4. Right-click a task in the Activity Window and select the command Detail in order to obtain
further information about the execution.

5. If some peculiarities occur during the execution (such as the host is not active), an
appropriate text is output in the message window.

Exercise
Execute the Job object without having a Login object specified in the Notification tab Refer to the
text that is supplied in the message window. Correct this error by selecting the right Login object
and restarting the object. Now the message window displays that the job has ended normally.

1.7 Statistics and Reports


Aim:
- Calling the statistics of a Job
- Reading a job report

Automation Engine

Lesson 5
Meeting auditing requirements is highly important in the Automation Engine. Many functionalities
support these requirements by providing detailed information about what is going on in your UC4
system. This includes the statistics of objects which contain information about executions.
Now let's call the statistics of your Job object:
1. Highlight the Job object in the UC4 Explorer.
2. Open the statistics overview with the

button in the toolbar.

Each line stands for one object execution. The columns in the statistical overview are
essentially identical to those of the Activity Window.
3. Right-click on a statistical entry and select the command Detail. The Detail Window opens
and provides additional information about the execution.
4. The report can be called in the very same way. Depending on the object type and complexity
of the execution, it can comprise of several pages.

5. Close the Detail Window, the report and the statistics overview.

10

Chapter1 Getting Started Guide

Exercise
Read through the reports and Detail Windows of your Job object to get detailed information about
their executions.

1.8 FileTransfers
Aim:
- Creating a FileTransfer
- Creating a wildcard FileTransfer
Lesson 6
An integral part of processing is the transfer of files. The Automation Engine therefore provides an
extra object type for this activity. A statistics overview is available for FileTransfers (as for Job
objects) so that the individual executions can be traced.
We are now going to create a FileTransfer. Prepare several files that can be transferred to a different
computer.
1. Open the folder in the UC4 Explorer in which the Job object is stored.
It is of no importance where your objects are stored. Nevertheless, UC4 recommends
establishing a folder structure that makes your administrative work as easy as possible, as
objects that use each other do not necessarily have to be stored in the same folder.
2.
3.
4.
5.

Click the button in the toolbar.


Select the object type JOBF (FileTransfer).
Assign a suitable name.
Double-click the FileTransfer object to open it.

Let's now take a look at the content of the FileTransfer object. You already know many tabs from
the Job object. It applies for FileTransfers as well as all other object types that the predefined
default values are suitable. We are now going to define the file that should be transferred and the
location to which it should be sent.
1. Change to the FileTransfer tab.
2. Enter the file to be transferred and the host (computer) from which it should be transferred in
the upper half of the tab. First select the host and then the appropriate Login object which is
required in order to log on to the host.
3. Enter the path and the name of the file to be transferred. Ensure that the format is also
defined (binary or text file).
4. The lower half of the tab serves to specify the destination of the FileTransfer. Also select the
host and the appropriate Login object.
5. Enter the name and the path in which the file should be stored. You can also assign a
different name for the file.
6. Furthermore, you can define the reaction if the file already exists on the destination
computer. Select Overwrite in this case.

Automation Engine

11

7. The following illustration shows an example from the FileTransfer tab:

8. Store the modifications made in the objects with the


9. Close the FileTransfer object.

button in the toolbar.

The FileTransfer we created transfers one file. If you want to transfer several files with one
FileTransfer object, you can use wildcards. In doing so, files sharing the same start characters can
be transferred. Let's create such a FileTransfer:
1. Highlight the previously created FileTransfer object. We shorten the procedure and therefore
duplicate the existing FileTransfer.
2. Call the command Duplicate via the context menu (right mouse button).
3. Assign an appropriate name and double-click on the object to open it.
4. Activate the checkbox "Use wildcards" in the FileTransfer tab.
5. As we want the files to be transferred one after the other, the default setting "1" in "Max.
parallel-running transfers" is correct.
6. Enter the file names using "*" for the source and target hosts in the FileTransfer tab. The
illustration below serves as an example:

12

Chapter1 Getting Started Guide

7. Be careful to define the correct format, that is, "text" or "binary"!


8. Store your modifications using the button in the toolbar and close the FileTransfer object.
9. Start the execution using the button in the toolbar.

Exercises
Execute the two FileTransfer objects individually. The first file transfer is displayed in the Activity
Window as an individual task. As the second FileTransfer object transfers several files, each file is
displayed individually and you can view multiple tasks. Read the statistics and the reports of both
FileTransfer objects after the FileTransfer.

1.9 Automation via Schedules


Aim:
- Creating a Schedule
- Scheduling a FileTransfer
- Using the Schedule monitor
Lesson 7
So far, we have manually started our objects. As this is non-productive when a large number of
objects are involved, we are now going to explain the functioning of the object type Schedule in
close detail. Schedules start objects in a predetermined interval - every two days at 10.00 o'clock,
for example.
One of our FileTransfer objects should be executed every day at a particular time. First, we create a
Schedule object:

Automation Engine

13

1. Open the particular folder in the UC4 Explorer in which you stored all other sample objects.
2.
3.
4.
5.

Click the button in the toolbar.


Select the object type JSCH (Schedule).
Assign an appropriate name.
Double-click on the Schedule object to open it.

In each Schedule, an interval must be indicated in which the assigned objects should start. This
interval is also referred to as "period".
1. Change to the Attributes tab

2. Specify "1 Day(s)" in the period section as the FileTransfer should be executed once a day.
3. Open the Schedule tab.
Now we add a FileTransfer object to the Schedule object. Two different methods can be
applied:
Method 1: Use the Drag & Drop function and move the FileTransfer object from the UC4
Explorer to the Schedule tab.
Method 2: Call the command Add Task... using the right mouse button. Enter the name of the
FileTransfer object manually or click on the three dots which opens a new UC4 Explorer
window from where the object can be selected.
4. The properties window opens automatically as soon as the FileTransfer object has been
added to the Schedule.

14

Chapter1 Getting Started Guide

5. Enter the time 18.00 hours (24-hour system) in the Start time tab and then click OK.
6. Store your modifications with the

button which is found in the toolbar.

The Schedule tab displays this FileTransfer that has been planned for 6.00 p.m. (18:00 hours). You
can also plan several objects in one Schedule object. Each of these objects then has its own start
time. The execution interval, however, remains the same for all objects.

An object can be referred to as "Child" when it is activated by a superordinate task - a "Parent".


In our example, the FileTransfer object is the "Child" and the Schedule object is the "Parent".
Other examples for superordinate tasks are Workflows and Groups which will be explained in
later lessons.
The Schedule object is not yet active. Only active Schedules execute their objects:

Automation Engine

15

1. Highlight the Schedule object in the UC4 Explorer.


2. Start the execution with the button in the toolbar.
The Schedule object is now displayed in the Activity Window and remains active until it is
ended by you.
The current status of tasks within the Schedule can be queried through a monitor:
1. Highlight the Schedule object in the Activity Window.
2. Click the button in the toolbar.
3. The Schedule monitor opens. It is structured similarly to the Schedule tab. Additionally, it
shows the task status (such as ENDED_OK) and the next time of execution.
4. Close the monitor.
5. End the Schedule object by highlighting it and right-click the corresponding popup-menu
command in the Activity Window.

Exercise
The properties window of a planned task in the Schedule object can subsequently be opened with
the command Properties using the context menu (right mouse button) in the Schedule tab. Enter
your current time plus 2 minutes. Re-start the Schedule and watch its execution in the Schedule
monitor. Then end the Schedule.

1.10 Calendar Conditions


Aim:
- Creating a Calendar
- Creating a Calendar keyword
- Assigning this Calendar keyword to a FileTransfer
Lesson 8
It is very easy and helpful to schedule tasks through Schedule objects. Calendar objects can
additionally be included as business processes often dependent on particular days.
In this lesson, we adjust the execution of the existing FileTransfer. It should be started Mondays to
Fridays, but not on weekends.
1. Open the folder in your UC4 Explorer in which all existing sample objects are stored.
2.
3.
4.
5.

Click the button in the toolbar.


Select the object type CALE (Calendar).
Assign an appropriate name.
Double-click the Calendar object to open it.

The weeks are graphically displayed in the Calendar tab.

16

Chapter1 Getting Started Guide

Now the Calendar must be linked to the FileTransfer object. This is done with Calendar keywords.
1. Open the Calendar tab.
2. All Calendar keywords are listed on the right side. As this Calendar object has been newly
created, there is only the default keyword STATIC.

3.
4.
5.
6.

Different types of Calendar keywords are available, each having its own Form Assistant
for the quick and easy assignment of days.
Right-click with the mouse button somewhere in the list area and select the command New
Keyword -> Weekly.
A dialog window opens in which this keyword can be renamed to WEEKDAYS.
Remove the default keyword STATIC via the Del button or the command "Delete keyword"
in the context menu (right mouse button).
Now select the command Calendar Definition... (context menu) for the keyword
WEEKDAYS. A Form Assistant opens.

Automation Engine

17

7. Highlight Mo, Tu, We, Th, Fr and click OK.

8. Store the modifications using the


now highlighted in the Calendar.

button in the toolbar. All Mondays through to Fridays are

If several Calendar keywords are created, the days of the currently selected Calendar
keyword are highlighted.
9. The Calendar keyword WEEKDAYS now contains the dates of all weekdays.

10. Close the Calendar object.


The Calendar object is now ready for use. In the next step, we assign the Calendar keyword to the
FileTransfer in the Schedule.
1. Open the Schedule object.
2. Change to the Schedule tab and highlight the FileTransfer.

18

Chapter1 Getting Started Guide


3.
4.
5.
6.

Right-click the popup-menu command Properties.


Change to the Calendar tab and activate the checkbox of the same name.
Select "Execute if one condition matches".
Select your Calendar object and the keyword WEEKDAYS, then click OK.

7. The Schedule tab now contains the letter "C" in the Conditions column which indicates that
the Calendar condition has been set.

8. Store your modifications using the

button in the toolbar.

Automation Engine

19

9. Close the Schedule object.


In accordance with the definitions made, the FileTransfer object will run from Mondays to Fridays.
Note that this only applies when the FileTransfer was activated by the Schedule.

Exercise
Create a second Calendar keyword in the Calendar object which includes all Saturdays and
Sundays. Now select the WEEKEND keyword in the FileTransfer object instead of the
WEEKDAYS keyword. Hence, the FileTransfer object does not run on days between Monday and
Friday.
End the Schedule object and re-assign the WEEKDAYS keyword to the FileTransfer object.

1.11 Using Workflow Objects


Aim:
- Creating a Workflow object
- Using the Workflow monitor
Lesson 9
This lesson serves to introduce you to the object type Workflow. It comprises objects that run in
sequence, which is very useful for maintaining the UC4 Database.
Archiving and reorganization is required in order to maintain the database. These maintenance
processes must run in succession which is best organized by using Workflow objects. As a matter
of principle, UC4 strongly recommends handling your processes using Workflows and Schedules in
order make use of the full benefits of UC4's object orientation.
The job and the two existing file transfers will now be integrated in a Workflow.
1. Open the particular folder in the UC4 Explorer in which you stored all the created sample
objects so far.
2.
3.
4.
5.
6.

Click the button in the toolbar.


Select the object type JOBP (Workflow).
Assign an adequate name and double-click on the Workflow object to open it.
Change to the Workflow tab. By default, the start and end boxes are already available.
Insert the job and both file transfers. This can be done in two ways (as with Schedule
objects,):
Method 1 - Drag & drop one or several objects from the UC4 Explorer to the Workflow tab.
Method 2 - Call the command "Add Task" by using the right mouse button. You can either
enter the name of the object manually or click on the three dots to open a new UC4 Explorer
window from which the object can be selected.

The objects are displayed as boxes which can be moved and positioned as you like. The
lens symbols shown in the toolbar can be used to zoom into or out of the Workflow.
7. Order the objects starting with the two file transfers, followed by the job as shown in the
illustration below:

20

Chapter1 Getting Started Guide

Structuring the objects provides a clear overview. UC4 recommends using several
Workflows when there are a lot of objects or including other Workflow objects - called subWorkflows - in a Workflow.
8. The execution order for the objects is determined by lines. Right-click on an empty space in
the Workflow tab and select the command Line Tool. The mouse pointer is now displayed in
the form of a pencil symbol.
9. Connect the individual object boxes with lines (left-click with the mouse and draw it from box
to box). The illustration below shows the result thereof:

An object within a Workflow will only be activated when all its predecessors have ended.
Therefore, the job in our example will only start when the files of the two FileTransfers have
already been transferred.
10. Store your modifications using the

button in the toolbar and close the Workflow object.

The next step is to execute the Workflow:


1. Highlight the Workflow in the UC4 Explorer and start its execution with the button in the
toolbar.
2. The Workflow object is now displayed in the Activity Window. Due to the default settings,
the Workflow monitor also opens. Watch the Workflow execution. Tasks that are being
executed are displayed green; tasks that have already ended are shown in gray. Red signals

Automation Engine

21

that an error occurred (such as the file that should be transferred does not exist).

The default setting is that the Workflow will automatically be removed from the Activity
Window as soon is has ended. The Workflow monitor will also be closed. These settings can
be changed in the Attributes tab of the Workflow object.

Exercise
Delete the lines between the boxes (right-click with the mouse to highlight the particular line and
then click Remove dependency using the left mouse button to delete it). Arrange the three objects
one after the other. Then draw new connecting lines. When watching the execution of this
Workflow, you will notice that the Workflow starts with the first object, and then the second object is
processed and so on. Each object waits until its predecessor is finished.
Finally re-arrange the objects as shown in the above illustration.

1.12 Information through Notification


Aim:
- Creating a Notification
- Using the Notification monitor
- Assigning the Notification to a FileTransfer
- Restarting the FileTransfers in the Workflow
Lesson 10
Notifications are very important and are commonly used object types. They can be used to send
messages to individual users or even user groups of the UC4 system.
We will now create a Notification object and include it in the first FileTransfer in order to assure that
a message is sent if an error occurs.

22

Chapter1 Getting Started Guide


1. Open the folder in the UC4 Explorer in which you have stored the previous sample objects.
2.
3.
4.
5.
6.

Click the button in the toolbar.


Select the object type CALL (Notification).
Assign a suitable name and double-click on the Notification object to open it.
Change to the Notification tab
Select the priority "High" and the type "Alert".

7. Change to the Notification tab.


8. Enter a message text, keeping in mind whether this text should be used for multiple tasks or
only for specific ones. Depending on the use, the message should contain a general text or a
specific one.

Automation Engine

23

9. Change to the Recipients tab.


10. Select your user in the Recipients column.

11. Store your modifications using the

button in the toolbar and close the object.

For testing reasons, the Notification is now started manually.


1. Highlight the Notification in the UC4 Explorer and start it with the button in the toolbar.
2. The Notification monitor opens. Additionally, a Notification symbol in the right upper edge of
the UserInterface notifies you of the incoming message.

24

Chapter1 Getting Started Guide

3. Click Accept and then Done in order to successfully end the Notification.
The Notification object does not end if you close the Notification monitor instead of
responding to it as described above. The Notification symbol is still shown in the
UserInterface's upper right edge.Right-click this symbol and select the client. A dialog opens
in which you can reopen the Notification monitor.
The Notification sends a message if the first FileTransfer of the Workflow could not be executed
successfully.
1. Open the Workflow object by double-clicking it.
2. Switch to the Workflow tab. Properties can be specified for each object of the Workflow (as
in Schedule objects).
3. Right-click the box that is used for the first FileTransfer and select the command Properties.
4. Switch to the Postconditions tab.
5. Select Conditions and use the drag and drop function to move the STATUS entry to the left
window area. Now click <STATUS> within the STATUS block. In the displayed dialog,
select the status that is expected for a successful execution, which in this case is ENDED_
OK. Click OK to confirm this dialog.
6. Now add an Else condition to the STATUS block. Do so by calling the block's menu with the
symbol in the upper right edge and select the command "Add Else block".
7. In the Else section, you can define the expected reactions if the FileTransfer does not end
with the status ENDED_OK. Click Actions (right window section) and drag
EXECUTEOBJECTand BLOCK to the Else section.
8. EXECUTE OBJECT executes any executable object of your choice and BLOCK blocks the
task if the previously defined status condition does not apply (Else). For the parameter
<Object> of EXECUTE OBJECT, enter the object which should start (BSP_CALL01)and set

Automation Engine

25

the option "do not wait". In the BLOCK section, you can set any status text for the blocked
task.

9. Store your modifications in the Workflow object using the


this object.

button in the toolbar and close

Now the Notification can be tested in combination with the Workflow.


1. Enter a non-existing file name in the first FileTransfer object. This should cause an error in
your Workflow.
2. Highlight the Workflow in the UC4 Explorer and start its execution using the button in the
toolbar.
3. The Workflow monitor opens. As the file cannot be transferred due to the wrong file name,
the Workflow blocks. The FileTransfer box is displayed yellow.

26

Chapter1 Getting Started Guide


4. The Notification monitor also opens. Click Accept in order to indicate that you are going to
handle this problem. Thus, other recipients of this message know that somebody is already
in charge of this situation.
5. Right-click the FileTransfer box in the Workflow monitor and select the command Edit. The
FileTransfer object opens and the erroneous file name can be corrected. Now store and close
the FileTransfer.
6. The FileTransfer can now be re-activated. It is not necessary to restart the whole Workflow.
Just right-click the FileTransfer box and select the command Restart...
7. Click OK, the default settings are appropriate in this case.
8. The Workflow will now end successfully. Click Done.
You can also create the Notification CALL.ALARM using the button. It has been preconfigured and information about the name of the UC4 system, object type etc. is then
automatically included in messages.

Exercise
Select different priority levels and types in the Notification object. Start it manually and watch how
the different settings affect the Notification.

Automation Engine

27

1.13 Using Groups


Aim:
- Creating a Group
- Executing objects in a Group
Lesson 11
Usually, many tasks run in your UC4 system. Whether you want some to run parallel or not, using
the object type Group is very helpful. This object type is also useful for tasks that should be
collectively processed at a later point in time.
The two existing FileTransfers and the job should be integrated in a Group.
1. Open the particular folder in the UC4 Explorer in which you have stored the previous sample
objects.
2.
3.
4.
5.
6.
7.

Click the button in the toolbar.


Select the object type JOBG (Group).
Assign a suitable name.
Double-click the Group object in order to open it.
Change to the Notification tab
Our FileTransfers and the job should not run parallel but one after the other. Hence, the
default value "1" in the option "Max. parallel-running tasks" is suitable. The other pre-defined
settings for the execution are also correct for this example as the Group will be called
manually.

8. Store your modifications by using the

button in the toolbar and close the Group object.

The Group is assigned in the objects.


1. Open the two FileTransfer objects and the Job object and select the Group in the start-type
section of the Notification tab Store the modifications and close the objects.
2. Highlight the three objects and start their execution with the button in the toolbar.
3. The objects are now displayed in the Activity Window but have not yet started. They are in
the waiting condition "Registered" until the Group is activated.

28

Chapter1 Getting Started Guide

4. Highlight the Group object and start its execution with the button in the toolbar.
5. The Group is now displayed in the Activity Window and starts one object after the other (not
parallel). This procedure can also be watched in the Group monitor which is called via the
context menu (right mouse button) in the Activity Window. In the following illustration, the
first FileTransfer has already ended. The second one is being processed while the job waits
for its start.

1.14 Forecasts
Aim:
- Using the Auto-Forecast
- Using the regular forecast
Lesson 12
You already know how to create, schedule and execute objects. As your tasks are mainly organized
via Schedules, it is important to have the time and duration of task executions displayed centrally.

Automation Engine

29

The Auto-Forecast provides this functionality.


Supported by the Auto-Forecast, we will retrieve the next execution time of the FileTransfer that has
been included in the Schedule.
1. Highlight the Schedule object in the UC4 Explorer and start its execution with the
in the tool bar.

button

Note that the result of the Auto-Forecast only includes tasks of active Schedules and
objects of type Event.
2. Open the Auto-Forecast with the

button in the toolbar.

3. Click Recalculate if the calculation period for the forecast data is not up to date.
4. Limit the result by selecting "FileTransfer" from the list of object types and enter the name of
the FileTransfer object.
5. Now enter the period of time for which the executions should be displayed. It must lie within
the calculation period.
Your calculation period can deviate from the illustration shown above as it depends on the
settings made by your UC4 administrator.
6. Click Execute Query.
7. The lower part of the window lists the next FileTransfer executions. If the period includes a
weekend, the specified Calendar conditions are also considered (as can be seen in the
above illustration). The FileTransfer is not activated on weekends and therefore, the status
box in the column Logical start is displayed white.
8. Close the Auto-Forecast and end the Schedule object.
In addition to the Auto-Forecast, you can also query an individual forecast for a particular object. It
provides information about the average duration of this object's execution.
1. Right-click the Job object in the UC4 Explorer and select the command Forecast.
2. The calculation of the average runtime is based on several options that can be specified
here. In our case, the default settings are sufficient and you can click OK.

30

Chapter1 Getting Started Guide

3. The Forecast window opens in which all forecasts are located. The Runtime column informs
about their average execution times.

Auto-Forecast calculations also create individual forecasts (see above).


4. Close the forecast window.

Exercise
Include the Workflow in the Schedule object. Now start the Schedule. The Auto-Forecast now also
includes the Workflow and its objects.

Automation Engine

31

1.15 Navigation in the UserInterface


Aim:
- Working with the UC4 Explorer
- Searching objects
- Finding object uses
Lesson 13
You have already used many functions of the UserInterface in the previous lessons. This document
serves to explain additional useful functionalities.
General information:
From any location in the UserInterface the available commands can be called via the menu, push
buttons in the toolbar, context menu (right mouse button) and shortcuts. When we restarted the
Workflow in our example, we could directly open and edit the object via the Workflow monitor.
Another very functional detail: If the name of an object is written in a window (such as in a text field
or a table), you can directly open and edit it via the right mouse button.

The view of the UC4 Explorer can be changed according to your preferences:
1. Objects can be sorted by names, object types, etc. - just click on the particular column title.
2. If you like, you can rearrange the columns by dragging the column title to the designated
position.

32

Chapter1 Getting Started Guide

3. The view of object symbols can also be changed. Right-click an empty space in the folder
and select View. The options Details, List and Large icons are then available.
4. Opening several UC4 Explorers is also possible.
Keep the following in mind when working with the UC4 Explorer:
You have already created a folder at the beginning of this chapter. Note that due to the object
orientation of the Automation Engine, folders are also regarded as object types. They are
therefore created with the

button in the toolbar.

Object names within a client must be unique.


It is irrelevant in which folder the objects are stored. UC4 recommends creating a folder
structure that makes your administrative work as easy as possible. Objects that use each other
(such as Workflows) do not necessarily have to be stored in the same folder.
Links can also be created in the UC4 Explorer. You can access a particular object in several folders.
1. Highlight the object to which you want to create a link and call the command Link to... which
is available in Duplicate/Link/Move in the context menu.
2. Select the folder to which the object should be linked.
The Search function is another important functionality. It can be used to search objects within a
client, by using filter criteria.
1. Call the search function with the button in the toolbar.
The search contains three tabs that can be used to limit the search result.
2. Select the object types Job and Calendar.
3. Click Start.
4. The result is displayed in the lower half of the window.

Automation Engine

In some situations it can be helpful to know in which other objects a particular object is also used.
This special search for use is also available.
1. Highlight the first FileTransfer and call the command Search for Use... from the context
menu (right mouse button).
2. The search opens and the name, object type and type of search are already inserted.
In the settings of the Objects tab in Search for... you can define whether the search
function searches for objects or for object uses.
3. Click Start.
4. The result is displayed in the lower half of the window.

33

34

Chapter1 Getting Started Guide

Exercise
Create a new folder and try to link objects. Search for the sample objects and their uses.

1.16 Personal Settings


Aim:
- Individual use and configuration of the UserInterface
Lesson 14
The previous lessons trained you to use the various functionalities of the Automation Engine. Now,
we want to introduce you to the various individual settings that can be applied and make working
with the Automation Engine even more comfortable.
1. Multi-desktop mode
Using multi desktops is very convenient. So far, you have been using one working
environment of the UserInterface. This can be changed by adjusting the settings of the
UserInterface, which can be called using the menu item Options in the General tab.
See: Using Desktop Modes

Automation Engine

35

2. Arranging windows
Windows can be moved and changed in size as required. Use the menu Options to store
your individual settings. The command Settings opens several tabs. In the General tab,
magnetic windows can be activated.
See: Settings of the UserInterface - General
3. Opening monitors
In the settings of the UserInterface, you can also specify the monitors that should open
automatically when an object has been activated.
See: Settings of the UserInterface - Activity refresh
4. Safety queries
The Check Back tab is also available in the settings and contains a list of situations in which
a safety query is made. Example: If you do not want to have the query "Do you really want to
execute this/these object(s)?" displayed with each object activation, you can change this
setting in this tab.
See: Settings of the UserInterface - Check-back
5. Connections to several clients
The menu item Connections can be used to establish connections to several clients. A
special license is required for this function.

Exercise
Try the above configuration methods and find your preferred settings.

1.17 Last but not Least


Have you been working through the lessons intensively and also engaging in the exercises?
Congratulations! You are now well informed of the basics of the Automation Engine.
As the next step, you can now start to map your own processes in the UC4 system. Possible
window and object configurations are described in the UC4 Documentation. This online help is
available via the F1 key and always opens the page that contains information about the active
window's content.
A particular document UC4 would like to recommend in this context is Tips and Tricks on Using the
UC4 Documentation which provides very helpful information.
Would you like to continue enhancing your UC4 knowledge? Refer to our introductory chapter about
UC4 Script and the Sample Collection, both of which provide deep insights into the common use of
UC4 objects in combination with UC4 Script.
These very practical chapters serve to introduce you to the basic functioning of the Automation
Engine. For the more complex functions of the Automation Engine, UC4 recommends attending one
of the trainings offered by our experienced trainers. They will be pleased to explain details and
peculiarities in connection with your particular environment!

36

Chapter2 UserInterface

2 UserInterface
2.1 Introduction
The UserInterface serves as a connector between the UC4 system and its users. Its userfriendly interface facilitates the quick and easy handling of all processes.
This document provides general information about the way the UserInterface works. For more
detailed information, refer to the subsequent documents that describe the individual functions.
The UserInterface view includes the following three main windows:
l
l
l

UC4 Explorer - includes the existing objects


Activity Window - includes the tasks that are active including their states
Message Window - prints information, warnings and error messages that refer to the
processes

If you have the necessary authorization, you can also have the System Overview displayed. It
provides information about the UC4 system's current status and you can edit it by using various
functions.
You can save your personal UserInterface settings so that the order of the main windows is the
same when you log on the next time. All users can create their own particular settings. The
UserInterface offers numerous other settings that can also be adjusted according to the different
users' requirements.
The way how date and time are displayed depends on the regional settings that are specified for the
particular user.
You can also make screenshots of particular UserInterface windows. This function can be very
useful for various purposes. You can call it by using the Screenshot command which is available in
the UserInterface's Options menu. If you activate this function, the mouse pointer displays with a
symbol and you can create screenshots of particular UserInterface windows. Click on an area
within a window or on the title bar to screenshot the whole window. A red frame indicates the outline
of the newly created picture. If the window on which you click is not in the fore, the overlapping
window(s) are also including in the screenshot. They are stored in .PNG format. You can also
snapshot particular parts of the UserInterface's interface. Just activate the screenshot function by
keeping the Shift key pressed.
You can use the F1 key to call the UC4 Documentation from anywhere in the UserInterface. The
help opens at exactly the section that describes the particular window, tab or script element.
Use this opportunity in order to obtain information about the various UserInterface functions.
You can use the View in the menu bar to change the view of the windows. You can either select
the Standard Design (new as of version 9) or the Classic Design (same design as in version 8).

2.2 Login
The login dialog that is shown below pops up when you start the UserInterface. Enter your name
and department, and the client to which you want to establish a connection.
You can establish connections to several clients and UC4 systems from within the UserInterface.
Doing so requires a specific license. A colored line that displays underneath a window's title bar

Automation Engine
shows windows of the same client in the same color. You can select your preferred colors from a
drop-down list.
The UC4 administrator determines the encoding for the UC4 system in the UC4 Variable UC_
SYSTEM_SETTINGS, key XML_ENCODING. You can open connections to several UC4
systems in the UserInterface if they have the same encoding. You must start a second
UserInterface if you want to connect to a UC4 system with a different encoding.

Description
Field

Description

Connection

Drop-down list for the UC4 system connections that are defined in the
uc4config.xml configuration file.

Client

Client number.
Allowed values: 0 - 9999

Name

User name.

Department

User's department.

Password

User's password.

Language

Drop-down list for the language of the UserInterface.


Allowed values: "D", "E", "F"
"D" = German
"E" = English
"F" = French

37

38

Chapter2 UserInterface

Color

List in which you can select a color.


In the login dialog, you can assign a color to each client connection
within a UserInterface instance. Each color can be used once. It will
appear as a colored line underneath the title bar of the individual
windows.
The number of colors and the colors that are available depend on the
definitions that are stored in the configuration file uc4config.xml of the
UserInterface. Note that officially, the number of simultaneous
connections is limited to 8.

See also:
Client
User

2.3 Using Desktop Modes


The desktop - working space of the UserInterface - is the environment in which objects can be
created and their execution be monitored. Due to the various functions that are available, many
windows can be in use. Two different desktop modes are therefore available which serve to
provide a clear overview.
Select your preferred mode when working with UC4.
l
l

Single Desktop Mode


Multi Desktop Mode

Desktop modes are specified in the settings of the UserInterface - General tab.
Regardless of the selected mode can the windows be grouped according to your requirements via
the menu item "window". It is found in the title bar of the UserInterface. You can also specify a
magnetic area which provides for a seamless grouping of windows.
Single Desktop
If you work with one desktop, all windows are displayed on this desktop. If there are connections to
several clients, the windows belonging to the same client show the same color line underneath the
window's title bar.
Multi Desktop
An extra work space is created for each connection when the multi-desktop mode is used.
Additionally, you can create new desktops. The specific advantage is that the windows of different
connections can be displayed in one desktop - you can create a desktop for the Activity Windows of
your clients, for example.
A user-defined desktop can be created as shown below:
1. Click the button [+] which is available next to the Desktop tabs.
2. Enter a name and a color for the new desktop to be created
3. Activate the required client connection through the menu item "Connections" (New
Connection) in the menu bar of the UserInterface
4. Now open the windows of the particular client
5. Repeat steps 3 and 4 to access the windows of other clients

Automation Engine

39

The client currently used in the user-defined desktop is shown in the UserInterface's title line.
By default, the checkbox "Adopt active connection color" is activated when a user-defined desktop
is created. If you are logged on to client 1 with a red color, the same color is suggested for the userdefined desktop if it should contain windows of client 1. If you log on using the color blue, the userdefined desktop is automatically displayed in blue, too.
For each desktop, the status bar displays a tab in the connection's color or the color which has been
selected for the user-defined desktop. Click these tabs to switch between the different desktops.
You can also use the shortcuts to scroll through the available workspaces:
l
l

Forth "Ctrl" + "Shift key" + "<"


Back: "Ctrl" + "<"

For connections, the tab shows the name of the UC4 system and the client. You can specify an
individual name for user-defined desktops.

The context menu of a box contains the commands "Activate Desktop" and "Close Desktop". Userdefined desktops can be renamed and their colors be changed if required.
It is not possible to close the connection to the client to which you connected first via the
UserInterface.
The tabs for connection desktops are listed in alphabetical order. If a connection has windows in a
user-defined desktop which does not yet exist, this desktop is queued directly after the
corresponding connection desktop. If windows of a connection already exist in several user-defined
desktops, their tabs are queued alphabetically.
Objects can be dragged and dropped from one desktop to another. The target desktop is
displayed when an object - mouse button held down - is dragged to one of the desktop's tabs in
the status bar. In doing so, it can be stored in the Explorer of the destination desktop. In this
case, the object is not moved but copied.
Although each desktop can display different windows, the Message Window and the System
Overview remain the same. Both always show the same content.
User-defined desktops are stored and still available when you log on to the UserInterface the next
time. If defined, the main windows such as Explorer, Activity Window, Message Window and
System Overview are also displayed in the same way.
A global license is required in order to open several connections. Without this special license,
only one additional connection can be established to the system client 0000.

2.4 Buttons in the Toolbar of the UserInterface


The following overview describes the meanings and functions of all symbols that are used in the
UserInterface.
Standard Commands
Symbol

Definition

Description

Explorer

Opens a new UC4 Explorer.

40

Chapter2 UserInterface

Search

Enables the Search for a client's folders and


objects by using detailed criteria.

Activities

Opens a new Activity Window.


Objects that are displayed must be set in the
Dialog Box.

Messages

Opens and closes the Message Window.

System Overview

Calls the System Overview.

Forecast

Calls the Forecast Overview.

Auto Forecast

Calls the Auto Forecast.

Settings

Calls the Settings of the UserInterface.

Execute

Runs an executable object.


This command refers to one or more executable
objects that have been highlighted in the UC4
Explorer. It also starts an executable object that is
open for editing purposes.

Statistics

Calls the current statistical overview.


l

The statistics of an object are available if


an object or its monitor view is open or if
the object has been highlighted in the UC4
Explorer.
The statistics of UC4 servers, agents or
users can be displayed in the System
Overview.

Child objects statistics

Calls the statistical overview of child objects.


This command is available if the statistics are
open and if a selected object has child objects.

Report/Last report

Displays the report/last report depending on the


context. For example:
l

The report of an active object that is


highlighted in the Activity Window or
whose monitor is open displays.
The current UC4 server or agent log can be
called in the System Overview.
The last report displays immediately if an
object is open for editing purposes or
highlighted in the UC4 Explorer.
The report of a highlighted entry can
always be called in the statistical
overview.

Edit

Opens the object so that it can be edited.

Delete

Deletes folders or objects in the UC4 Explorer.


This command refers to highlighted folders and
objects. By default, a safety query displays.

Automation Engine

Print

41

Prints the content of the particular active window.


For example:
l

The content of an object that is highlighted


in the UC4 Explorer with all its settings and
specifications in the individual tabs
including Process and Documentation
tabs.
Statistics and reports.

To select a printer other than your default printer,


open the Print Preview by using the appropriate
popup-menu command. Then click the
and select the printer of your choice.

symbol

Print...

Opens a selection dialog for the printer or the page


view if it is called from the menu.

Print preview

Creates the print preview.


You can print one or all pages of this print preview.

New object ...

Creates a new object, thereby using predefined


templates.

New Folder

Creates a new folder (object type FOLD).

Duplicate

Creates an identical copy of a particular object


using a different name.

Details

Shows the object details in the Explorer window.

List

Displays the objects in the Explorer window in list


form.

Large icons

Displays objects in the form of large symbols in


the Explorer window.

Up

Changes to the superordinate folder of a UC4


Explorer.

Refresh

Refreshes the existing view of all open windows.

Commands for Handling Objects


Symbol

Definition

Description

Save

Saves an object.

Variables...

Opens the Variable Selection dialog in objects in which you can select
predefined variables.

Cut

Cuts the highlighted text out of the Process and Documentation tab.
The text is saved in the Windows clipboard and can be inserted in new
position.

Copy

Copies a text that is highlighted in the Process and Documentation


tabs.
This text is also saved in the clipboard for further use.

Paste

Imports a text from the Windows clipboard to the Process tab or a


Documentation tab.

42

Chapter2 UserInterface

Undo

Cancels the last modification in the Process tab and the


Documentation tabs.

Redo

Repeats a previously canceled modification that has been made in the


Process tab and the Documentation tabs.

Comment
Block

Adds a comment to the active script line.

Uncomment
Block

Removes an existing comment from the active script line.

Increase
Indent

Increases the indention in the Process tab.

Decrease
Indent

Decreases the indention in the Process tab.

Weeks
horizontally

Displays Calendar weeks horizontally.

Weeks
vertically

Displays Calendar weeks vertically.

Periodic
view

Activates the periodic view in a Calendar if periods have been defined.

Search...

Searches for text in:


l
l
l

The Process and Documentation tabs of objects.


Reports of servers/agents and objects.
Message Windows.

Line Tool

Editing mode of the workflow:


Switches the Line Tool on or off so that objects in a Workflow can be
linked.

Fit

Editing mode of the Workflow:


Adjusts the size/proportion of the edited Workflow to the window size
while it is activated.

Zoom in

Editing mode of the Workflow:


Enlarges the edited Workflow regardless of the window size.

Zoom out

Editing mode of the Workflow:


Reduces the edited Workflow regardless of the window size.

Zoom in
section

Editing mode of the Workflow:


Zooms in a section of the edited Workflow that can be framed by
clicking the mouse.

Special Commands of the Activity Window


Symbol

Definition

Description

Cancel

Cancels the execution of the selected task(s).

Quit

Ends the selected long-running task(s).


Can be used in Schedules, Events, Period
Containers and RemoteTaskManagers

Automation Engine

Deactivate

Deactivates finished task(s).


Can only be used for:
l

Individual tasks (they do not run within a


workflow) that have already ended
Workflows that do not include active
tasks

Detail

Opens the Detail Window.

Filter...

Here you can change the Activity Window


selection.

Hierarchical

Activates or deactivates the hierarchical


Activity Window view.

Comments

Here you can add comments to the selected


tasks.

Monitor

Opens the monitor of Workflows.

Rollback

Processes a Rollback of the selected task(s).


This button is only available in Workflow tasks
in which the Rollback settings are active.

Restart

Restarts the task(s).


Only available for tasks that have already
ended.

2.5 Keyboard Shortcuts


You can also navigate within the UC4 UserInterface by using shortcuts.
General
Shortcut

Description

F1

Opens the UC4 Documentation at the position where it


contains information about the active window.

F3

Displays the Quick Access field.

F5

Updates the content of the active window.

Shift key + UP or DOWN


ARROW

Highlights several lines in the list view.

CONTEXT MENU (button


between "ALT GR" and "CTRL")

Opens the context menu for the highlighted window.

CTRL + A

Highlights everything.

CTRL + C

Copies the highlighted text.

CTRL + F

Opens the search window for texts.

CTRL + P

Prints the content of the highlighted window.

CTRL + V

Inserts the copied text at the mouse-pointer position.

43

44

Chapter2 UserInterface

CTRL + X

Cuts the highlighted text.

CTRL + Y

Repeats a previously undone modification in the Process


and Documentation tabs.

CTRL+ Z

Undoes the last modification in the Process and


Documentation tabs.

ALT + blank key

Opens the menu of the UserInterface window.

Enter key

Confirms the window entry.

Menu bar
Shortcut

Description

ALT + letter

Opens the menu of the underlined specified letter.

ALT + letter +
letter

Opens the menu and executes the command of the menu whose letter is
underlined.

Desktop
Shortcut

Description

Caps Lock key + CTRL + TAB

Backward switch between windows.

CTRL + TAB

Forward switch between windows.

CTRL + F4

Closes a window.

CTRL + <

Switches to the left desktop.

CTRL + Caps Lock key + <

Switches to the right desktop.

Objects
Shortcut

Description

ALT+ M

Opens the monitor of the superordinate object.

F2

Opens a dialog box for renaming the highlighted object.

TAB

Switches to the next setting within a tab.

TAB +
LEFT
ARROW

Switches to the left tab in objects.

TAB +
RIGHT
ARROW

Switches to the right tab in objects.

CTRL +
E

Opens an object for editing.

CTRL +
F

Opens the quick search function in object lists (such as the Explorer) or workflows.

CTRL+
H

Opens the Statistics.

You can use it in the Explorer, the Activity Window, the System Overview, the
Statistics window, the Search window, and for the tasks of workflows and
schedules. Note that you cannot use this shortcut when the Line Tool is active.

Automation Engine

CTRL+I

Opens the Detail Window.

CTRL+
M

Opens the monitor.

CTRL +
N

Opens the window containing the templates for object creation.

CTRL+
R

Opens the report.

CTRL +
S

Stores an object.

CTRL+
T

Opens the Statistics of the superordinate task.

45

2.6 Settings of the UserInterface


Various basic settings are available and can be used to handle the UserInterface. These settings
are user-specific which means that users can define their own preferred settings that are loaded
whenever a user logs on to the UC4 system.
Select Settings in the Options menu in the UserInterface in order to specify your personal settings.

General
[General] [Activity refresh] [Message Window] [Font Settings] [Script editor] [Statistics] [Time
format/Calendar] [Check back] [Workflow] [ERP Forms]

The mode in which the desktop of the UserInterface should be displayed can be defined in the
General tab. Note that the settings that have been specified in the first connection are applied if
several connections are open.

46

Chapter2 UserInterface

In the General tab, you can define the magnetic scope of the windows that are shown in the
UserInterface. By default, this function is deactivated. If you activate it, you can also specify the
magnetic area in pixels (default value 15, max. 25 pixel). If this value is not kept, the window is
aligned to the nearest screen edge or window. Depending on the setting that you have made, this
function becomes effective either when you drag or drop the window.
Each window contains its own toolbar. You can specify whether texts that refer to the pushbuttons
should be displayed, and how.

Activity refresh
[General] [Activity refresh] [Message Window] [Font Settings] [Script editor] [Statistics] [Time
format/Calendar] [Check back] [Workflow] [ERP Forms]

The Activity Window is refreshed either automatically or manually. Use theActivity refresh tab in
the Settings window in order to decide upon the basic settings you prefer.

Automation Engine

47

Windows are automatically refreshed unless the system is busy. Specify the number of seconds
that the system must be idle in order to allow refreshing. You can determine the intervals for
refreshing in the box "Refresh interval". This interval is influenced by the duration of the previous
refreshing time as refreshing can take some time when there are many tasks in the Activity Window
- for example when a Workflow is being processed. As a result, the interval until the next window is
refreshed gets longer. This setting serves performance improving purposes.
For example: The past refresh lasted 4 seconds due to the numerous activities in the Activity
Window. Therefore, the next refresh will not be carried out before 12 seconds.
If you select the option Manual refreshing is only possible via the F5 key. Selecting the option
Automatic causes an immediate refresh when the F5 key is pressed.
You can also select the objects whose monitor should open automatically whenever they are
activated.
See also: Updating UserInterface Windows

Message Window
[General] [Activity refresh] [Message Window] [Font Settings] [Script editor] [Statistics] [Time
format/Calendar] [Check back] [Workflow] [ERP Forms]

Messages are displayed depending on the user privileges that have been assigned and the settings
of the Message Window. The UC4 administrator determines if a user can also receive system
messages. In this window, you can define how messages that are assigned to you should be
displayed.

48

Chapter2 UserInterface

You can select whether all client messages should be displayed, or only your own messages plus
the ones of the Group. Additionally, administrator and security messages can also be displayed.
It is also possible to specify whether the Message Window should open automatically for incoming
information or error messages. Furthermore, two checkboxes are available that can be used to
specify the message type that should be displayed. Specify the number of messages that should be
read when the UserInterface starts and when you updating using the F5 key.
The setting "Show unread messages after logon" only refers to administrator and security
messages. More detailed information is provided in the document Message Window.
Messages that have been sent by using the script element SEND_MSGare not delivered if the
checkbox "Display error messages and warnings only" is active.

Font Settings
[General] [Activity refresh] [Message Window] [Font Settings] [Script editor] [Statistics] [Time
format/Calendar] [Check back] [Workflow] [ERP Forms]

You can determine the size in which the caption should be displayed in the UserInterface. This
setting affects all connections to clients or other UC4 systems opened within this UserInterface.
The selected size is stored in the connection that has been used for the first login. The effect is
that if you start the UserInterface again at a later point in time using the same first connection,
the stored font size is used for displaying the captions.

Automation Engine

49

This tab can be used to change the font used in scripts, reports and activation logs. Type "Courier
New", size 14 is used by default. The UserInterface immediately assumes modifications, open
windows must be closed and re-opened.
The font size of the windows referred to above can also be modified by using the CTRL key in
combination with the scroll wheel. These modifications then only apply for the particular window
and are not stored if the window is closed.

Script Editor
[General] [Activity refresh] [Message Window] [Font Settings] [Script editor] [Statistics] [Time
format/Calendar] [Check back] [Workflow] [ERP Forms]

The settings made in this tab apply to all Process tabs.

50

Chapter2 UserInterface

Show parameter info:


Script functions and statements usually require one or several fixed or optional parameters to be
specified. A parameter list can be displayed which is helpful to enter data.
Show help for parameter info:
The UC4 Documentation describes each script element on a separate page. The script editor can
directly display the required page, pressing the F1 key is not required.
Assume line's last prefix to continuation line:
The script editor distinguishes three types of scripting lines whose first characters differ from each
other:
l
l
l

Comment lines start with "!"


UC4 scripting lines start with ":"
All other lines are JCL lines

Activating this setting has the effect that a new line automatically starts with the first character used
in the previous line.
Suggest and keep indent:
For the purpose of keeping a clear structure, scripting lines in constructs such as :IF or
:WHILEshould be indented. The script editor can automatically indent such lines, pressing the tab
key is not required.
Close constructs automatically:

Automation Engine

51

Constructs such as :IFor :WHILEcan automatically be completed with the corresponding closing
statement (:ENDIF, :ENDWHILE).

Statistics
[General] [Activity refresh] [Message Window] [Font Settings] [Script editor] [Statistics] [Time
format/Calendar] [Check back] [Workflow] [ERP Forms]

Statistical data is created whenever executable objects are activated. This data remains stored in
the UC4 Database until it is removed using the utilities UC4.DB Reorg and UC4.DB.
In this tab, you can select the maximum number of statistical data that should be shown in an
object's statistical overview.
The maximum value is 999. Use the selective statistics if you want to access several
executions of an object.

TimeZone/Calendar
[General] [Activity refresh] [Message Window] [Font Settings] [Script editor] [Statistics] [Time
format/Calendar] [Check back] [Workflow] [ERP Forms]

The TimeZone that is specified here only serves display reasons (for example, for the Message
Wwindow). It does not affect the processing of tasks. Therefore, it does not make a difference who
has started the object (see also:Using TimeZones in UC4). If you select "Default" in the section
Time format, UC4 uses the computer's time format.

52

Chapter2 UserInterface

You can also specify your preferred standard Calendar View. You can change this view at any time
in an open Calendar using the UserInterface's menu.
It is also possible to define the week that should be displayed as the first week of the year. The
definition made here is displayed in Calendar objects but does not influence processing (for
example, WEEK_NR).
If you select the option Default, the specification that the UC4 administrator made in the UC4
Variable UC_CLIENT_SETTINGS with the key FIRST_WEEK_METHOD is used for the first
week of the year.

Check Back
[General] [Activity refresh] [Message Window] [Font Settings] [Script editor] [Statistics] [Time
format/Calendar] [Check back] [Workflow] [ERP Forms]

Particular actions of the various objects are re-checked before they are executed.

Automation Engine

53

Specify the actions that should be re-checked. Note that actions that are highlighted with "*" are
activated after each program start, regardless of other selections that have previously been made.

Workflow
[General] [Activity refresh] [Message Window] [Font Settings] [Script editor] [Statistics] [Time
format/Calendar] [Check back] [Workflow] [ERP Forms]

In order to facilitate the creation of a Workflow, you can set a default value for the line status. This
value is automatically assumed to the Dependencies tab of Workflow objects.

54

Chapter2 UserInterface

Here you can specify the status of the previous task, which is required for the execution of the
following object. Also determine the alternative action for the case that a job ends with a different
status than has been specified. Selections you make here are default settings that apply
automatically when a workflow is created. They can also be changed directly in the individual
objects.
The properties of workflow tasks are displayed in a tooltip text which is composed of the information
that is provided in the tab selected here. The two options Thumbnail and General do not refer to
tabs. Thumbnail has the effect that the box for the workflow task is shown in tooltip if a particular
zoom level has been reached. The tooltip contains a picture of the tooltip box if the workflow view
has been reduced to an extent that the box content could not easily be read anymore. "General" has
the effect that the tooltip displays an additional area that includes the most important information
such as object type, host name and the short forms of specified properties.
You can use the option Prompt for alias in order to determine whether the dialog Add task should
be displayed when you add Workflow tasks using the drag and drop function, and when. In this
dialog, you can assign an alias for the task and determine whether the task is an external
dependency.
l
l

Always - The dialog always displays if objects are dragged and dropped to a Workflow.
On duplicates only - The dialog only opens if the object is already available in the Workflow
as a task. Only the object name is checked, not the alias name.
Never (default) - The dialog does not open if the drag and drop function is used.

If you define an alias for a workflow task, this alias is displayed in the workflow monitor, the
Activity Window and the Statistics instead of the actual object name.

Automation Engine

55

ERP Forms
[General] [Activity refresh] [Message Window] [Font Settings] [Script editor] [Statistics] [Time
format/Calendar] [Check back] [Workflow] [ERP Forms]

Select the Login object that should be used by default in the Form tab of PeopleSoft jobs in order to
connect to the Enterprise Business Solution. You can use the option Work Offline in order to
deactivate the login screen. It can then be called manually by using a menu command.

2.7 UC4 Explorer


2.7.1 UC4 Explorer
General Information
[General Information] [Folder] [Objects]

The UC4 Explorer is the central window of the UserInterface. You can use it to edit, display,
administer and execute objects. Its structure and handling is basically identical to Windows
Explorer.

56

Chapter2 UserInterface

The UC4 Explorer window is divided into two parts. The left half shows the folders of a client. A
newly created client initially only includes the<No Folder> folder. It includes objects that have been
restored after they have been deleted, for example. You can specify the folders of a client that can
be used in the authorization system. By doing so, you can limit the access of users to folders and
subfolders.
The right half of the UC4 Explorer includes the objects of the folder that is currently open. The
objects can be displayed with large icons, as a list or with details. Use the popup-menu command
View in the UserInterface (right-click without highlighting an object) for this purpose. You can also
sort objects by name, object type, title, and creation or modification date. Do so by clicking on the
particular column title.
The status bar in the bottom window edge displays the number of objects in a particular folder and
the number of objects that are currently selected.
Within a UserInterface, you can use several UC4 Explorers and access objects that are sorted,
selected or displayed according to different criteria. Open a new UC4 Explorer by clicking the
corresponding toolbar button. You can also use the Explorer... command in the File menu. Use the
Window menu in the UserInterface in order to switch between UC4 Explorer windows.
Folder
[General Information] [Folder] [Objects]

In your own client, you can create any number of folders and structure them by using subfolders.
You can organize them as you like. Note that you can also assign different access rights to different
users. The only limitations is that the names of folders of the same hierarchy must be unique.
Folders of the same names must only be used as subfolders of different folders.
Action
New object ...
New folder

Description
You can create a folder by using the New object or New
folder command in the File menu of the UserInterfaces or
the popup-menu command New... (right click). You can
also use the toolbar buttons.
The characters A-Z, 0-9, $, @, _, . and # can be used for
names (max. 200 digits). You can also specify a folder
title.

Automation Engine

57

Delete

You can only delete a folder if it does not include


subfolders. Otherwise, you must delete the subfolders
first. Highlight the folder that should be deleted and use
the Delete command in the File menu of the UserInterface
or the context menu, or the button in the toolbar.
Objects that are stored in the folder are not deleted but
moved to <No Folder>. If there are links to one of these
objects, the oldest link is deleted and the object is copied
to this link.

Duplicate

Use duplicate in order to create a new folder. The objects


that it includes are not duplicated. The new folder includes
links to these objects instead (see below).

Objects
[General Information] [Folder] [Objects]

Objects are the exactly defined tasks that can be edited, displayed, administered and executed in
the UC4 Explorer. You can also access their statistics and reports.
Action
New object

Description
You can create an object by clicking the
button in the
toolbar, by using the corresponding command of the
New... menu in the UserInterface, or you can use the
New... command in the context menu (right click). Within
a client, the object name must be unique. The following
characters are allowed: A-Z, 0-9, $, @, _, . and # (not
more than 200 characters). You can also specify an object
title.
Note that the suggested default object name can also
include a counter. The UC4 administrator can specify
the corresponding settings in the UC4 Variable UC_
OBJECT_COUNTER.

58

Chapter2 UserInterface

Duplicate
Duplicate to...

Creates an identical copy of one or several objects in the


current folder. The name that is suggested is the original
object name plus the appendix .NEW.1, .NEW.2 etc.
depending on the number of highlighted objects. You can
use the Duplicate to command in order to select a target
folder for the duplicated objects.
Within a UC4 system, you can also use the drag &
drop function to copy objects from one client to
another. Keep the following information in mind:
l

Link to...

The object is not to be copied if the target client


already includes an object of the same name.
Users and UserGroups cannot be copied to other
clients.
Objects cannot be copied to <No Folder>, the
Recycle Bin, the Transport Case or the folder
Version Management.
Objects with authorizations that have been
assigned via the context menu by using the
Properties command cannot be copied to other
clients.

Stores a file link in the selected target folder. Press the


shift key before you move an object or a link, and a link is
also created in the target folder.
A small arrow in the icon identifies links. Specific menu
commands are available:
l

Open home folder: Opens an Explorer window that


displays the folder in which the object is stored.
Set home folder: The object and the link that is
used to call the command change places.

The home folder is the folder in which an object is


created or duplicated, or to which it is imported.
Links have always the same name as the object to
which they refer. If you rename the object, all links are
also renamed.
If you want to delete a link, you require write access to the
folder in which this link is stored.
Move to...

Moves the highlighted objects to the selected target


folder. You can also use the drag and drop function in
order to move objects between folders. If you want to
move a particular object, highlight it in the right UC4
Explorer section and drag it, by holding the mouse button
pressed, to the folder in the left UC4 Explorer section.

Automation Engine

Delete

59

Deletes an object from all folders. To delete an object,


highlight it and use the button or select Delete in the
File menu of the UserInterface or in the context menu. If
the object that should be deleted is used in other objects
such as a Workflow or Schedule, a query displays in order
to verify whether the object should really be deleted.
Deleted objects are moved to the UC4 Recycle Bin and
can be restored if necessary.

Rename

Opens a field in which you can change the object's name


and title. Do so by highlighting the object and press the F2
key or select Rename in the File menu of the
UserInterface or the context menu. A name field opens in
which you can edit the object's name. The following
characters are allowed: A-Z, 0-9, $, @, _, . and # (not
more than 200 characters). If the object that should be
renamed is used in other objects such as a Workflow or
Schedule, a security query displays in order to verify
whether the object should also be renamed in these
objects. A dialogue opens if you confirm this query (Yes).
Select all the applications from the list in which the names
should be replaced.
If you decide that objects that are used in other objects
should not be renamed, you can cancel the "Replace
use" dialog. In this case, only the object itself is
renamed.
If a Workflow uses the same task several times, all
these tasks are replaced.
Entries can only be replaced in Include objects and
Process tabs if the UC4 administrator has activated
the SEARCH_SCRIPT_FOR_USAGE key in the
UC4 Variable UC_CLIENT_SETTINGS. Otherwise, a
warning is displayed.
You cannot replace Users in User-Group objects. This
is a security measure that serves to prevent from a
regular User being assigned to a group that has
administrator rights. However, you can replace users
in other objects such as Notifications.

Print

Highlight the object that should be printed and use the


symbol in the toolbar. To select another printer than your
default printer, click the symbol. A print preview opens.
Click the
symbol again and select the printer of your
choice.

The availability of the individual UC4 Explorer functions that are described above depends on
authorizations.
Different users of a client can use completely different folder structures. This includes that
commands that are activated through the UserInterface's menu or the UC4 Explorer's context
menu depend on the objects that are currently highlighted.

60

Chapter2 UserInterface

See also:
Context menu of the UC4 Explorer

2.7.2 Context Menu of the UC4 Explorer


Various commands are available in the context menu depending on the object type and privileges
that have been assigned. Highlight one or more objects in the right half of the UC4 Explorer
window and right-click the mouse in order to open the context menu.

Command

Description

Activities Window

Opens a separate Activity Window for each highlighted object.

Delete

Moves highlighted objects to the UC4 Recycle Bin.

Delete Link

Deletes the highlighted links.

Duplicate
Duplicate to...

Duplicate creates an identical object in the same folder. The command


Duplicate To... creates a copy of the highlighted object(s) in a
selectable target folder.

Edit

The command Edit opens the selected objects.

Explorer

Opens the folder in a new Explorer window.

Export...

Exportsthe highlighted objects to an XML file.

Export to file...

Exports the Explorer window's content to an Excel file (explorer.csv).

Forecast...

Opens the option window for each highlighted object and a forecast
can be created.

Immediately

Processes the highlighted objects.

Import...

Imports objects to an XML file.

Last Report

Opens the last report of each highlights object.

Link to...

Creates a link of the highlighted object in the selected target folder. If


the object was only available in <No Folder>, it will no longer be
displayed as this folder only contains objects that are not available in
other folders.

Move to...

Moves the highlighted objects to the selected target folder.

New

Opens the template window and a new object may be created.

Once...

Opens the option window of each highlighted object for a single


execution.

Open

Opens the highlighted folder.

Open home folder

This command is only available for links. It opens an Explorer window


which displays the folder in which the object is stored.

Print
Print...
Print Preview

This command prints the highlighted object(s) including all its specified
settings. Use the command Print... or Print Preview to view the page
that will be printed beforehand.

Properties

Opens the properties window of the highlighted objects.

Automation Engine

61

Recurring...

Opens the option window of each highlighted object for recurring


execution.

Refresh

Updates the Explorer window.

Rename Object

Opens a text field for each highlighted object in which you may define a
new name or title.

Replace...

The Replace use dialog opens and lists all objects in which the
highlighted object is used.

Restart...

Opens the option window of each highlighted object for a restart.

Search...

Opens the search and sets the highlighted folder as search path.

Search for Use...

The Search dialog opens and you can search for objects by using the
highlighted object (such as a Workflow or Schedule).

Send To

If the UC4 administrator has defined calls for external programs or


internal objects in the UC4 Variable UC_SENDTO or UC_SENDTO_
ACT, the context menu of the UC4 Explorer additionally contains the
menu Send To. You can select the program or object to be called from
the submenu.
The codes of the previously highlighted objects are transferred to it for
further processing.

Set home folder

The object and the link from which this command is called swap places
with each other.

Statistics

Opens the statistical overview of each highlighted object.

Sync Monitor

Opens the Sync Monitor which displays the current status of the
highlighted Sync object and its usage through tasks.

Transport

Moves the highlighted objects to the Transport Case.

Up

The Explorer switches to the superordinate folder.

View:
Details
List
Large icons

You can use this command in order to have the objects that are shown
in the Explorer windows displayed in a different form. They can be
displayed with large icons, as a list or with details.

Note that the availability of the functions that are described above depends on authorizations.
This includes that within the very same client, different functions are available for different
users.

2.7.3 UC4 Recycle Bin


This document describes how to use the Recycle Bin in the UC4 Explorer. The Recycle Bin
includes objects that have already been deleted.
The following methods can be used to delete objects:
l
l
l

Highlight object(s) and press the


button in the tool bar.
Highlight object(s) and select Delete in the Edit menu of the UserInterface or popup menu.
Highlight object(s) and drag and drop them to the UC4 Recycle Bin.

62

Chapter2 UserInterface
Note that objects that have been specified for transport and are located in the UC4 Transport
Case cannot be deleted.

whether a query is made when an object should be deleted depends on the specifications that have
been made in the UserInterface. A query always displays if an object is used in other objects.
Deleted objects are stored in the UC4 Recycle Bin and obtain an extended name. A system-internal
number is appended to the object name. You can restore deleted objects by highlighting one or more
objects in the UC4 Recycle Bin and selecting Restore in the Edit menu of the UserInterface or
context menu. The deleted object is restored in "No Folder". You can also restore an object directly
to a specific folder. Drag and drop the object from the open Recycle Bin to the UC4 Explorer folder.
A requirement for restoring objects is that no other object of the same name can be created after the
deletion process.
The objects in the UC4 Recycle Bin can be displayed with large symbols, as a list, or with details.
Additionally, you can sort the objects by their name, object type, object title and date of deletion. Do
so using the command buttons in the tool bar, the View menu of the UserInterface or the context
menu (right-click without highlighting an object). Simply click the column title in order to sort them in
ascending or descending order.

The UC4 administrator can limit the number of objects that should be displayed in the Recycle
Bin by using the entry TRASHBIN_SHOW_MAX in the UC4 Variable UC_SYSTEM_
SETTINGS.
Deleted objects that have been archived using the utility UC4.DB Archive are not available in
the UC4 Recylce Bin.
Only privileged users have access to the UC4 Recycle Bin.
Users who do not have "Access to the Recycle Bin" cannot (or only partially) use the described
functions, menu commands etc.

2.7.4 UC4 Transport Case


Objects can be exchanged between various UC4 systems or individual clients in the same UC4
system. The exchange process is composed of 3 phases.
There are two ways of selecting objects for transport:
l

Highlight the object(s) to be transported and select Transport from the File menu or in the
context menu.
Highlight the object(s) to be transported and move them to the open UC4 Transport Case
using the Drag & Drop function.

Automation Engine

63

Actually, the objects are not moved to the UC4 Transport Case, but copied and displayed there.
They are now registered for transport. The objects in the UC4 Transport Case can be displayed with
large icons, in list form, or with details. They can be sorted by name, object type, object title and
modification date. Do so using the buttons of the tool bar, the commands from the View menu of the
UserInterface or the context menu (right mouse click without highlighting an object). Objects can
also be sorted in ascending or descending order by clicking on the column title of the detail view.

Transport registration can also be canceled. Highlight one or several objects in the UC4 Transport
Case and remove then using the command Delete from the File menu in the UserInterface or the
context menu.
Note that the Transport Case's content is not displayed if it contains more than 50000 objects.
Use the command Remove All to remove objects from it.
Statistics and the last report are available for objects in the UC4 Transport Case. These objects can
be printed or viewed. The corresponding functions are available via the buttons of the toolbar, the
commands from the UserInterface's File menu or the context menu.
The UC4 administrator can use the utility UC4.DB Unload to unload the Transport Case of one
or all clients. It creates a text file which contains the data of all objects.
In order to assume the objects to a different UC4 system start the loading program UC4.DB
Load and select the required text file. The client to which the data should be loaded can be
specified in an extra window. The objects are then stored in the destination client at the same
location and with the folder structure as in the original client. If the folder does not yet exist, it is
automatically created.
Keep the following performance-improving notes in mind when loading many objects to a client:
l

There should be no activities running in this client in order to make sure that the Automation
Engine is not obstructed by database locks caused by the utility UC4.DBLoad.
Turn off Version Management and Revisioning as otherwise, a version is generated for each
loaded object which affects performance negatively.

Users and UserGroups can also be transported with their passwords then being reset to "pass".
While the Transport Case is loading, the included Users verify if all their UserGroups are available in
the destination client or in the Transport Case and create a link to them. A warning is written to the
log file of the utility UC4.DB Load if one or more UserGroups do not exist. When UserGroups are
loaded, however, the existence of Users is not checked and no links are created either. UC4
recommends transporting UserGroup objects in the first step and loading the User afterwards in a
separate transport file.

64

Chapter2 UserInterface
Transport Cases can be loaded and unloaded in each client. Note that loading system objects
(e.g. UC4 Variables) to system client 0000 can also affect other clients! An additional
information message is therefore displayed before the loading process starts.
Note that Users and UserGroups specified as operators should first be loaded to the client and
the Notification objects in a second loading process in a separate file. If these objects are
transported together, it could happen that users are replaced in the Notifications because the
utility starts searching the User objects of operators in the client.
This is also important when transporting authorizations on object level. The UC4 administrator
can specify that these are also transported using the start parameters of the loading program
UC4.DB Load. By default, the transport is canceled if the specified Users are missing. This
default behavior can be changed with the corresponding start parameters.
TimeZone objects that have been transported with the Transport Case are not automatically
assumed. Therefore, all calculations for objects using them are based on UTC. This affects all
time conditions such as Calendar settings or start times. This situation can be avoided when
any TimeZone object of your choice is opened and stored. In doing so all other TimeZone objects
are also refreshed.
Note that Calendar keywords of other Calendars that refer to the transported Calendar object
must also be transported! Calendars are re-calculated after each transport and this occasionally
causes error messages in the log file when the Calendar was re-calculated at a point in time
when the referred-to Calendar keywords had not yet been read. Such messages can largely be
ignored because there is a subsequent calculation of Calendar keywords without any manual
interference being required.
Only privileged users have access to the UC4 Transport Case. Users who do not have "Access
to the Transport Case" cannot use these functions, menu commands, etc.

See also:
Import and Export of Objects

2.7.5 Version Management for Objects


Version Management can be used in order to keep track of changes that have been made in
objects. Using it has the effect that objects are duplicated each time they are stored. The copy is
then available in the Version Management folder. Additionally, the Documentation tab of each
object includes a list of all object versions.

Automation Engine

65

The UC4 administrator can activate Version Management for each client in the UC4 Variable
UC_CLIENT_SETTINGS using the entry "Y" in the validity key VERSION_MANAGEMENT.
The UC4 administrator can also specify that Version Management is automatically activated
when the UC4 administrator turns on the logging for the Revision Report. Further information is
provided in the Administration Guide, utility UC4.DB Revision Report.
The name of the object version is structured as follows:
Original name.Suffix.Date.Time
Date and time are based upon the client's TimeZone and refer to the object's last modification. The
suffix can freely be selected and must not exceed 8 characters. It is specified by the UC4
administrator with the validity key "VERSION_MANAGEMENT_SUFFIX" in the UC_CLIENT_
SETTINGS. If the complete name contains more than 200 characters, the original name is replaced
byOH_IDNR_nnnnnnnnn.
Object versions that are duplicated via Version Management can be opened in write-protected form,
restored or deleted. Statistics and reports can also be accessed.
Version Management is available for the following object types:
l
l
l
l
l
l
l
l
l
l
l
l
l
l
l
l
l
l
l
l
l
l
l
l
l
l

Calendar
Connection
AgentGroup
Agent/Client Assignment
Cockpit
CodeTable
Documentation
Event
FileTransfer
Filter
Group
Include
Job
Login
Notification
Workflow
PromptSet
RemoteTaskManager
RA Solution
Schedule
Script
StyleSheet
Sync
User
UserGroup
Variable

Versions of Variable objects are only stored if a manual adjustment was made. No version is
stored if changes are made via script elements such as PUT_VAR.
As described above, the object versions are not only stored in the folder Version Management but
also in the object itself. A limited number of commands is available in the context menu (right mouse
click).

66

Chapter2 UserInterface

The following actions can be taken:


Command

Description

Restore

Replaces the object with the highlighted and stored object version.

Open

The object version is opened in write-protected mode and its attributes are
displayed.

Delete

Moves the object version to the Recycle Bin.

Properties

Opens the properties dialog of the stored object version.

Refresh

Refreshes the view.

The UC4 administrator can irrevocably delete object versions via a database reorganization.
Data that should be deleted can be marked with a deletion flag by using the utility UC4.DB
Reorg. The unloading program UC4.DB Unload removes this data.
Note that by restoring an object version, this version obtains the current object name (even if the
old object version was named differently).
For example:
An older version of the Workflow MAM.DAY should be restored. The old version was originally
named MM.DAY. As a result, the restored Workflow has the content of MM.DAY but its name is
MAM.DAY.
The UC4 administrator can limit the number of objects that should be displayed in the Version
Management using the entry VERSIONS_SHOW_MAX in the UC4 Variable UC_SYSTEM_
SETTINGS.

See also:
Documentation Tabs

Automation Engine

67

The folder "Version Management" is only visible if the user has the appropriate privilege. Users
without "Access to the Version Management" can only use these functions, menu commands,
etc. through the Documentation tabs of the particular objects.

2.7.6 Favorites
The Favorites folder is a specific folder in the UC4 Explorer that cannot be moved or deleted.
You can use it to assign any objects to the user who is logged on and to various UserGroups.
This folder only stores the links to particular objects.
Favorites can be used to list particular UC4 objects per user in the Service Catalog and Process
Assembly part of the ECC (Enterprise Control Center). They are administered exclusively via
the UserInterface.
The Favorites folder includes a sub-folder for the user who is currently logged on. It is composed of
this user's first and second name. The name of the User object is used if the user name is not
available.
A folder for each UserGroup object is also listed. It includes the user who is logged on.
The privilege "Manage favorites on user group level" is required to administer the favorites of all
the client's UserGroups.

There are two methods to add favorites:


l

Select one or several objects in the Explorer and drag and drop them into the required
Favorites sub-folder.
Highlight one or several objects in the Explorer and call the context menu commands "Link Link to". Then select Favorites and the required sub-folder.

Note that write access (W)to USRG objects is required for objects to which favorites should be
added. This applies regardless of the privilege "Manage favorites on user group level".

2.7.7 Recent Objects


The "Recent Objects" section lists the current client's objects that the user who has logged in
has last used and/or modified.
This area displays a maximum of 50 objects with the most current ones being listed on top.

68

Chapter2 UserInterface
Note that the Last Used information (Header tab) is only updated if a value above 0 has been
specified in the setting LAST_USE (UC_SYSTEM_SETTINGS).

The Header tab displays the date, time and the user of the last object usage and modification. It
also displays the number of times that the particular object has been used and modified.
The term "usage" includes the processing of executable objects (activation by a user or parent
object). It also includes accesses of tasks to non-executable objects such as AgentGroups,
Variables or Calendars.

2.8 Search
2.8.1 Search
The search function can be used to select objects and folders in the UC4 Explorer according to
various criteria. Note that objects are displayed as specified in the dialog window. Search results
can be limited by using all the available tabs.
You can use the wildcard characters * and ? for entering names. * stands for any number of
characters, ? for one specific character.
UC4 recommends that you do not use wildcard characters at the beginning of object names.
Otherwise, the search process takes considerably longer.
Results are supplied in an extensive context menu. The Explorer command is very useful
because it opens the UC4 Explorer exactly in the folder in which the object you searched for is
available.
Keep the following information in mind if you use Oracle as the UC4 Database:
An error will occur if the characters +, -, /, : and # are used in combination in the Search fields
Search for Objects (Objects tab), Search for text and Search for Calendars (Further Options
tab). The order or position in which the characters are used is irrelevant. You can solve this error
by removing one of the above characters.

Objects
[Objects] [Date] [Further Options]

Automation Engine

69

Use the From Path input field in this tab and select whether you want to search the whole client
(default) or only one particular folder.
You can search for all object types or only for particular ones. Searching for the object types agent
and server only leads to a result in client 0000.

The search function can also be used to have all object types listed that use a particular object.
Select the option Usage of objects from the "Search for" list. Activating the check box "Include
Script" has the effect that the specified object is also searched in scripts. An even easier way to
open this type of search is using the Search for Use command in the UC4 Explorer in the selected
object's context menu.
Note that you can only use the option "Include script" when the setting SEARCH_SCRIPT_
FOR_USAGE has been set in the UC4 Variable UC_CLIENT_SETTINGS.
Search results are listed in the Search dialog. Right-clicking the mouse opens context menu for the
objects. It is very similar to the context menu of the UC4 Explorer. Objects can be edited, exported,
etc.
Date
[Objects] [Date] [Further Options]

70

Chapter2 UserInterface

The Date tab can be used to restrict your search to objects and folders that have been created,
edited or used in a particular period of time. Activate the desired option and specify a period. By
default, "No Date Selection" is activated.
Note that the latest use will only be updated if the setting LAST_USE is defined in the UC4
Variable UC_SYSTEM_SETTINGS (greater than 0). Otherwise, a search using the option Used
will either supply outdated results or no results at all.

Further Options
[Objects] [Date] [Further Options]

When searching for objects, you can also specify a text that should be searched in scripts,
Documentation tabs, object titles and/or in the Archive Keys of objects. You can also search the
contents of the specific values of RA objects (Jobs, Connections) by using the option RA Values.
Uppercase letters and lowercase letters are (no case sensitivity).
You can also search for Variable objects including their keys and contents. Contents depend on the
data type that has been specified:
l
l
l

String
Number
Time(hh:mm:ss)

Automation Engine
l
l

71

Date (yyyy-mm-dd)
Timestamp (yyyy-mm-dd hh:mm:ss)

The date, time and timestamp format that is specified in parentheses applies.
You can even search for Calendar keywords in this tab. If you also specify a date, keywords that
are valid on this very day are searched. You can open this specific function more quickly by using
the popup-menu command Search for Use of a Calendar keyword that is specified in the Calendar
object.
The search text automatically starts and end with the wildcard character "*". Therefore,
searching for MM also supplies results such as MM.DAY or UC4.MM.CLOSING.
The text that should be searched can also contain the wildcard characters "*" and "?". You
cannot search for exactly these characters.

See also:
Search for Object Usage
Searching and Replacing Texts

72

Chapter2 UserInterface

2.8.2 Searching for Object Usage


The search-for-use function can be used to find objects. It can even be used to search for the
usage of particular objects. For example, if the indicated job is part of a workflow, the search
result shows this particular workflow.
Click the Objects tab and select "Usage of objects" in the "Search for" section in order to search for
object usages. Object name and type should also be specified.
This search function can be accessed even more easily by highlighting the object in the UC4
Explorer and selecting the command Search for Use in the context menu. The Search window
opens with the required information already being inserted. The search starts immediately with
all folders by default.

In script, the search-for-use function is deactivated by default and the checkbox "Include Script"
is grayed out. The UC4 administrator can activate this functionality in the UC4 Variable UC_
CLIENT_SETTINGS using the key SEARCH_SCRIPT_FOR_USAGE. Two methods are
available:
1. The searched string must be somewhere in the script as otherwise it cannot be displayed.
For example: The search for MM lists results in which it is included as a whole or partially.
l MM
l MM.CLOSING
l UC4.MM.DAY
2. The searched string is handled as a word which is enclosed in delimiters such as blanks, left
and right parentheses, equals (=), comma, single quotations, double quotations, end of lines
and script ends.
Underscores are not delimiters. Searching for MM in _MM_ does not return a result.

Automation Engine

73

For example: The search for MM lists results in which it is enclosed in the described
delimiters.
l (MMI)
l =MM=
l 'MMI'
l (MM,
l =MM at the end of a line
When searching for Calendar keywords in scripts, the result only includes lines that include the
keyword as well as the name of the Calendar object.
Note that the search function does not find Calendar and Calendar keyword usages if the
settings of recurring task are concerned.
The Search function does not search a Calendar keyword in the Calendar object in which it has
been created.
For example: The Calendar object ON_CALL_DUTY contains the Calendar keywords MONDAY_
TO_FRIDAY and WORKDAYS. The latter one is a group-type Calendar keyword which contains
the Calendar keyword MONDAY_TO_FRIDAY. The result of searching the usage of MONDAY_
TO_FRIDAY does not include the Calendar keyword WORKDAYS because it is stored in the very
same Calendar object.
The search function does not find agent usages if the filter specifications refer to AgentGroups.
The search for use function also includes fields that include an object but have been deactivated
using a particular option and are grayed out. For example, Runtime tab - Else - Execute.
Note that the object type is not considered if the wildcards "?" and "*" are included in your search
for object names.
The "Use" column in the search result describes where the object was found. It contains for
example:
l
l
l
l
l
l

the task number in Workflows and Schedules,


"Login" in Login objects,
"Start type" in Groups,
the script line which contains the particular object name,
the tab when the object is used in the properties of a Workflow or Schedule object,
etc.

A special feature has been included in the search for usage: If you open an object that is shown in
the search result, the searched object is highlighted with a red frame. This feature is supposed to
make it easier to find the particular object especially in Workflows which contain many tasks.

74

Chapter2 UserInterface

A blue frame is used when the searched object was entered in the properties of a task (such as in
the Result tab). This can affect Schedules, Workflows and elements of Cockpits.

The colored frame highlights checkboxes of Workflows, lines in Schedules, elements in


Cockpits, text fields in which the object was entered and object names used in script lines.
See also:
Search
Searching and Replacing Texts

2.8.3 Searching and Replacing Texts


You can search for character strings in windows in which you can output and edit texts (such as
the report display, activation report, Process and Documentation tabs).

Automation Engine

75

Open the dialog by using the Search... command in the context menu (right mouse button) or the
shortcut CTRL + F.

You can enter a string or select one from a previous search list. Note that you cannot use wildcard
characters in this dialog. If you have highlighted a character string in the window before calling the
dialog, this string will be searched.
You can also specify that the character string should be searched as a whole word. If this check box
is not activated, all words that include this character string are displayed. You can also define the
search direction and a case-sensitive search.
When the string is found, the window displays the line in which the found string is highlighted. Click
Find in order to continue your search. A dialog box displays the end of the search or an
unsuccessful search.
In windows in which texts can be edited, a string can also be replayed by another one. Such
windows are the Process tab and object- documentation tabs.
All possibilities are applicable for locating a character string in an editable text window. Use the
Replace command to have each found string displayed and replace them individually. If a found
string should not be changed, select "Find next". "Replace All" replaces all found character strings.
A dialog box displays the completion of a replacement procedure or an unsuccessful search for a
string.
Calling the Search-and-Replace dialog
Menu Edit of the UserInterface

Select the Search command to call the dialog.

Right mouse button in the selected window

Select the Search command in the context menu .

Keyboard

Use the shortcut CTRL+F.

See also:
Search
Search for Object Usage

76

Chapter2 UserInterface

2.9 Activity Window


2.9.1 Activity Window
The Activity Window informs you about a client's tasks which have either been activated
manually or by a super-ordinate task. It displays the current status of a task beginning with its
activation and start until the transfer of its report.

The Activity Window is one of the UserInterface's main components, along with the UC4 Explorer
and the Message Window.
You can use several Activity Windows and filters within a UserInterface. In doing so, you can group
tasks of the same name, status or host on which they run in one window.
Click the buttonor use theActivities... command in the View menu and a window opens in which
you can specify filters for the Activity Window. By default, no filter is set, and all activities are
displayed. You can use the tabs in order to specify filters for various areas. Then click OK and the
Activity Window opens. The status bar displays your specified filter settings.
The UC4 administrator can limit the number of activities that should be displayed in the Activity
Window using the UC4 Variable UC_SYSTEM_SETTINGS. If the specified value is exceeded,
a message appears in the Activity Window's status line. UC4 recommends setting filters in the
Activity Window selection in this case so that tasks are arranged in groups and currently nondisplayed tasks can be viewed as well.
The Activity Window is divided into two sections: The left section includes all Queue objects of the
current client plus the corresponding states. Exception: The system client shows the Queue objects
of all clients. The right section includes the tasks plus the corresponding information. Select a
particular Queue object to have only the tasks that refer to this Queue object listed (filter for Queue).
The right window section lists tasks line by line. All activities that are shown in the Activity Window
can be sorted by column titles. Simply click one of them in order to sort them in an ascending or
descending order. You can also change the column order. Just click a column and move it while you
keep the mouse-button pressed.
Column

Description

Name

The object name or the alias name (if available) of the activated task.

Type

The object type of the activated task.

RunID

The run number of the task.


Comments are available in tasks in which the RunID shows a small red
edge.

Parent

The run number of the parent task that activated this task.

Status

The condition symbol and status of the activated task.

Automation Engine

Platform

The symbol and name of the platform on which the task is being processed.

Queue

The Queue object for the task.

User

The user who has activated this task.

Start Time

The time when the task has been started.

Priority

The priority that has been used to execute the task.

Host Name

The name of the agent that executes the task.

User ID

The login data to the computer on which the task is processed.

Start Type

The start type of the activated task.

Process ID

The identification of the process on OS level during the execution.

CPU Time
(sec)

The consumed CPU time in seconds.

Archive 1
Archive 2

The object's first and second archive key .

Consumption

The object's resource consumption (can be specified in the Attributes tab).

Runtime

The time that has past since task has started.

End time

The point in time when the task has ended.

Modification
flag

In Workflows that have been modified during their runtime, this column includes
a pencil symbol and the name of the user who has made the last modifications.

Remote
Status

This shows the status of an SAP or RA job has in its applicatio. This column is
empty if no status is available.
For example: An SAP job. UC4 status:"Active", status in the SAP system:
"Released" (it appears in the "Remote Status" column).

77

The Activity Window's content is refreshed on a regular basis. The corresponding interval can be
determined in the settings of the UserInterface. Pressing the F5 key immediately refreshes the
content.
Various functions such as statistics of tasks are available via the context menu.
Use the shortcut CTRL + F to open the quick-search function in the Activity Window.
In the Activity Window, the context menu shows the additional item "Workflow" for tasks
running in a Workflow. This menu item contains all the commands that can also be called in the
Workflow Monitor. The following commands are available:
l
l
l
l
l
l

Go Immediately
Set Breakpoint
Delete Breakpoint
Skip Task
Unskip Task
Unblock Task

In the Activity Window, you can access several objects at the same time using multiple selection.
Use the shift key to highlight a specific range of objects. Keep the CTRLkey pressed in order to
select objects that are not directly positioned above or below each other. You can also right-click the
mouse in order to work within a highlighted range. Only menu commands that can be used with all
the highlighted objects are available.

78

Chapter2 UserInterface

Activity Window Views


The Activity Window can be displayed in two different views.
l
l

List view
Hierarchical view

The first view displays all tasks in list form as the following illustration shows:

The list view becomes unclear if many tasks are displayed. Therefore, the hierarchical view is used
in the Activity Window by default. This view groups tasks that have a common main task (parent).
Main tasks (parents) can be:
l
l
l
l
l
l

Workflows
Schedules
Groups
SAP jobs with their sub-jobs
Wildcard FileTransfers
Escalating Notifications

The hierarchical view does not only structure the information, it also reduces the Server's
workload.
The hierarchical view groups subordinate tasks and also several restart runs of the same task. The
last restarted run represents the main node. When you expand it, all the previous restart runs will be
listed.
Expanding a parent task in the hierarchical view will list its direct subordinate tasks. If this list
includes a sub-workflow, you must also expand it in order to see its child tasks. Note that collapsing
or expanding workflows does not automatically refresh the view. For this purpose, you can use the
Refresh command in the Activity Window.
You can switch views by clicking the

button.

In the hierarchical Activity Window, the selection criteria only affect first-level parents.
Ended tasks of Schedules that have not yet been deactivated after a period turnaround are
handled as first-level tasks and not as scheduled tasks in the Activity Window. The reason is
that the Schedule obtains a new RunID with each period turnaround and is no longer the parent
of these tasks.

See also:

Automation Engine

79

Activities Window Selection


Context menu of the Activity Window
Updating UserInterface Windows

2.9.2 Activities Window Selection


Objects that should be displayed in the Activity Window can be selected in the dialog window
"Activities window selection".
Activate the Activity Window and use the Options... command in the View menu of the
UserInterface. You can also open this dialog window by right-clicking the Activity Window without
highlighting an object. The dialog window opens automatically when a new Activity Window is
called. Selections that are made for an open Activity Window are displayed immediately.
Note that objects are displayed according to the search criteria that are specified in the dialog
window. You can limit the search results by using the available tabs.
You can exclude particular terms or filters using negative filters with the option NOT. Doing so is
possible in all tabs (except for "Status"). Note that negative filters are ignored and no exclusion
is made if the character * is used in the relevant text field.
Objects
[Objects] [Status] [Host] [User] [Archive Keys]

In the Objects tab, you can specify a title for each Activity Window. It is then displayed together
with "Activities". This helps you keep track of activities when you use numerous Activity Windows.
Here, you can select object types whose states are supposed to be displayed in the Activity
Window. Simply click the check box in front of the object types. Quick and easy selection is
possible by using the toolbar buttons "Select All" and "Unselect All".
You can also set a filter so that only objects are displayed whose names correspond to this filter.
With the default entry * being set, all objects are listed. Use the wildcard characters * and ? in order
to set a filter. * stands for any number of characters, ? for exactly one character. You can also select
the option NOT in order to have all tasks displayed that do not correspond to the specified filter.

80

Chapter2 UserInterface

Status
[Objects] [Status] [Host] [User] [Archive Keys]

You can select objects according to particular conditions in the Status tab. The four different states
are ANY_ABEND, ANY_OK, WAITING and ACTIVE. States that are displayed in gray indicate
that not all sub-categories were selected.
When you set filters, ensure that only active tasks are displayed. Note that you must deactivate
objects manually when their Attributes tabincludes the setting After error-free end of
program or Never deactivate automatically when finished. Otherwise, they will remain in the
Activity Window and can negatively affect performance and the Activity refresh cycle if many
tasks are affected.
You can also filter for the remote status of tasks. You can use this function for SAP, database and
RA jobs and for the SAP RemoteTaskManager.
In SAP jobs, the SAP RemoteTaskManager and database jobs, you must define the message
number of the remote status. The following values are possible:
SAP:
l
l
l
l
l
l
l
l

DB:

2004972 - Waiting for SAP Server


6500 - scheduled
6501 - released
6502 - ready
6503 - running
6504 - finished
6505 - canceled
6514 - hold

Automation Engine
l

81

2012025 - Waiting for Database

To filter for the remote status of RA jobs, you must specify it in the Filter for inserts field.

Host
[Objects] [Status] [Host] [User] [Archive Keys]

The Host tab can be used to define that the Activity Window only displays tasks that are executed
on particular hosts. You can either specify a particular host name or use a filter in order to select
several hosts. The wildcard characters "*" and "?" can be used. The default value "*" has the effect
that the tasks of all active hosts are displayed.
You can also select particular host types. In this case, the Activity Window only displays tasks that
have been started on particular platforms.
The setting "NOT" displays the activities that do not correspond to the determined host selection.
Note that you cannot filter for agent groups because the agent group will already be resolved and
the effective agent be entered in the task when processing takes place.

82

Chapter2 UserInterface

User
[Objects] [Status] [Host] [User] [Archive Keys]

You can use the User tab in order to select tasks that have been started by particular users or
departments. Two selection types are available.
Selection by filter: Sets filters that select several users or departments. You can use the wildcard
characters * and ?. By default, * serves to display the tasks of all users.
Selection by user: Selects a particular user from the list to have his/her tasks displayed. For
reasons of clarity, this selection type is not available in the system client 0000 because it provides
access to all clients and their users.
Select the option NOT in order to exclude a user name or filter.

Automation Engine

83

Archive Keys
[Objects] [Status] [Host] [User] [Archive Keys]

The Archive Keys tab can be used to limit the tasks that should be displayed in the Activity window
to those that have specific archive keys. You can either enter a particular archive key or set filters
for archive keys. Use the wildcard characters * and ? for filter selection. * refers to any number of
characters and? to exactly one character. The default entry * displays all tasks.
You can also specify that both archive keys (AND relation) or only one of them (OR relation) should
apply. The latter option can only be selected if there are two archive keys.
Activate the checkbox NOT in order to select only tasks that do not include particular archive
keywords.

84

Chapter2 UserInterface

See also:
Activity Window

2.9.3 Context Menu of the Activity Window


Right-clicking with the mouse opens the context menu. The available commands depend on the
currently highlighted objects and the corresponding rights and privileges. The following table lists
all the available commands in alphabetical order.

Command

Description

Cancel and Cancel


(recursive)

Cancels the task and its subordinate tasks (such as a workflow).


Cancel (recursive) also includes running tasks.
Workflows that have been canceled recursively obtain the status
ENDED_CANCEL. Schedules end with ENDED_OK.

Collapse All

Closes all open branches of the tree structure in the hierarchical Activity
Window.

Comments...

Opens a task's comment window.

Automation Engine

Deactivate

85

Removes tasks that have already finished from the Activity Window.
This command can only be used for:
l

Individual tasks (they do not run within a workflow) that have


already ended
Workflows that do not include active tasks.

The deactivation process of workflows always includes all subordinate


tasks.
Deactivate (forced)

Available for finished workflows that do not include any active tasks.
This command deactivates the workflow without considering
superordinate workflows and it ignores the defined options for automatic
deactivation.

Delete Entry

Deletes the task that is waiting for the start of its group.

Detail

Displays a task's Detail Window.

Edit

Opens the corresponding object for processing. Note that changes


apply for all executions and not only for the current one.

Enforce Pre-Condition
evaluation

Restarts the evaluation process of the Preconditions tab of workflow


tasks. The time interval (CONDITION_CHECK_INTERVAL - UC_
SYSTEM_SETTINGS) is reset.
This command is only available for workflow tasks that are in the status
"Waiting for Preconditions".

Explorer

Opens an Explorer window that displays the folder in which the object is
stored.

Export to File

Exports the current view of the Activity Window to a CSV file. By


default, the name of the exported file is activities.csv.

Filter

Calls a filter that can be used to define the view of the Activity Window.

Forecast

Creates a new Forecast for the task.

Go and Go recursive

Go starts the processing of workflows (sub-workflows are exempted),


schedules, events or Queue objects. Doing so has the effect that tasks
which were in a waiting condition now start.
Go (recursive) includes the tasks and sub-workflows.

Ignore / Consider
Agent Resource

Has the effect that the resources of this task are not checked or
checked again.
The task starts immediately if it is in the status "Waiting for
resource".

Ignore Pre-Condition

Preconditions of workflow tasks are no longer checked or deactivated.


This command is available for all workflow tasks that have not yet
started.

Ignore Queue limit

Starts a task immediately which is in a waiting condition because of


missingQueue slots ("Waiting for Queue slot").

Ignore SYNC

Specified Sync objects are ignored in this task.

86

Chapter2 UserInterface

Modify status
manually

Changes the task's current status.

Modify task
parameters

This command opens the task's PromptSet dialog in which you can
modify the prompt values subsequently.
When the option Request task parameters is activated in RA jobs
(RA tab), you can also modify the RA-specific values by using the
PromptSet dialog.
An error message will appear when no PromptSet objects are assigned
to the task or when the task is not an RA job in which the option
Request task parameters is set.
While the task is being modified, it changes to the status Waiting for
user input.
Modifying values after the task has been generated has no effect.

Modify UC4 Priority

Changes the UC4 priority. Further information is provided in the


document UC4 Priority.

Monitor and Monitor


Parent

Opens the monitor of the task (only applies for notifications, cockpits,
groups, workflows, schedules and syncs) or the monitor of the
superordinate task.

Open for
modifications

Opens the highlighted workflow in the monitor's editing mode.

Open Generated Job

Displays the result of a generated job.

Quit

Ends active Cockpit and Schedule objects.

Refresh

Refreshes the view.

Reload definition at
period turnaround

Possible changes in the Schedule object are assumed at the next


period turnaround.

Report

Calls the task's current report.


Event objects show the report of the Event (!Process) that has last
been executed.

Restart

You can restart tasks that have already been executed and specify
options.

Send To

If the UC4 administrator has defined calls for external programs or


internal objects in the UC4 Variables UC_SENDTO or UC_SENDTO_
ACT, the Activity Window's context menu includes the menu Send To.
You can select the program or object that should be called from the
submenu. The codes of the previously highlighted task are assigned to
them for further processing.

Statistics

Calls the statistics of the task.

Stop and Stop


recursive

Workflow tasks are stopped with the exception of sub-workflows which


remain active. Stop recursive includes tasks and sub-workflows.
The Stop command is also available for Queue objects. It causes the
object execution to come to a hold.

Automation Engine

Take Over Task

87

Tasks run under the User who has started them. They can be assumed
by any other User at any time and then be processed by this User. The
system verifies that the User who assumes a task has an execution
right for the corresponding object. If so, the task including all its child
tasks that are active or in a waiting condition are assumed. This
procedure does not affect tasks that have already ended. In this case,
the User is not changed.
The report of all involved tasks includes the information that the
User has been changed.
Note that only the top task's execution right is verified. Ensure that
you have all the required rights and contact your UC4 administrator
if you have any questions.
The privilege "Take Over Task" is required; otherwise this command
is not available.

Unselect All

Tasks are no longer highlighted.

Workflow Control

This menu contains commands which can also be called in the


workflow monitor:
l
l
l
l
l
l
l
l

Go Immediately
Set Breakpoint
Delete Breakpoint
Skip Task
Unskip Task
Unblock Task
Ignore Preconditions
Enforce Pre-Condition evaluation

See also:
Activity Window

2.10 Comments in Tasks


The UC4 system logs everything that happens in the form of messages, reports and statistical
records. Comments can also be stored in tasks. In doing so, you can comment on modifications
at runtime or peculiarities that occurred while the task was executed. Reactions to Notifications
can also be stored.
Comments refer to an individual object execution and are part of the statistical record.
Comments can be added and read in the following windows:
l
l
l
l
l

Activity Window
Statistics
Workflow monitor
Schedule monitor
Notification monitor

Call the comment window using the Comments... command in the popup window.

88

Chapter2 UserInterface

The upper window section shows the entries that have been made so far. They are listed in
chronological order with the latest one being on top. Each comment includes date, time and user
name. They are automatically stored and provide a well-structured history. Comments cannot be
changed later on.
A comment including line breaks can comprise of up to 1024 characters. Longer texts are
automatically truncated. The number of commenting entries is not limited.
Tasks including comments show a small red edge which is displayed together with the RunID. The
following illustration lists tasks in the Activity Window:

If Workflows, Schedules and Notifications include comments, then a red edge is shown in the
upper left edge of a monitor.
Comments added to restarts are stored in the object's original execution. Thus, restarted tasks do
not have red edges. Calling the comment window opens the original execution's history.

Automation Engine

89

Comments refer to an execution. Hence, comments in Schedule tasks are no longer displayed in
monitors after a period turnaround. The statistics, however, provide access to comments at any
time.
The search for statistical records can be limited to tasks which include comments.
These task comments can be read in system client 0000. Text cannot be added.
Note that the user right S (access to statistics) is required for viewing task comments. To write a
comment, you require the rights S and M (modification at runtime).
The archiving process for statistical records includes comments. The UC4 administrator can
view these texts using the UC4 Archive Browser.
Script
UC4 provides script elements which can be used to handle comments in an automated form:
Script element

Description

:ADD_COMMENT

Adds a comment to a task.

PREP_PROCESS_
COMMENTS

Prepares the processing of a data sequence (comments of a


task).

See also:
Activity Window
Statistics

2.11 Message Window


The Message Window displays information and error messages. The Message Window is a
main component of the UserInterface's user interface like the UC4 Explorer and the Activity
Window.
Open the Message Window by clicking the
button or select the Messages command in the View
menu. While the Message Window is displayed, the toolbar button remains pressed and the menu
command is checked. Click the command button again or select the appropriate menu command to
close the Message Window.
As opposed to the UC4 Explorer and Activity Window, there is only one Message Window. The
colored bars next to the message texts refer to connections to other clients. You can specify that a
closed Message Window opens automatically when a new message arrives. Error messages are
displayed in red because of their importance.

90

Chapter2 UserInterface
The font size can also be modified using the CTRL key in combination with the scroll wheel. It is
then kept even if the Message Window is closed. Modifications are lost if the UserInterface is
closed.

There are several types of messages


l
l
l
l

Personal messages - These belong to a particular user.


Client-wide messages - These are notifications such as agent starts or stops.
System-wide messages - These are administrator messages.
Security messages - These include accesses which underlie the conditions of the Authority
System.

All occurring messages are stored and can be viewed in the System Overview (category
messages).
In the Message Window, you can search for character strings. Open the search dialog with the
command button in the tool bar or use the shortcut CTRL + F.
Various options can be selected in the Settings of the UserInterface in order to reduce the number of
displayed messages. You can also select the maximum number of message entries that should be
displayed.
Unread messages
Administrator and security messages are usually not displayed unless an authorized User has
logged on to the UC4 system. Nevertheless, these unread messages can be collected and be
displayed in the Message Window at the next logon.
UC4 administrators can activate this function in the UC4 Variable UC_SYSTEM_SETTINGS
using the keys UNREAD_MESSAGES and UNREAD_MESSAGES_BUFFER.
This setting can also be used to specify the maximum number of unread messages hat should be
stored. The oldest message will be overwritten if this number is exceeded. An extra message
window opens immediately when you log on to the UserInterface and displays the available unread
messages. These messages are only displayed to Users who are authorized to obtain administrator
and security messages. The displayed messages are then considered as read.

The following list informs about all specifications that are required:
UC4 administrators:
l

The keys UNREAD_MESSAGES and UNREAD_MESSAGES_BUFFEREs must be set in


the UC4 Variable UC_SYSTEM_SETTINGS.
Additionally, users to whom unread messages should be sent must have the privileges
"View messages to administrators" and/or "View security messages".

Users:
l

Activate the option Show unread messages after logon in the settings of the
UserInterface.
The type of messages that is shown in the Message Window can be specified using
additional options in the UserInterface's settings (checkboxes "Administrator messages"
and "Security messages").

Automation Engine

91

Unread messages are lost if the UC4 system is restarted or the primary work process is
changed. As messages are saved anyway, they can be viewed in the System Overview
(category "messages").

2.12 Detail Window


2.12.1 Detail Window
The Detail Window provides extensive information about objects. This information can be called
in various areas of the UserInterface such as the monitor view of a Workflow and a Schedule, in
the Activity Window as well as in the statistics of executable objects and through Forecasts and
Auto Forecasts.

You can open the Detail Window's context menu by selecting an object and right-clicking it. Then
select the Details command.

92

Chapter2 UserInterface

The Detail Window provides substantial information and therefore, only the details that include
data are displayed. If there is no Last Message line, this particular line is not displayed. The
effect is that a clear structure can be kept. Note that this rule does not apply to the Sync Info tab.
The Object Variables area lists the names and values of all the task's PromptSet variables and
object variables.
Details in the Editing and Monitor View of Objects
The execution of a Workflow and Schedule can be viewed in the Monitor View. You can also open
the Detail Window here. Depending on the object type, it now contains various information grouped
in thematic blocks that can be expanded. The supplied information includes general specifications
such as the object's name, the run number (RunID) that has been assigned by the system, the
User, the current status etc. The other thematic blocks are object-type specific and include
information about the host or the time consumed, for example.

Automation Engine

93

Details in the Activity Window


Objects are displayed in the Activity Window while they are executed, unless different options have
been specified in the Activities window selection. Detailed information about all the Jobs that are
shown in the Activity Window can be viewed at any time. Just highlight an object and right-click it.
The popup-menu command Details opens the Activities Detail window. It contains the Task tab and
a second tab called Sync Info if a Sync object has been assigned to the particular object.
All data about the execution is displayed in the Task tab. Some data is always displayed, this is the
run number (RunID), the user who started the Job, start type, start time and status specifications.
Other displayed data depends on the respective object type. If a Sync object has been assigned to
the object, the particular information that refers to it is displayed in the Sync Info tab.
The Detail Window also shows the script line that is being processed. Note that modifications
that are made in the script after object start are not considered.
Details in the Statistical Overview
After a task has been executed, all relevant statistical and auditing data is stored in the UC4
system. Use the popup-menu command Details to call the statistical overview of data that refers to
the particular objects.
Data about the completion of an execution has been added to the available information in the details
of the Activity Window. General data includes the end time, the retention time (the time from a
task's start to its completion) as well as the times that have been supplied by the OS. Data such as
the size of a file or the number of records are type-specific.
Details in the Forecast Window
You can also open a Detail Window via Forecast window's list view. It contains general information
about the particular object, as well as the estimated data about its next start, end and status.
A Detail Window is also available for activities that are shown in the Auto-Forecast window.
Double-click one of them for more detailed information about the calculated forecast data.

See also:
Detail Window Contents

2.12.2 Detail Window Contents


The following table includes all entries that can be displayed in the various Detail Windows. The
entries are listed in alphabetical order so that they can easily be found.
In RA jobs, the Detail Window includes additional information depending on the particular
Solution (such as the Banner ID of a Banner Solution).
Entry

Description

Abend action

Sync action that should be processed if the task aborts.

Activator

RunID of the activator.

Activation

Activation date and time.

Archive 1

First archive keyword.

94

Chapter2 UserInterface

Archive 2

Second archive keyword.

Canceling

Identifies manually aborted tasks.

Changed by

Last object that has modified the Sync status.

Changed on

Date and time of the last modification.

Check count

Number of checks that have been made so far.

Code

Name of the CodeTable that is used.

Code (D)

Name of the CodeTable that is used by the destination agent.

Code (S)

Name of the CodeTable that is used by the source agent.

Compressed

Compression rate of the data that should be transferred.

Compression

Type of compression.

Consumption

Resources that the task consumes.

CPU time

Consumed CPU time in seconds.

Current State

Sync object's current status.

Destination
AgentGroup

Name of the AgentGroup object.

Earliest start

Earliest start date and time.

Else

Measures that should be taken if the task's runtime does not meet the
specifications.

End

Execution's end date and time.

End action

Sync action that should be executed when the task ends.

Ended with
error

Number of aborted tasks.

Escalation

Starting date and time for the Notification to escalate.

Event count

Number of Events that have already been triggered.

Event ID

First RunID of FileSystem and Console Events.

Express

Ignore agent resource.

External
Parent
Workflow

Name of the Workflow that contains the external dependency.

File name (D)

Path and name of the destination file(s).

File name (S)

Path and name of the source file.

File size

FileTransfer: File size indicated in bytes.


"-1" is displayed if the file size cannot be retrieved for any reason.

Files

Number of FileTransfer files that should be transferred in the format:


Transferred files / Total number of files
(Files that were not successfully transferred are included if the option "Abort at
first error" has been deactivated.)

Automation Engine

Filtering

Display of configuration for filtered processes in the Activity Window.

Host

Name of the destination agent.

Host (D)

Name of the destination agent.

Host (S)

Name of the source agent.

Job status

Status of the task.

Last check

Date and time of the last check.

Last
message

Latest occurring message including number and text.

Latest end

Latest end date and time.

Latest start

Latest start date and time.

Login

User ID that is used by the agent to log on.

Login (D)

User ID that is used by the destination agent to log on.

Login (S)

User ID that is used by the source agent to log on.

Max. parallel

Specification of the maximum number of tasks that can be processed at the


same time.

Max. parallel
running tasks

Maximum number of objects that can run in the group at the same time.

Maximum
runtime
(MRT)

Setting for MRT runtime monitoring.

Message

Message that informs about the task.

Message:

Notification's message text.

Minimum
runtime
(SRT)

Setting for SRT runtime monitoring.

Next check

Date and time for the next check.

Next start
time

Date and time for the task's next execution.

Number of
activated
tasks

Number of tasks that are started by the group.

Object name

Task's actual object name.


This name is different from the task name if an alias has been assigned
(possible for Workflow tasks and objects that are activated once and recurring).

Parent

RunID of the parent.

Period
(Days)

Duration of the period indicated in days.

Period
turnaround

Date and time for the next period turnaround.

95

96

Chapter2 UserInterface

Post proc.

Start date and time for Post Process execution.

Prio.

Priority of the task.

Priority

Priority of the Notification.

Process ID

Process identification on OS level during execution.

Processing

Scripting line that is being executed.

Program

Step on the OS that is being executed.

Records

Transferred file's number of records.

Reference
RunID

RunID of an execution that has already been executed and is used for the
restart.

Repeated

Number of repetitions if the expected status does not occur.

Rest. from

Name of the point from which the restart is processed.

Restart point

Name of the restart point that has last been passed.

Restarted

Number of restarted tasks.

Return code

Return code of the execution.

RunID

Run number of the execution.

Runtime

Duration of the execution.

Scheduled
check

Date and time in order to check whether the task should start.

Start

Start date and time.

Start action

Sync action that should be executed when the task starts.

Start Jobs

Indicates that the RemoteTaskManager starts scheduled Jobs.

Start type

Method that is used for the start.

Status

Task status.

Status text

Status description.

Status within
Parent

Status in the superordinate task.

Substatus

Additional information about a task's status. It is displayed if one of the "Else"


conditions that are specified in the Dependencies tab applies or if the
commands "Go immediately" or "Remove halt" have been used.
Allowed values:
"A" - Abort
"H" - Halt
"S" - Skip
"X" - Halt and abort signal
"G" - Go immediately
"R" - Remove halt

Successful

Number of successfully transferred files (FileTransfer).

System time

Consumed system time in seconds.

Automation Engine

Terminate
Queue
autom.

Indicates that the RemoteTaskManager ends automatically.

Time
Checkpoint

Date and time of the time checkpoint.

Timeout

Date and time of the first timeout that has occurred.

Title

Title text.

Total number
of errors

Total number of aborted tasks.

Total number
of tasks

Total number of tasks that are processed in the agent group.

Transferred

Part of the FileTransfer file that has already been transferred in the format:

97

Percentage (already transferred bytes / total number of bytes)


FileTransfers in the format "binary": The actual number of bytes is shown.
FileTransfers in the format "text": The displayed values exceed the actual
number of bytes. The file is transferred record-wise and the number of bytes for
each record length is added to the file size.
Under NSK, the agent cannot always correctly retrieve the actual file size.
Therefore, the displayed transfer status of FileTransfers is occasionally more
than 100%.
Type

Type Notification.

User

User object name of the person who has started the task.

User time

Consumed user time in seconds.

See also:
Detail Window

2.13 Forecasts
2.13.1 Forecast
Forecasts calculate the estimated runtime of executable objects. The calculated result is stored
in the form of forecast records.
Open the forecast windows by clicking the
View menu.

button or use the corresponding command in the

Usage
Highlight the object for which a forecast should be created. Execute the command forecast... which
is available in the context menu. The window shown below opens:

98

Chapter2 UserInterface

The object name is used as the forecast name. A run number is attached to the object name if a
forecast of this name already exists . The forecast name can also be changed. Note that it is not
possible to use an existing name for the new forecast.
Forecasts of type object and task are available. Type task is available if the forecast should be
created for an active task that is shown in the Activity Window.
l

Type object: The current day and time are pre-completed as starting points for the forecast.
You can change both of them and influence runtime calculation because Calendar conditions
are taken into account.
Type task: The RunID of an execution is required for the forecast. By default, the RunID of
the highlighted task is pre-completed. The execution date and start time are used. In
periodical tasks, the period for forecast calculation can be determined when a number of day
is specified.

A further specification is available if a Group or Groups are involved in the execution. You can select
how their runtimes should be included in the forecast calculation.
Click OK. The runtime is calculated and a forecast record is created. The forecast window opens
automatically.
Read more about forecast calculations in the chapter "Inside UC4".

Forecast Window
All existing forecasts are listed in this window. You can switch the table content's order by clicking
on a column's title bar.

Automation Engine

Column

Description

Name

Name of the created forecast.

User

User who has created the forecast.

Logical start

Specified starting date of the task.

Estimated end

Estimated end time of this task.

Status

Expected end status of this task.

Runtime

Average runtime of this task.

99

Context Menu
Command

Description

List View

The selected forecasts are displayed in the "List View" table format.

Rename

The name of the saved forecast can be changed.

Delete

The selected forecast is deleted.

Export to
file...

The forecast window's content can be exported to its own file with the extension
.csv.

Details
List
Large icons

Type of forecast display

List View
This view either shows selected forecasts in the form of a tree structure or in table form.

100

Chapter2 UserInterface

Context menu
Command

Description

Detail

The determined details for selected tasks are displayed in a special window.

Last Report

The last report for the selected task is displayed.

Statistics

The saved statistical data for a selected task is displayed.

Expand all

Opens all the tree structure's nodes

Collapse all

Closes all the tree structure's nodes

Expand

Opens selected nodes of the tree structure

Collapse

Closes selected nodes of the tree structure

Show/hide tree

The tree structure view is activated or deactivated.

Export to file...

Exports the list view's content to a CSV file

Script Elements
The script functions FORECAST_OBJECT and FORECAST_TASK are additionally available for
the creation of forecasts.

See also:
Knowledge Base - Forecast
FORECAST_OBJECT
FORECAST_TASK

2.13.2 Auto Forecast


The Auto Forecast can be used to see which objects are going to be executed next. At one
glance, you get the information which tasks will run next weekend or the following Monday
between 18:00 and 20:00, for example.
The Auto Forecast lists active Events and Schedules plus their included objects.
Open the Auto Forecast via the button or use the command Auto Forecast from the View menu.
The Auto Forecast can also be called via the script function AUTOFORECAST.

Automation Engine

101

Preparation Work Required by the UC4 Administrator


The following specifications must be made in order to enable the use of the Auto Forecast:
Define the keys AUTO_FORECAST_PREFIX and AUTO_FORECAST_DAYS in the UC4
Variable UC_CLIENT_SETTINGS. The Auto Forecast function stores its results in the form of
forecasts. The keyword AUTO_FORECAST_PREFIX serves to determine forecast names.
The number of days that is calculated to the forth is specified in AUTO_FORECAST_DAYS.
Use the selection criteria of the Auto Forecast to have particular tasks displayed that will run
within this period of time.If your forecast calculation has ended successfully, the key
CREATED is set in the UC4 Variable UC_AUTO_FORECAST. If the calculation is canceled,
the keyword is not set. Therefore, a message is displayed when the forecast calculation is
restarted and the key can be reset to the default value.

Use
Displaying tasks that will run in the future requires the prior calculation of forecasts. Click
Recalculate in the first step. The Auto Forecast uses the current date for the calculation of object
executions and creates forecast records for a particular number of days (see "Reparation work
required by the UC4 administrator").
Note that depending on the number of ongoing activities, AutoForecast data calculation can take
some time.
The Auto Forecast creates forecasts for all active Events and Schedules.
Selection criteria do not affect forecast calculations.
A calculations leads to the creation of Forecasts:

102

Chapter2 UserInterface

The period of time for which forecast records were displayed is shown next to the Recalculate
button. If required, start a new calculation.
The name is structured as shown below in order to ensure that Auto Forecasts can be distinguished
from other forecasts:
Prefix_object name_RunID:date
You can individually define the prefix (see "Preparatory work required by the UC4 administrator).
The prefix in the above illustration shows the name AUTO. Names end on the date on which the
task will be executed (format YYMMTT).
All other fields in the Auto Forecast window can be used to display particular tasks from within the
calculation period. You can select object type, object name or a particular date. The lower part of the
window displays tasks in accordance with the selections you made. The Detail Window can be
used via the popup window or to export the whole list to a CSV file.

Restrictions
The result of Auto Forecast calculations depends on the interval in which tasks are executed, on the
one hand. For Schedules - this is the period length; for Events - it is the time interval. On the other
hand, it also depends on the calculation period.
One Forecast per day is created for Events even if the Events run every 15 minutes.
Note that the following limitations apply for Auto-Forecast calculations:
l
l

l
l

With the exception of Events, only tasks planned within Schedules are considered.
Tasks that will be activated through other tasks (e.g. ACTIVATE_UC_OBJECT) are not
included.
It is not possible to identify dependencies of tasks on other tasks.
Modifications of attributes during runtime are not taken into account.

See also:
Forecast
Script element AUTOFORECAST

Access to the Auto Forecast is limited to privileged users. Users without the privilege "Access
to Auto Forecast" cannot use the described functions, menu commands etc.

Automation Engine

103

2.14 System Overview


2.14.1 System Overview
With the growing number of clients, users and other components of the UC4 system, such as
server processes or agents, a way of administering them centrally has become increasingly
important. The System Overview offers numerous ways and means of viewingand processing
your UC4 system's current status with many functions being provided.
The following information and more is available:
l
l
l
l
l
l

Display of workload
A list of all active and inactive server processes, agents and users
Access to their statistics and reports
Messages sent to users and administrators as well as security messages
Overview of the database in use
A list of licenses

Administrative access is also available for:


l
l
l
l
l

Closing Server processes


Terminating and deleting agents
Canceling user sessions
Setting trace options for server processes and agents during system operation
Changing values to the Server's input buffer

The information provided in the System Overview is always client-specific. It is possible to view
information about clients to which the UserInterface is connected.

The System Overview is split in two halves. The left half displays the different categories about
which information is available. The System Overview is handled like the UC4 Explorer. Select a
category using the mouse button. The right half displays the relevant information either in list form or
as an overview. The list form provides additional functions that can be used via the context menu.

104

Chapter2 UserInterface

Open the System Overview using the command of the same name which is available in the menu
System of the UC4 Explorer or with the

button on the tool bar.

The System Overview and particular functions are protected by UC4's Authorization System.
When using the multi-desktop mode, UC4 recommends opening the System Overview in a userdefined desktop as it always shows the same content in all desktops.

See also:
Usage
Clients
Servers
Agents
AgentGroups
Host Assignment
Users
Messages
Database
ILM
License
Cache
Exits
Quarantine

2.14.2 Usage
This category displays the workload of the UC4 Automation Engine processes in percent.
Values are available for individual clients as well as for the UC4 system as a whole.
Only clients in which executions take place and a workload actually exists are shown.
The privilege "View server usage of all clients" is required to view the workload of all clients
instead of only one's own.
The overview gives information about the workload occurring throughout a day. Reaction to an
increasing workload of the UC4 system is possible by adding Server processes. If the workload is
high due to the number of logged-on agents and UserInterfaces, the number of communication
processes should be increased. If the number of tasks in a UC4 system is increasing, the number of
work processes can be increased.

Automation Engine

105

The overview is split in two halves. The upper half contains a table with columns, each of which
stands for one hour. The headings show the respective time. Client data is displayed in lines - one
line per client (hourly values and average value). The last line shows the total workload of the UC4
system.
In the lower half, there is a diagram which shows the total workload in percent. The columns also
show the workload of one hour in percent. Directly below the diagram, the current date and time are
displayed. The time is additionally highlighted in red.
The values of particular Server processes are called up via the popup menu in the category Servers.

2.14.3 Clients
The category "Clients" of the System Overview of system client "0000" lists all clients of your
UC4 system. The System Overview of the particular clients, however, only shows one's own
client. Further functions are available via the context menu. You can open the statistics and
reports or the corresponding Client object for processing, for example. The commands for
starting or stopping a client are also found here.
Clients cannot be deleted or copied in the System Overview. The utilityUC4.DB Client Copy
serves this purpose.

106

Chapter2 UserInterface

Column

Description

Client

Number of the client

Title

Title specified in the Client object

TimeZone

Time zone valid in this client

Status

Displays whether the client is currently active or stopped

Number of
objects

Number of objects created in the client

Number of
activities

Number of tasks currently being executed

Number of
active users

Number of users who are currently logged on

MIB Monitor

Displays whether the client is subject to SNMP monitoring

MIB Info

MIB information of the client

Priority

Priority of the client the UC4 administrator specified in the UC4 Variable UC_
CLIENT_SETTINGS with the key "CLIENT_PRIORITY".

Task Priority

Priority of the client's tasks the UC4 administrator specified in the UC4 Variable
UC_CLIENT_SETTINGS with the key "TASK_PRIORITY".

See also:
Client
UC4 Priority

Automation Engine

107

2.14.4 Automation Engine/Server


This category lists all Server processes. Currently inactive processes are displayed with a white
symbol. You can open the statistics and the current report of a process via the context menu.
You can also end individual Server processes.

Column

Description

Name

Server process name including the patch level.


This name is a combination of the system name, #, process type and
the consecutive 3-digit process type number.

Type

Process type
C ... Communication Process
P ... Primary Work Process
W... Work Process
D ... Dialog Process
N ... NonStop Process

Version

Server process version including the patch level.

IP address

TCP/IP address of the server process.

Port No.

Server process port number.

Host

Name of the computer on which the server process is running.

B.01

Percentage of server process utilization during the last minute.

B.10

Percentage of server process utilization during the last 10 minutes.

B.60

Percentage of server process utilization during the last 60 minutes.

Process ID

Process identification number of the server process.

Time difference

Time difference between the computer on which the server process is


running and the UC4 system.

Server time

Date and time of the computer on which the server process is running.

108

Chapter2 UserInterface

Connections

This column shows the number of external connections. Internal


connections between communication processes and work processes
are shown in the ServiceManager.
Number of connections to the communication process (such as
UserInterfaces and agents).Connections to work processes are
exempted.
For work processes:
The value is always "0".

Role

Server role that the work process assumes.


Possible values:"O" and "R"
"O"- Output
"R" - Resource
Each role is only assigned once. Therefore, a work process does
not necessarily assume a role.
Communication processes cannot assume Server roles.

Net Area

Name of the Server processes' net area.


By default, this value complies with the name of the UC4 system. WPs
always run within the same net area.

Context Menu
Column

Description

Statistics or Report

Calls the Statistics or the last Report.

Edit

Opens the related Server-process object.

Start

Starts the selected Server process via a ServiceManager.


You can only use this option if a ServiceManager is available that
can be used to start the Server process. You must also enter
theServiceManager settings in the Server object either manually or
by using the command "Refresh Service Manager Scan".

Usage Chart

Shows the workload of the particular Server process

Change Logging

Causes the log file to be changed. In the properties, you can specify
that the log changes automatically.
Note that changing the log file of a particular work process implies
that the log file of all other work processes are also changed.

Server mode DWP /


Server mode WP

Changes the work-process mode from WP to DWP and vice versa (see
also WP_MIN_NUMBER)
WP ... Work Process
DWP ... Dialog Process
Attention: You cannot change a work process to a dialog process if
it performs a Server role (see Role column).

Automation Engine

109

Close

Closes the Server process immediately regardless of tasks that might


be running.

Workload

Opens the search (message analysis) or statistical overview (message


statistics of buffered Server messages). This menu item is only
available for work processes (WP, PWP or DWP).

Properties

Calls the "Properties" dialog (see below).

Refresh Service
Manager Scan

Refreshes the ServiceManager's connection settings for the selected


Server processes.
You must specify these settings if you start the Server processes via
the System Overview or the script element MODIFY_SYSTEM by
using a ServiceManager. You can use the Server object's Attributes
tab in order to show and manually edit these settings.
This scan is automatically made when the Server processes start for
the first time. It can happen that the service name that has been
entered in the Server object does no longer comply with the related
service name in the ServiceManager. In this case, UC4 recommends
running the"Refresh Service Manager Scan" command or entering the
relevant values manually.

Refresh

Refreshes the view.

Properties
The Properties command in the context menu opens a dialog in which you can specify various
settings. In the first tab, you can set and delete trace options. In doing so, you can log the behavior
of the UC4 Automation Engine even in exceptional cases. You do not have to shut down the Server
if you start tracing but your system's performance can decrease as a result thereof because traces
can create a log of data. UC4 recommends setting trace options only in close cooperation with UC4
Support.
In the trace options section, you can specify numerical values for the individual options. A short
description of the values is shown in the right window section.You can also specify more than one
trace option.

110

Chapter2 UserInterface

In the Properties tab, you can specify the general settings for the Server process and the values for
the Server input buffers. The window shows two parts. In the left part, you can specify a maximum
value. The right part shows the current usage (see also: Cache tab).

Automation Engine

Column
Server settings

CHANGE_
LOGGING_MB

Description
Values for Server settings are read from the UC4 Variable UC_
SYSTEM_SETTINGS. New values that are specified in this
UserInterface are only valid until the UC4 system is cold booted.
The UC4 administrator can make permanent modifications in the
UC4 Variable UC_SYSTEM_SETTINGS.
Size in MB at which the log file should be changed.
Allowed values: "1" - "32767"
You can also prompt the log file to be changed by using the script
element CHANGE_LOGGING.

CHANGE_
LOGGING_DAYS

Number of days after which the log file should be changed.


Allowed values: "1" - "32767"
You can also prompt the log file to be changed by using the script
element CHANGE_LOGGING.

111

112

Chapter2 UserInterface

RESERVED_API_
USERS

Number of user licenses that are reserved for accesses via the
CallAPI.
Allowed values: "0" - "32767"

MIN_EVENT_
INTERVAL

Minimum interval (in minutes) in which Events should be executed. An


Event can also include a value that lies below this minimum interval. In
this case, the system uses the interval that is specified in the Event.

LAST_USE

Time delay (in minutes) after which the usage counter of objects will be
refreshed (Header tab).

Server language

Primary language in which the login is made. This value is retrieved


from the Server's INI file.

SNMP in use

Displays whether SNMP is used. You can also specify this setting in
the Server's INI file.

Server cache
settings

Format: User-defined value / Current value

Script cache

Maximum size of the input buffer (Bytes) for Scripts.

Var cache

Maximum size of the input buffer (Bytes) for UC4 Variables.

MQMEM cache

Maximum size of the input buffer (Bytes) for themessage queues.

Object cache

Maximum size of the input buffer (Bytes) for objects.

User cache

Maximum size of the input buffer (Bytes) for users.

The third tab shows specific information about the Server process.

Automation Engine

113

Usage
You can also open a usage chart for the individual processes. The window that opens is structured
in the same way as the window that shows the workload of all processes.

114

Chapter2 UserInterface

Workload - message analysis


In this dialog, you can select specific Server messages by specifying criteria. Note that you can
only search for messages that are currently buffered. The number of messages that are buffered
depends on the setting MQA_BACK_COUNT in the UC4 Variable UC_SYSTEM_SETTINGS.
You cannot use wildcards for searching messages. UC4 recommends listing all messages before
you start a search (default setting) and then specifying the values for the fields that should be
searched. Each search field comes along with a corresponding column.

Automation Engine

115

Workload - message statistics


You can either open the message statistics for one specific work process (Statistics process
option) or for all process that comply with the type (WP, DWP or PWP) of the selected work
process (Statistics type option).
The statistics include the time that it took to send the message (time from sending to receiving it),
the Server load and the number of messages. The values are shown for all messages of a particular
type (Type column) of each selected work process and as a total sum of all listed types (--TOTAL--).

"Time Total" refers to the period of time that was required to process the messages. "Time
Minimum" shows the shortest time and "Time Maximum" the maximum time that was required to
send a message. The average sending time is shown in a separate column.
For example:
The following example shows the processing of 6 Server messages. The gray blocks symbolize the
time periods during which no messages were sent. The total time ranges from sending the first
message until the last selected message has been received.

See also:
Usage
Cache Usage

116

Chapter2 UserInterface

2.14.5 Agents
The category "Agents" lists all agents that are allowed for a particular client. Currently inactive
agents are displayed with a white symbol. All agents of the systemcan be viewed and agent
authorizations be changed in the System Overview of client 0000.

Column

Description

Name

Name of the agent.

Authenticated

Shows whether an agent has been authenticated.

Version

Agent version including patch level.

Platform

Platform on which the agent runs.

HW

Computer's hardware information (i.e. system type, number of


processors, processor type).

SW

Computer's operating system.

SW Version

Version of the operating system.

Last Check

Time of last check.

CP

Linked communication process.

Time Diff.

Time difference between agent and UC4 system.

IP Addr.

Agent's TCP/IP address.

Port No.

Agent's port number.

License Class

Agent's license class.

MIB

Agent's MIB information.

Service

Indicates if the agent is responsible for a specific service:


"MAIL" - E-mail connection
"SQL" (only for Database Agents) - Agent is responsible for dissolving
"SQL" type Variable objects.

Automation Engine

Compress

117

Compression type which is used for file transfers by default.


The UC4 administrator can define this type in the UC4 Variable
UC_HOSTCHAR_DEFAULT with the key "FT_COMPRESS".
If a different compression method should be used for a FileTransfer, it
can be changed in the FileTransfer object.

License category

Name of the license category assigned to the agent

Authorizations

Rights assigned to the agent.


"R" - Read
"W" - Write
"X" - Execute

Job res. max.

Resources the agent provides for Jobs.


Format: Currently used resources (maximum number of resources)
The UC4 administrator can specify the resource value using the key
WORKLOAD_MAX_JOB in the UC4 Variable UC_HOSTCHAR_*.

FT res. max.

Resources the agent provides for FileTransfers.


Format: Currently used resources (maximum number of resources)
The UC4 administrator can specify the resource value using the key
WORKLOAD_MAX_FT in the UC4 Variable UC_HOSTCHAR_*.

Keep alive

Time interval for periodical checks.


The UC4 administrator can specify the time interval with the key
KEEP_ALIVE in the UC4 Variable UC_HOSTCHAR_*.

Roles

Agent roles.
The UC4 administrator can determine role names in the agent
variable UC_EX_HOST_ROLE.

Last logoff

Agent's last logoff time from UC4 system.

Number of Clients

Number of user-defined clients in which the agent has particular


authorizations.

Linked

Indicated if the agents is linked to a ServiceManager which depends on


the settings made in the Agent object's Attributes tab.

Process ID

The agent's process identification number.

Net Area

The name of the agent's net area.


By default, the name of the Automation Engine system is used for this
value.

Context menu
Individual agent commands are available via the context menu. It is possible to access statistical
and report data, search for objects using the agent or disconnect the connection. All possible
commands are explained below:

118

Chapter2 UserInterface

Command

Description

Statistics or Report

Calls the statistics or the last report.

Activity Window

Opens the Activity Window with a filter to agent tasks.

Edit

Opens the corresponding Agent object.


This command is only available in system client 0000.

Start

Starts the agent via a ServiceManager.


This option can only be used if a ServiceManager is available for
starting the agent. Furthermore, it is required to enter the
ServiceManager settings in the Agent object either manually or with
the command "Refresh Service Manager Scan".

Disconnect Agent

Disconnects the connection on a temporary basis. The agent


reconnects to the UC4 Automation Engine as soon as the next signal
for agent checking is sent. Disconnecting an agent connection is
reasonable when a new communication process is started and the
agents rearrange themselves in order to have workload well-balanced.

Change Logging

Causes the log file to be changed. You can also use the script element
CHANGE_LOGGING for changing the log file.

Close

Closes the agent immediately regardless of tasks running .

Delete Agent

Deletes an inactive agent. It is moved to the Recycle Bin and can be


restored at a later time. Agent authorizations remain untouched.

Search for Use...

The Search dialog opens, in which you can search for objects using the
agent.

Replace...

The Replace Use dialog opens, listing objects that use the agent and
can therefore be replaced by another one.

Properties

Calls the Properties dialog (see below).

Export to File...

Exports the content of the agent list to a CSV file.

Refresh Service
Manager Scan

Refreshes the ServiceManager's connection settings for the selected


agents.
These settings are required for starting agents via the System
Overview or the script element MODIFY_SYSTEM using a
ServiceManager. The Agent object's Attributes tab can be used to
display and manually edit these settings.
It can happen that the service name which has been entered in the
Agent object does not comply with the corresponding service name in
the ServiceManager anymore. In this case, execute the command
"Refresh Service Manager Scan" or enter the relevant values manually.

Refresh

Refreshes the view

The following commands are only available in system client 0000. The UC4 administrator can
define the ones which should be displayed in the UC4 Variable UC_AS_SETTINGS.
Command

Description

Automation Engine

Export company key

Exports the company key to a file.

Authenticate Agent

Releases and agent for processing.

119

Subsequently, this agent can be used in your individual clients.


Withdraw
authentication

Locks an agent from processing.

Export authentication
package

Exports the authentication package to a file.

Renew transfer key

The transfer key must be renewed when the agent's keystore file has
been changed.

This agent is no longer available for processing in your clients.

Properties
The popup-menu command Properties opens a dialog in which you can specify various settings.
Trace options can be set or deleted in the first tab. In doing so, the agent's error behavior can be
logged. The agent does not have to be closed for a trace but system performance can decrease due
to the fact that a huge amount of data is created. UC4 recommends close cooperation with our UC4
Technical Support when setting trace options.
Enter the adequate number in the relevant trace option. It is also possible to specify more than one
trace option.

120

Chapter2 UserInterface

Agent settings can be specified in the lower part of the window. These are valid until the agent
connection is interrupted or ended.
The default value is specified by the UC4 administrator in the UC4 Variable UC_HOSTCHAR_
*.
Description

UC_
HOSTCHAR_
*

Max. resources Jobs:


Maximum number of resources the agent provides for Jobs (allowed values: "0"
- "100000"). The resource value is not checked if the checkbox is not activated.

WORKLOAD_
MAX_JOB

Max. resources FileTransfer:


Maximum number of resources the agent provides for FileTransfers (allowed
values: "0" - "100000"). The resource value is not checked if the checkbox is
not activated.

WORKLOAD_
MAX_FT

Automation Engine

121

Max Report blocks


Maximum number of report blocks to be stored in the UC4 Database (allowed
values: "1" - "10000").

MAX_
REPORT_
SIZE

Check interval
Time interval for the periodic UC4 Automation Engine check.

KEEP_ALIVE

The second tab includes information about agent variables.

Information

Description

HOST_HTYP_HW

Hardware information about the computer


(for example, system type, number of processors, or processor type).

HOST_HTYP_SW

Operating system of the computer.

HOST_HTYP_
SWVers

Version of the operating system or business solution.

HOST_CodeName

Name of the CodeTable object in use.

122

Chapter2 UserInterface

HOST_JCLVar

JCL variant (Job Control Language).

HOST_
HostAttrType

Type of the agent.

HOST_TcpIpAddr

DNS name or TCP/IP address of the agent.

HOST_TpcIpPort

Port of the agent.

HOST_Active

Shows whether the agent is active or inactive.


Allowed values: "0" and "1"
"0" - Agent is not active
"1" - Agent is active

HOST_JobCnt

Number of currently active agent jobs

HOST_MaxWaiting

Displays whether the value specified with WORKLOAD_MAX_JOB was


exceeded.
Allowed values: "0" and "1"
"0" - Value lies below WORKLOAD_MAX_JOB
"1" - Value was exceeded

HOST_Daylight

Retrieves if summertime applies.


When being started, the agent verifies whether summer or wintertime
applies.
Allowed values: "Y" and "N"
"Y" - Summertime
"N" - Wintertime

HOST_
LicenceClass

License class

HOST_Version

Agent version including hotfix level.

HOST_JobMd

Path of the job messenger.

HOST_PathBin

Path of the BIN directory.

HOST_
PathJobReport

Path of the directory in which the job report is stored.

HOST_PathTemp

Path of the Temp directory.

HOST_LoginMask

Mask for the login information.

HOST_
MibMonitoring

Shows whether the agent's availability is monitored.

HOST_LicCategory

License category.

See also:
Agent
>

Allowed values: "0" and "1"


"0" - The agent is not monitored
"1" - The agent is monitored

Automation Engine

123

2.14.6 AgentGroups
This area of the System Overview displays the AgentGroups of the own client and, if the relevant
authorization has been granted, of system client 0000.

Column

Description

Name

Name of the AgentGroup.

Client

Client in which the AgentGroup object is available.

Platform

Platform of the AgentGroup's agents.

Mode

AgentGroup mode.
"ALL" - All agents
"ANY" - Any randomly selected Agent
"FIRST" - First available Agent
"LOAD_DEPENDENT" - Depends on the workload
"NEXT" - Next listed Agent

Agents parallel

Maximum number of agents on which the task can be executed at the


same time.

Broadcast enforced

Check this setting if the task should be executed on all agents (mode
"All") including those that are not active at the time of activation.

Context menu
The context menu provides commands for individual or several AgentGroups.
Command

Description

Simulation

Lists all agents that belong to the AgentGroup in the simulation view.

Edit

Opens the corresponding AgentGroup object.

Search for use

The "Search" dialog opens which searches for objects that use the
AgentGroups.

Replace...

The "Replace use" dialog opens and lists all objects in which the
AgentGroup is used and can be replaced.

124

Chapter2 UserInterface

Disconnect Agent
connection

Temporarily disconnects the connection for all the AgentGroup's


agents. They reconnect to the UC4 Automation Engine as soon as the
next agent check signal is sent. Disconnection is useful when a new
communication process is started and the agents should rearrange.

Change logging

Triggers a log-file change for all the AgentGroup's agents. This is also
possible using the script element CHANGE_LOGGING.

Close

Immediately terminates the AgentGroup's agent regardless of running


tasks.

Properties

Calls the "Properties" dialog (see below).

Export to File...

Exports the content of the AgentGroup list to a CSV file.

Refresh

Refreshes the view.

Properties
The context menu command Properties opens a dialog in which you can define several settings. All
agents of the highlighted AgentGroups obtain these values when you click OK.
The properties window displays default values and not the actual agent settings.
The settings correspond to those that can be changed in the System Overview, section "Agents".

Automation Engine

125

Simulation view
The simulation and the button of the same name in the AgentGroup object list all agents that belong
to an AgentGroup. An arrow indicates the agent on which the next task will run.
The columns correspond to the ones displayed in the agents area of the System Overview.

See also:
AgentGroup

2.14.7 Queues
The System Overview item "Queues" lists all Queue objects including their states and settings.
The System Overview of client 0 displays the Queue objects of all clients.

Column

Description

Name

Name of the Queue object

Status

Status of the Queue object


"STOP" - The execution of Queue objects has been stopped.
"START" - The object can start in the Queue.
The Queue's max. slots have been set to value "0" and no tasks
can start.
You can change the status via the context menu of the System
Overview or the Activity Window.

Priority

Priority of Queue tasks.

Max.slots

Max. parallel-running Queue tasks. The displayed value always


complies with the object definition (Attributes tab).
Value "-1" signals that there is no Queue limit.

126

Chapter2 UserInterface

Used slots

Number of active tasks that occupy a position in the Queue object.


Note that this value can exceed the defined Queue limit (max.
slots) because of limit modifications or the execution of the
command "Ignore Queue".

Hold

Number of Queue tasks that have already reserved a slot but must not
start because of the stopped execution of a Queue, client or Workflow
(STOP).

Waiting

Number of Queue tasks that are in the status "Waiting for Queue slot"
(Queue status: STOP).

Consider ERT

The Queue object includes the setting "Consider Estimated Runtime


for Calculation".

Context menu
The following commands in this form are only available for Queue objects:
Command
Go
Stop

Modify

Description
Starts or stops the Queue's execution of tasks.
These modifications can also be made for several Queue
objects at a time. Doing so requires that only Queue objects
with the same status are selected.
Opens a dialog window that can be used to change a Queue
object's priority and max. slots. The current values are displayed in
the window.
Modifications that are made for these settings are only valid
until the next exception occurs or until a further manual
modification is made.

General commands:
Command

Description

Edit

Opens the relevant Queue object.

Activity Window

Opens the Activity Window with a filter. Therefore, only the tasks
of the selected Queue object are displayed.

Statistics and Reports

Opens the Statistics Overview or the last Report.

Search for usage

Opens the Search dialog which can be used to search for the
objects that have been assigned to the Queue object.

Replace

Opens a Replace Use dialog that lists the objects in which the
Queue object is used so that it can be replaced by another one.

Export to file

Exports the Queue's list content to a CSV file.

Refresh

Refreshes the view.

See also:

Automation Engine

127

Queue

2.14.8 Agent Assignment


This area is only available in the System Overview of client 0. It displays all Agent/Client
Assignment objects (HSTA). The upper half of the window lists all active objects, the lower half
all inactive ones.
Active objects do not run in the Activity Window, but are considered when an agent is assigned to a
client:
l
l

When the agent logs on to the UC4 system for the first time.
When you execute the "Execute host assignments" command in the HSTA object's
"Simulation" toolbar button.

You can move the HSTA objects to the active or inactive area in the System Overview either by
double-clicking them or by dragging and dropping them. You can click "Save" to assume your
changes or "Reset" in order to discharge all changes that have not been changed. When you switch
to another area of the System Overview, all the HSTA assignments that have not been saved will
also be reset without any additional query.
The HSTA object order affects the assignment of rights if the filters of several HSTA objects
overlap. The list is processed from top to bottom. If some filters overlap, the rights of the HSTA
object that is listed last is entered in the Agent object.
The UC4 Variable UC_AGENT_ASSIGMENT includes a list of all active HSTA objects. The
UC4 administrator can access this Variable.
If you want to delete an HSTA object, the system queries whether it should also be deleted in the
UC4 Variable UC_AGENT_ASSIGNMENT. HSTA objects that have already been deleted but are
still available in this Variable are displayed with an exclamation mark in the System Overview.

128

Chapter2 UserInterface

Description
Field/Element

Description

Name

Name of the HSTA object.

Title

Title that has been specified in the HSTA object, Header tab.

Context menu
Command

Description

For active HSTA


objects
Deactivate

Cancels the release of the HSTA object.


Inactive HSTA objects are not considered when an agent is assigned
to a client.

Move up
Move down

Moves the HSTA object in the list.

Edit

Opens the HSTA object.

Delete

Deletes the HSTA object.

Rename object

Opens a dialog in which you can specify a new name for the HSTA
object.

For inactive HSTA


objects
Activate

Releases an HSTA object.


Only active HSTA objects are considered when an agent is assigned
to a client.

Edit

Opens the HSTA object.

Delete

Deletes the HSTA object.

Rename object

Opens a dialog in which you can specify a new name for the HSTA
object.

2.14.9 Users
All a client's users are listed in the category User. All users of the UC4 system can be viewed in
system client 0000. Additional information is provided using the popup-menu command Details.
User sessions can also be canceled here. In doing so, the connection is immediately ended and
a message informs the user as soon as UserInterface work is continued.

2.14.10
Column

Description

Automation Engine

Name

Name of the user in the format Client/Name/Department

Last Name

User's last name

129

First Name User's first name


Version

UC4 system version including patch level

Language

Language selected at last user logon

Time zone

Time zone specified in User object

Session ID

Number of the user session

CP

Communication process to which the user is connected

Session
TimeZone

Time zone of the session

Last
session

Date and time of the last logon

E-Mail1

User's email address

E-Mail2

User's second email address

LDAP
connection

Indicates whether the User has specified the LDAP connection

Archive 1
Archive 2

Archive keywords which were entered in the User object

Remote
Identifier

This column shows when users have not directly logged on to the Automation
Engine system via the UserInterface but in another component.
Possible values:
"ECC" - Enterprise Control Center
"SVO" - Service Orchestrator
"PCO" - Policy Orchestrator
The version of the particular component is also displayed.

User States
Depending on specifications made in the User object, users can have several states. Current states
are displayed with a symbol in the column Name. A green symbol
indicates that the
corresponding user has logged on to the UC4 system and red
indicates that not. An additional
lock symbol
is displayed if a user has been blocked by the UC4 administrator for a repeated
wrong password specification. Logically, inactive users are no longer part of the UC4 system, this
situation is displayed with a canceled user symbol

The option is available to hide inactive users in the lower window edge.

Context menu
The context menu serves to open commands for one or several users.
Command

Description

130

Chapter2 UserInterface

Detail

Opens the Detail Window

Edit

Opens the corresponding User object

Statistics

Opens the statistical overview

Disconnect user

Disconnects the connection between User and UC4 system

Activate LDAP connection


Deactivate LDAP
connection

Activates or deactivates the LDAP connection for all specified


users

Delete

Deletes the User object


This command is only available for inactive users

Export to File

Exports the user list content to a CSV file

Refresh

Updates the view

See also:
User

2.14.11 Messages
This category can be used to recall messages that were displayed in the UserInterface's
Message Window during system operation. Numerous filter criteria are available. You can select
the settings that you required and confirm by clicking Start or pressing the return key in order to
start the search. The results are displayed in the lower window part.

Field/Control

Description

User

Name of the user who received the message.

Automation Engine

131

Admin

Select this check box if administrator messages should be included in your


search. Administrator messages are not assigned to a particular user (such as
system-wide messages).

Security

Select this check box if security messages should be included in the search.
They are created by the Authorization System's access control management.

Message type

The following message types are available:


Information
Warning
Error
Monitoring: successful
Monitoring: unsuccessful
The last two message types are only created if the UC4 administrator has
activated the access control in the UC4 variable UC_CLIENT_SETTINGS by
using the key "SECURITY_AUDIT_SUCCESS" or "SECURITY_AUDIT_
FAILURE".

Message
category

The following message categories are available:

Filter for
inserts

Search for strings within messages (such as UC4#WP001).

Date settings
(messages)
From - Until

Displays messages that occurred in the specified period of time.

Order
direction

Ascending or descending order of found messages.

Max number

Maximum number of messages that should be displayed.

Message, object access, host access, login and privilege.

Allowed values: "1" - "9999"


Date

Date and time at which the message occurrec.

Source

Message source. This could be the UC4 system or security monitoring.

Category

Message category.

Message type

Message type.

Message

Message text.

The easiest way to open a message is to double-click it. This is especially useful if the message
has been truncated and can only be read by scrolling through the System Overview. You can also
open a message by using the popup menu.

132

Chapter2 UserInterface

See also:
Message Window

2.14.12 Database
This category provides information about the database in use.

Field

Description

Database
DBMSName

Database

Version

Database version

DriverName

Name of the driver

DriverVersion

Version of the driver

DriverODBCVersion

Version of the ODBC driver

DBName

Name of the UC4 Database

ODBCConnString

Connection string to the UC4 Database

UC4

Automation Engine

InitialData Version

Version of initial data

Current MQ Records

Number of queued messages

MQPWP

Message queue of the primary work process

MQWP

Message queue of the work processes

MQDWP

Message queue of the dialog processes

MQMEM

Message queue for current activations

MQRWP

Message queue for outputs

MQOWP

Message queue for resource calculations

133

2.14.13 License
This category within the System Overview contains a list of all licenses that are used including
the corresponding information. The acquired licenses are supplied in a separate file and you can
load them to the database using the utility UC4.DB Load.
The license type is shown in the very first line of the overview. "T" stands for test system and "P"
for production system.

Column

Description

Platform

The license for the platform that is used.

Class

The license class that complies with the acquired license and hardware and
software.
Allowed values: "1" to "9", "S", "V"
"1" to "9" = The license class of the agent.
"S" = The agent that is used for administrative tasks on the Server computer.
"V" = The virtual license class for the agent.

Category

The category description of the license (such as Production).

Date

The date on which the license will expire.

134

Chapter2 UserInterface

Count

The total number of licenses for the platform.

Event

This is displayed if UC4.event has been licensed.

Processors

The number of allowed processors or users (depending on platform).

Restriction

A comment field for restrictions.

Used
(Host)

The number of licenses that are used.


Agents for Enterprise Business Solutions:
The number of running agents (total number of users who access them)
Other agents:
The number of used agents / number of used CPUs /Actual number of agents (
actual number of CPUs)
Server:
The number of used licenses (total number of actually running Server processes)
User:
The number of used licenses

License abbreviation
Column

Description

CN.DB.DB2

Database connection for DB2

CN.DB.ORA

Database connection for Oracle

CN.EBS.SAP.MON

UC4.Connect for SAP Monitoring

CN.MQ

UC4.Connect for WebSphere MQ

CN.OS.VSE

CallAPI for VSE

Company

The default line that is used for each license certificate.

DC

UserInterface

DC.WEB

WebInterface

EX.EBS.OA

OracleApplication agent

EX.EBS.PS

PeopleSoft agent

EX.EBS.SAP.BAS

SAP agent for Basis

EX.EBS.SAP.BCA

SAP agent for BCA

EX.EBS.SAP.BI

SAP agent for BI

EX.EBS.SAP.XI

SAP agent for XI

EX.EBS.SEBL.I

Siebel agent

EX.OS.BS2

BS2000 agent

EX.OS.GC8

GCOS8 agent

EX.OS.LNX.ZSE

z/Linux agent

EX.OS.MPE

MPE agent

Automation Engine

EX.OS.NSK

NSK agent

EX.OS.OS4

OS/400 agent

EX.OS.UNX

Unix agent

EX.OS.VMS

VMS agent

EX.OS.WIN

Windows agent

EX.OS.ZOS

z/OS agent

EX.SVC.CIT

Agent for Rapid Automation

EX.SVC.JMX.BOSS

JMX agent for JBoss

EX.SVC.JMX.NETWEAVER

JMX agent for SAP NetWeaver

EX.SVC.JMX.OC4J

JMX agent for Oracle Containers for J2EE

EX.SVC.JMX.TOMCAT

JMX agent for Tomcat

EX.SVC.JMX.WEBLOGIC

JMX agent for BEAWeblogic

EX.SVC.JMX.WEBSPHERE

JMX agent for IBMWebSphere

EX.SVC.SQL.ACCESS

Database Agent for MSAccess

EX.SVC.SQL.DB2

Database Agent for DB2

EX.SVC.SQL.MAXDB

Database Agent for MaxDB

EX.SVC.SQL.MSSQL

Database Agent for MSSQLServer

EX.SVC.SQL.MYSQL

Database Agent for MySQL

EX.SVC.SQL.ORACLE

Database Agent for Oracle

EX.SVC.SQL.SYBASE

Database Agent for Sybase

FW.OV.NNM

UC4.Connect for HP OpenView NNM

FW.OV.OVO

UC4 Smart Plug-In for HP OpenView Operations

FW.PTL.KM

UC4.Knowledge Module for BMC Patrol

FW.TME.PM

UC4.PlusModule for Tivoli

GL.DC

Global UserInterface license for opening client connections of


different UC4 systems

SRV.AIX

UC4 Automation Engine for AIX

SRV.HPX

UC4 Automation Engine for HP/UX

SRV.LNX.X86

UC4 Automation Engine for Linux

SRV.LNX.ZSE

UC4 Automation Engine for z/Linux

SRV.NS.AIX

UC4.Nonstop-Server for AIX

SRV.NS.HPX

UC4.Nonstop-Server for HP/UX

SRV.NS.LNX.X86

UC4.Nonstop-Server for Linux

SRV.NS.LNX.ZSE

UC4.Nonstop-Server for z/Linux

SRV.NS.SOL.SPC

UC4.Nonstop-Server for Solaris

135

136

Chapter2 UserInterface

SRV.NS.WIN

UC4.Nonstop-Server for Windows

SRV.SOL.SPC

UC4 Automation Engine for Solaris

SRV.WIN

UC4 Automation Engine for Windows

2.14.14 ILM
This area lists information about partitions and facilitates checks, switch-outs and deletions.
The System Overview only displays the area ILM if ILM has been installed and the User
privilege "ILM actions" has been granted.
The lower window part indicates whether ILM is active and shows the number of online partitions.
You can stop ILM, and in doing so you prevent future partition changes.

The Partition tab contains a list of existing partitions. You can delete staging tables
(MSSQLServer) or partitions which are no longer required (Oracle). The History tab displays a list
of removed partitions.
All partitions (the current one exempted) can be checked for statistical records of active tasks. The
result is a list of these active tasks which can be adjusted manually. On the Partition tab, call up
the context menu of the particular partition and select the option Check partition. This checklist
includes a further context menu which opens when your right-click a task.
The context menu provides an additional command for MS SQLServer which can be used to trigger
a switch-out for a partition without statistical records of active tasks. A switch-out is always made
for the oldest partition, regardless of the partition checked in the list.

Automation Engine

137

Partition tab
Column

Description

Partitionno.

Running number of the partition


Staging tables (MSSQLServer) always have the partition number "0".

Parent

Displays the schema name (MS SQLServer) or the corresponding


main table of the UC4 Database (Oracle).

Filegroup
/Tablespace

Name of the filegroup (MSSQLServer) or the tablespace (Oracle)

Start time

Time as of when data records have been stored in the partition.

Min RunID

Smallest RunID of the partition

Max RunID

Largest RunID of the partition

Rowcount

Number of staging-table data records (MSSQLServer)

Checked

Indicates whether the partition could successfully be checked.


A check, which is made either before a partition change or manually, is
regarded as successful if the partition does not contain statistical
records of active tasks.

The ILM checklist which includes the active tasks of a partition contains the following columns:
Column

Description

Client

Number of the client in which the task is active

Name

Task's object name

Type

Task's object type

RunID

Task's running number (RunID)


Tasks whose RunID shows a little red edge include a comment.

Status

Task's status symbol and status

Start time

Time at which the task was activated

End time

Time at which the task ended

User

User who activated the task

Parent

Running number (RunID) of the superordinate task that has


activated this task

The following options are available for all tasks in the ILM checklist's context menu:
Command

Description

Details

Shows the task's Detail Window

Report

Opens the current report for this task


Event objects display the report of the Event that was last
processed (!Process).

Statistics Activator

Displays the statistical overview of the activating object.

138

Chapter2 UserInterface

Command

Description

Child-task statistics

Displays the statistical overview of subordinated objects.

Comments

Opens a task's comment window.

Refresh

Refreshes the view.

Additional context menu options are only available for particular tasks:
l
l
l
l

Monitor (only for Notifications, Cockpits, Groups, Workflows and Schedules)


Change logging (only for Server processes)
Deactivate (only for ended tasks which have not been deactivated automatically)
Cancel (only for tasks in status "Waiting for Host" and for Notifications and Events in status
"Sleeping")
Disconnect (only for active user processes)

History tab
Column

Description

Partitionno.

Running number of the partition


Under MSSQL Server, staging tables always have the partition number
"0".

Parent

Displays the schema name (MS SQLServer) or the corresponding


main table of the UC4 Database (Oracle)

Filegroup
/Tablespace

Name of the filegroup (MSSQLServer) or the tablespace (Oracle)

Start time

Time as of when data records were stored in the partition

End time

Time up to when data records have been stored in the partition

Min RunID

Smallest RunID of the partition

Max RunID

Largest RunID of the partition

2.14.15 Cache
Information requested from the database is stored in the Server input buffer and can so quickly
be read whenever required. This procedure improves system performance as it is less timeconsuming than repeatedly calling the database. Keep this in mind when specifying the
maximum size of the Server input buffer in the Server tab. This value depends on the memory
that is available on your computer.

Automation Engine

Column

Description

Name

Area of the Server input buffer:


l
l
l
l
l
l
l

Clean Up Limit

139

SCRIPT - for Script


VARA - for UC4 Variable
MQMEM - for message queues
ODOC and XREQ - for UserInterfaces
USER - for User lists
OBJECT_IDNR - or object codes
OBJECT_NAME - for object names

Limit for the cache's memory release. To be specified in the Server properties.
Data is stored in the cache until its maximum size has been reached. Only in
this case, the Server deletes entries that are no longer required. The cache's
maximum size is ignored if it is not possible to remove data.

Current size

Currently used cache size

Cache items

Number of all cache entries

Active

The cache is active if this checkbox is checked

Calls

Number of input buffer calls

Hits

Number of entries found in the cache

Hit ratio

Hits of the primary work process in percent

Time

Total time consumed by the work processes for calling the cache

See also:
Server
Cache Usage

140

Chapter2 UserInterface

2.14.16 Password Exit


This area of the System Overview lists all the available information about a password exit.

Column

Description

Exit key

Type of exit
Allowed value: "XUC4PASS" for password exit

Exit name

Name of the exit


Allowed value: "PASSWORD" for password exit

Exit file

Path and file name of library

Exit parameter

Parameters assigned to the library

See also:
Password Exit

2.14.17 Quarantine
Internal messages control processing based on objects and their settings. Thus, checking their
contents is of high importance.
Invalid messages which cancel a Server process are intercepted and displayed in this area of the
System Overview. Your UC4 system is therefore protected since these messages do not affect the
Server processes.
Contact UC4 support; these messages are helpful for further analyses.
By default, the UC4 Automation Engine checks internal messages. On UNIX, this can have a
negative impact on performance. The UC4 administrator can deactivate this function with the
parameter exception= in the UC4 Server's INI file.

Automation Engine

Column

Description

Message number

Number of the message

Status symbol

Status of the message

141

"1" - May be released after prior contact with UC4 support


"2" - Has been logged for analysis reasons but cannot be released
"3" - Has successfully been processed and can be deleted
Occurrence time

Time when the message was quarantined

Reason for failure

Additional information about the failure reason

Replays

Number of release attempts

XML Stream

Message sections (if retrievable) for analysis

Reaction to invalid messages


The following steps are initiated if an invalid message has been detected:
1.
2.
3.
4.

The message is put into quarantine.


All database modifications made by this message are canceled.
Further message information is written to the UC4 Automation Engine's log file.
A trace file of the following name is created:
UC4Dump_name of the Server process_RunID_time stamp.txt

Example:
c:\uc4\server\temp\UC4Dump_UC2T#WP002_40373135_20060406144901543.txt
5. A dump is created if possible.
6. The ServiceManager restarts the aborted Server process.
7. If the UC4 administrator has defined the key EXECUTE_ON_EXCEPTION in the UC4
Variable UC_SYSTEM_SETTINGS, the specified object starts.
The UserInterface displays the symbol

to authorized users if there are quarantine messages.

142

Chapter2 UserInterface

This area of the System Overview and the symbol in the UserInterface are only displayed when
the User object or UserGroup has the privilege "Create diagnostic information" and a modification
right for Server processes. Obtain further information from your UC4 administrator.

Releasing messages
Only release messages upon prior contact with UC4 support.
Highlight the message and open the context menu command "Release". A dialog opens in which
trace options can be set. Select the Server process to be used for reprocessing the message.

Only the primary work process executes PWP messages.


Specified trace options are deactivated after the execution attempt. If the message could be
processed without failure, it remains in the list but can be deleted with a context menu command.

Context menu
The following actions are possible:

Automation Engine

Command

Description

Receipt

Flags the message as noted

143

The alarm status shown at the upper right edge of the UserInterface is no longer
shown when all invalid messages have been noted.
Delete

Removes a message from the list which could be reprocessed without failure

Release

Releases a task which can then be reprocessed

Show
message

Shows the message's internal technical information

2.15 Quick Search


2.15.1 Quick Access
The Quick Access function in the UserInterface enables a global, quick search for objects within
a client and direct access to them via the context menu. It even allows you to quickly access
objects that are deeply nested in a folder structure.

Client-wide quick search


You can call the Quick Access search field in the UserInterface either by clicking on the
magnifier button in the toolbar or via the F3 key.
The Quick Access search field is displayed directly below the toolbar in the UserInterface. A list of
matching objects and the number of results (hits) is displayed when a search key has been entered
and confirmed.
The UC4 Explorer's context menu is available for objects that are displayed in the result list of the
Quick Access search. This means that actions such as editing or executing particular objects can
be easily performed.

Note that this search does not include folders (FOLD).


The following table provides an overview of the Quick Access search field:

144

Chapter2 UserInterface

Action

Shortcut

Opening the Quick Access search


field

F3

Starting the search

ENTER
(Cursor positioned in the search field)

Collapsing the result list

ESC

Closing the search field

ESC
(result list collapsed)

Pushbu
tton

2 x ESC
(result list expanded)
Wildcards
A wildcard search is possible with the character '*'. If individual wildcard characters are used at the
beginning or end of the search text, the system searches for elements that start or end with the
search key. This schema is automatically used, hence it is not required to place a wildcard
character before and after the search text. You can also use the wildcard character '*' within the
search key; it stands for any number of characters.
Example: Wildcard search
Search text

Result

JOBS

Searches for all objects whose names include the term


"JOBS".

*JOBS*

Searches for all objects whose names include the term


"JOBS".

*JOBS

Searches for objects whose names end with the term "JOBS".

JOBS*

Searches for objects whose names start with the term "JOBS".

JOBS*TEST

Searches for all objects whose names include the terms


"JOBS" and "TEST" separated by any number of characters.

*JOBS*TEST*

Searches for all objects whose names include the terms


"JOBS" and "TEST" separated by any number of characters.

Quick Access
To execute actions via Quick Access, select one or more objects in the search list and open the
context menu. With multi-selection, the context menu only provides commands that can be
executed for all selected objects.
Objects of the Quick Search list can be dragged and dropped to the Activity Window, another
folder or a Workflow or Schedule object.

See also:
UC4 Explorer's Context Menu
Quick Search in Workflows

Automation Engine

145

Quick Search for Lists


Quick Search in Objects

2.15.2 Quick Search Function for Lists


The Quick Search function in the UserInterface facilitates a quick, easy and clear search for lists
with objects and activities.

General information
The Quick Search is available for the following areas:
l
l
l
l
l
l
l

UC4 Explorer (also available for the detail and symbol view)
Statistics
Activity Window
Forecast
Auto Forecast
Search (Results)
System Overview (for messages, the column Messages is used for the search)

The Quick Search bar can be opened using the shortcut "CTRL + F" in a selected window. The
search field opens exactly above the displayed objects. Use the ESC button to hide the Quick
Search.

A drop-down list opens if you enter a term in the search field. This list includes up to 10 matching
objects. The name and the corresponding symbol are always displayed. If a column other than
Name has been selected for the Quick Search, the suggestions also include this column. Within the
listed results, the specified search text is highlighted in yellow. At the same time, all found elements
in the object area are highlighted and the first matching objects are automatically displayed in the
window.
The arrow keys can be used to navigate within the Quick Search function. If a search result is
selected, the corresponding object is highlighted and the window's content is automatically moved
to this element. The buttons ESC or ENTER can be used to close the result list.
Note that upper and lower case letters can be used for the Quick Search. This is important
because it is also possible to search for object titles which can also include lower case letters.
Make sure to use upper case letters if you search for object names.

146

Chapter2 UserInterface

Wildcards
A wildcard search is possible with the character '*'. Other wildcard characters are not allowed. If
individual wildcard characters are used at the beginning or end of the text, the system searches for
elements that start or end with the search term. This schema is automatically used, hence it is not
required to place a wildcard character before and after the search term. You can also use the
wildcard character '*' within the search text in the form of a placeholder for any number of
characters.
Example: Quick Search with wildcard characters in the Explorer window
Search text

Result

JOBS

Searches for objects whose names include the term "JOBS".

*JOBS*

Searches for objects whose names include the term "JOBS".

*JOBS

Searches for objects whose names end with the term "JOBS".

JOBS*

Searches for objects whose names start with the term "JOBS".

JOBS*TEST

Searches for objects whose names include the terms "JOBS"


and "TEST" separated by any number of characters.

*JOBS*TEST*

Searches for objects whose names include the terms "JOBS"


and "TEST" separated by any number of characters.

Pushbuttons of the Quick Search bar


Symbol

Meaning

Description

Shows the previous term

Highlights the previous search


result in the list. The window
content is automatically moved
to this element. The highlighting
of all matching search results is
removed.

Show matching terms only

This function can be used to limit


the window content to the
elements matching the search.
This button can be activated and
deactivated.

Shows the next term

Highlights the next search result


in the list. Also, the element is
automatically displayed in the
window's list view. The
highlighting of all matching
search results is removed.

Automation Engine

Select search column

147

This command can be used to


select columns of the list (name,
title, type etc.) which should be
searched.
Clicking this button opens a
menu in which the column can be
selected. The object/task name
is always displayed in the dropdown list of the Quick Search
function.
The search column is displayed
with the symbol .

Close

Closes the Quick Search bar.


This function is also available via
the ESC key. If the result list is
open, the button ESC first hides
this list.

See also:
Quick Access
Quick Search in Workflows
Quick Search in Objects

2.15.3 Quick Search / Quick Access in Objects


Combo boxes in object tabs that can be used to select objects include a Quick Search function.
A context menu for a Quick Access to objects is available in all fields in which an object name
can be entered.

Quick Search
A Quick Search is only available for combo boxes in object tabs that can be used to specify objects
of a particular type. For example: Host, Login, Code, Group etc.
Fields without content in which a Quick Search is possible are identified by the text "<Type to
search>".

148

Chapter2 UserInterface

If you enter a search key in a combo box, the matching objects are displayed in a drop-down list. If
you do not enter a search text, a list that includes all object types opens when the combo box is
expanded. The search field is highlighted in yellow in the result list.
You can use either the mouse button or the arrow key (UP/DOWN) in combination with the ENTER
key to select a search result from the list.
Wildcards
The wildcard character '*' can be used. If individual wildcard characters are used at the beginning or
end of the search text, the system searches for elements that start or end with this search key. This
schema is automatically used, hence it is not required to place a wildcard character before and after
the search text. Within the search key, the wildcard character "*" stands for any number of
characters.
Example: Using wildcard characters in the combo box "Login" (Attributes tab) of a Job.
Search text

Result

LOGIN

Searches for all Login objects whose names include the term
"LOGIN".

*LOGIN*

Searches for all Login objects whose names include the term
"LOGIN".

*LOGIN

Searches for all Login objects whose names end with the term
"LOGIN".

LOGIN*

Searches for all Login objects whose names start with the term
"LOGIN".

LOGIN*TEST

Searches for all Login objects whose names include the terms
"LOGIN" and "TEST" separated by any number of characters.

*LOGIN*TEST*

Searches for all Login objects whose names include the terms
"LOGIN" and "TEST" separated by any number of characters.

Automation Engine

149

Quick Access
The context menu for a Quick Access is available for several fields that require an object to be
entered. These include combination fields, but also the field Execute in which an object has to
specified that should be processed if an error occurs.
All fields in which the context menu is not available have the symbol
menu by right-clicking the relevant field or via the symbol.

. You can open the context

Note that this context menu can only be displayed if the relevant field is not empty.
The context menu cannot be opened in selection tables (e.g.: Sync or Recipient tab).
Symbol

Command

Description

Edit

Opens the object specified in the field for editing.

Search for usage

Starts a search for usage of the object specified in


the field.

Add object

Opens a specific Explorer window which can be used


to create a new object. The Explorer window displays
only objects of the type that is allowed in the
respective field. More information is provided in the
description below.

Open home folder

Opens a new Explorer window which shows the


folder of the object that has been entered in the field.
The window content automatically shows the
highlighted object.

Context menus for fields in which you can specify executable objects also include the commands
"Execute", "Statistics" and "Last report".
Add object

150

Chapter2 UserInterface

The context menu command "Add object" opens a specific Explorer window from which objects can
be selected from a clear folder structure. Only object types are displayed that are allowed in the field
from which the call was made. This can be a particular object type (such as Login field) or several
ones (such as Runtime - Else - Execute: all executable objects). The Explorer opens in the folder in
which the object that has been specified in the field is stored.
Now, you can select an existing object. Do so by clicking an object in the Explorer or manually enter
it in the text field. Click "OK" to copy the selected object name over to the field.
You can also create a new object from this window. The following steps are required:
1. Enter the new object name in the text field.
2. Click the button New object.
3. The object cannot be created if an object of the same name already exists in the client. Use
an object name that has not yet been used.
4. The new object is immediately created if only a particular object type is allowed for the field
via which this window has been called (such as Login).
5. The Templates dialog opens if objects of different types can be selected for the field. In this
case, the Templates window only displays the object types that are allowed for the field
(such as all executable objects).

See also:
Quick Access
Quick Search for Lists
Quick Search in Workflows

Automation Engine

151

2.15.4 Quick Search in Workflows


The Quick Search function provides a clear overview and navigation in Workflows. This is very
useful in huge Workflows.
The Quick Search function of Workflows can be called in the Workflow tab or in the Monitor using
the shortcut CTRL F. The search bar is shown between the toolbar and the process flow in the
object window.
A list of matching Workflow tasks opens when a term is entered in the search field. This list
displays a maximum of 10 results and the search text is highlighted in the object name. All matching
Workflow tasks are additionally marked with a black border.
You can select a particular entry in the result list with the arrow buttons (UP/DOWN). The window
content then automatically switches to this task. This function is useful if the Workflow does not
display all tasks because the function "Fit size" has not been selected. Multi-selection is not
possible. Pressing the ENTER key or left-clicking will close the result list and highlight the selected
task in the Workflow.

Pushbuttons of the Quick Search bar


The following table describes the control elements of the Quick Search field:
Symbol

Meaning

Description

Finds the previous item

Highlights the previous search result


in the Workflow using a black border.
Additionally, the content of the
Workflow moves to this task if it is
not visible.

152

Chapter2 UserInterface

Finds the next item

Highlights the next search result in


the Workflow. Additionally, the task
is automatically displayed in the
Workflow.

Close

Closes the Quick Search bar. This


function is also available via the
ESC key. If the result list is open,
the shortcut ESC first hides this list.

Wildcards
A wildcard search is possible with the character '*'. Other wildcard characters are not allowed. If
individual wildcard characters are used at the beginning or end of the text, the system searches for
elements that start or end with the search term. This schema is automatically used, hence it is not
required to place a wildcard character before and after the search term. You can also use the
wildcard character '*' within the search text in the form of a placeholder for any number of
characters.
For example: Quick Search with wildcard characters in a Workflow
Search text

Result

JOBS

Tasks in the Workflow whose names include the term JOBS.

*JOBS*

Tasks in the Workflow whose names include the term JOBS.

*JOBS

Tasks in the Workflow whose names end with the term JOBS.

JOBS*

Tasks in the Workflow whose names start with the term JOBS.

JOBS*TEST

Workflow tasks whose names include the terms JOBS and


TEST separated by any number of characters.

*JOBS*TEST*

Workflow tasks whose names include the terms JOBS and


TEST separated by any number of characters.

Automation Engine

153

Connect to

The "Connect to" function of the Line Tool can be used to connect two tasks within a Workflow
quickly and easily. The "Connect to" command is available in the Line Tool's context menu. The
Quick Search bar opens when this command is used.
Enter a text in the search field and a list of matching tasks expands. Only search results that can be
connected to the task are displayed. By selecting the list entries with the arrow buttons
(UP/DOWN), the possible connection to the selected Workflow is displayed by a dotted line.

See also:
Workflow Monitor
Workflow tab
Quick Access
Quick Search for Lists
Quick Search in Objects

2.16 Importing and Exporting Objects


Objectscan be imported and exported between different UC4 systems or between the individual
clients of the same UC4 system. Object information is stored in an XML file and can be
exchanged between the different platforms.
As opposed to the Transport Case, you can freely select the UC4 system folder in which the
objects should be stored.

154

Chapter2 UserInterface

Note that XML imports require the target UC4 system to have at least the same ServicePack
version as the source system (XML file).
Do not use the import and export function for mass transports. Use the UC4 Transport Case for
this purpose.
Note that the size of the imported XML file must not exceed 2048 KB. Values below this limit
can be defined by the UC4 administrator in the UC4 Variable UC_SYSTEM_SETTINGS with
the key "MAX_IMPORT_SIZE".
The UC4 administrator can also limit the maximum number of objects that should be exported at
once. Use the key "MAX_EXPORT_COUNT" in the UC4 Variable UC_SYSTEM_SETTINGS
for this purpose.
Highlight one or several of the objects that should be exported in the UC4 Explorer. Then call the
Export command in the UserInterface's File menu or the context menu. A window opens in which
you can enter the name of the XML file. UC4_export.xml is suggested by default.

Importing objects works the other way round. Call the Import command in the UserInterface's File
menu or the context menu and select the XML file that should be imported. You can determine
whether already existing objects should be replaced. Objects of the same name are skipped if this
option is not active.If it is active, you can additionally specify that existing folder links should be
kept.
You can also define that a link or the previous order is created for each replaced object. If the option
Keep existing folder links is not activated, al links of the imported objects are removed.

Automation Engine

155

A message window that provides further details displays when the importing process has started.
Right-click the context menu in order to copy the displayed line(s) or to export the text to a CSV file.
Various tools are available that can be used to edit the generated XML files. Note for Notepad
users: Notepad creates additional header information at the beginning of the editing function if
exported objects include special characters (such as titles with German U umlauts) in order to
display them. Doing so changes the XML file's content and UC4 cannot guarantee that the
import will function properly.
You can import and export objects manually via the UserInterface or by using the script
elementsIMPORT and EXPORT.
Note that authorizations that are assigned in the object's properties are not exported.
The validity range of Calendars that are exported from UC4 versions that are older than 5.00A
and should be imported to systems that use version 5.00A or later ones is not automatically
converted. Open these Calendars manually and store them if you want to use them.
For security purposes, you cannot export passwords.
Additional note:
Calendar keywords of other Calendars that refer to the transported Calendar object must also be
imported. Calendars are recalculated after each import. Doing so occasionally causes error
messages in the log file when the Calendar was recalculated at a point in time when the
particular Calendar keywords had not yet been read. You can ignore these messages, no
manual interference is required.

See also:
XML Files of Objects
UC4 Transport Case

156

Chapter3 Objects

3 Objects
3.1 Introduction
3.1.1 UC4's Object Orientation
UC4 shows processes in the form of objects. Each object is responsible for a work step and
represents a certain task. This means that processes are composted of various objects on a
modular basis.
This concept has tremendous advantages:
l

Clarity
All processes are clearly structured.
Simple maintenance
You can easily modify them.
Extensibility
It is easy to integrate new requirements.
Distributed processes
You can split complex processes into simple steps.
Re-usability
Subtasks can be integrated into various processes.

Object names can consist of up to 200 of the following characters: A-Z, 0-9, $, @, _, . and #.
TimeZone object names are an exception; they must not exceed 8 characters.

Opening Objects
When you open an object in the UserInterface, you will first see its most significant tab.
In Jobs, this is the Process tab provided that it includes a content. Otherwise, the Attributes
tabopens first.
The Attributes tabalso opens for SAP Connection objects.

Automation Engine

157

See also:
Object Classes
Object Types

3.1.2 Object Classes


Objects can easily be handled through the UC4 Explorer. There are four object classes:
executable, active, passive and system objects.

Executable Objects
Executable objects are objects that can be processed manually or through control mechanisms of
superordinate objects. They experience the stages of activation, start and execution.
Symbol

Object

Description

Cockpit

Visualizes various values and conditions within the system


or from the systems that are monitored or controlled.

Event

Determines conditions and reaction to conditions that occur.

FileTransfer

Exchanges files of any kind between systems and system


platforms.

Group

Executes sporadic tasks.

Job

Determines the process steps to be executed in a target


system.

Notification

Notifies an operator of an interruption in a task, the


completion of which represents a necessary precondition for
the execution of further tasks.

RemoteTaskManager

Monitors and controls external jobs that were not started by


the system.

Schedule

Starts executable objects at regular intervals.

Script

Contains processing instructions that are not executed on a


target system and implemented exclusively with script
elements.

Workflow

Compiles single tasks for combined execution via defined


conditions anddependencies.

Active Objects
Active objects are objects whose contents can be modified manually or while processing an
executable object.
Symbol

Object

Description

Calendar

Defines calendar days which can be considered as starting


conditions when executing tasks.

158

Chapter3 Objects

Queue

Defines the maximum number of parallel running tasks and the


corresponding priority.

Sync

Synchronizes executable objects on the basis of defined


conditions and actions.

Variable

Stores values statically or retrieves them from a data source


dynamically.

Passive Objects
Passive objects are objects whose contents are defined by the user. They are static. Their contents
cannot be modified when processing an executable object but they are still used.
Symbol

Object

Description

CodeTable

Defines a complete set of characters.

Dashboard

This represents a dashboard which is used in the product


Enterprise Control Center.

Documentation

Administers documentation that does not refer to a single object.

Filter

Contains filter definitions for the contents of reports and external


files.

Include

Contains commonly used processing instructions from UC4 script


for shared use through objects.

PromptSet

Input mask that can be assigned to executable objects and which


reads user values during the activation process.

StyleSheet

Formats XML reports.

System Objects
System objects serve to administer your system.
Symbol

Object

Description

Agent

Enables the execution of jobs, file transfers, console and


file.system events, thereby facilitating the processing of various
operation steps in a target system.

AgentGroup

Combines agents and can be used to process tasks on one


particular or several hosts.

Agent/Client
Assignment

Assigns agent rights to individual or all clients.

Client

Defines a fully self-contained environment for the execution of


tasks within a system.

Connection

Contains connection parameters to an external target system.

Folder

Folders are objects.

Login

Saves login data for hosts.

Automation Engine

RASolution

Represents an RA solution.

Server

Represents a Server process

TimeZone

Records values for the calculation of local time.

User

Records a user's UC4 login settings, its assignments to user


groups, folders and access rights.

UserGroup

Groups users in order to assign them identical authorizations.

159

See also:
Object Types

3.1.3 Object Types


All objects belong to a particular object type, each one has its own particular short form which is
used in many places.

Symbol

Object type

Short
form

Description

Agent

HOST

Enables the execution of jobs, file transfers,


console and file-system events, thereby
facilitating the execution of various operation
steps in a target system.

AgentGroup

HOSTG

Combines agents and can be used to process


tasks on one particular or several hosts.

Agent/Client
Assignment

HSTA

Assigns agent rights to individual or all clients.

Calendar

CALE

Defines calendar days that can be considered as


starting conditions for the execution of tasks.

Client

CLNT

Defines a fully self-contained environment for the


execution of tasks within a UC4 system.

Cockpit

CPIT

Visualizes various values and conditions within


UC4 or from those systems being monitored or
controlled.

CodeTable

CODE

Defines the conversion of character sets between


two systems.

Connection

CONN

Contains connection parameters to an external


target system.

Dashboard

DASH

This represents a dashboard which is used in the


product Enterprise Control Center.

Documentation

DOCU

Administers documentation that does not refer to


a single object.

160

Chapter3 Objects

Event

EVNT

Determines conditions and reaction to conditions


that occur.

FileTransfer

JOBF

Exchanges files of any kind between systems and


system platforms.

Filter

FILTER

Contains filter definitions for the contents of


reports and external files.

Folder

FOLD

Folders are objects.

Group

JOBG

Executes sporadic tasks.

Include

JOBI

Contains commonly-used processing instructions


from UC4 script for shared usage via objects.

Job

JOBS

Determines the process steps to be executed in a


target system.
Subordinate tasks of SAP jobs are special forms.
They are also displayed in UC4 and called JOBD.

Login

LOGIN

Stores registration data for hosts.

Notification

CALL

Notifies an operator of an interruption in a task, the


completion of which represents a necessary
precondition for the execution of further tasks.

PromptSet

PRPT

Input mask that can be assigned to executable


objects and which reads user values during the
activation process.

Queue

QUEUE

Defines the maximum number of parallel running


tasks and the corresponding priority.

RA Solution

CITC

Represents an RA solution.

RemoteTaskManager

JOBQ

Monitors and controls external jobs that were not


started by UC4.

Schedule

JSCH

Starts executable objects at regular intervals.

Script

SCRI

Contains processing instructions that are not


executed on a target system and implemented
exclusively with script elements.

Server

SERV

Represents a server process.

StyleSheet

XSL

Formats XML reports.

Sync

SYNC

Synchronizes executable objects on the basis of


defined conditions and actions.

TimeZone

TZ

Records values for the calculation of local time.

User

USER

Records a user's UC4 logon settings, its user


group assignments, folder assignments, access
rights and privileges.

User Group

USRG

Combines users in order to assign them identical


authorizations.

Automation Engine

Variable

VARA

Stores values statically or retrieves them from a


data source dynamically.

Workflow

JOBP

Compiles single tasks for combined execution by


means of defined conditions anddependencies

Other Object Types


There is now a separate object for the following object types:
Short form

Description

API

CallAPI

C_HOSTG

Container of an agent group.

C_PERIOD

Container of a recurring task.

JOBD

Child tasks of SAP jobs.

REPORT

Report

See also:
Object Classes

3.1.4 Variables in UC4


The following table provides an overview of the types of variables available in UC4 and where
they can be used.
Object, PromptSet and script variables are only available in executable objects.
Variable objects
l

161

Static Variable
objects
(source:STATI
C)
Dynamic
Variable objects
(source: SQL,
SQLI, MULTI and
FILELIST)

Predefined variables

Description
Variable objects store values
(static) or retrieve them from a
particular data source
(dynamic).
The values are stored and
supplied in table form with a
particular data type, format and
value area.
Lines are identified by the Key
or Result column and the
columns are addressed via
numbers (1 to n).

Usage
l
l
l

UC4 Explorer
Script
Data source of Cockpit,
Database Event and
PromptSet objects

162

Chapter3 Objects

Predefined
variables for
system values
Predefined
variables for
object values

Predefined variables are


placeholders that refer to the
values of the system or the
object in which they are used.
Their names and values are
predefined and cannot be
changed.

Predefined variables can also


refer to the values of Variable
objects. Their syntax differs
from the syntax of predefined
variables for system or object
values and cannot be used in
scripts.

You can create object variables


by using either the script
element :PSET or the
Variables & Prompts tab.

l
l
l

Script
Attributes
"Variables & Prompts" tab
Properties of Workflow and
Schedule tasks

Syntax:
&$Variable name#
l

Predefined
variables for
Variable objects

Syntax:
{VARA object name [,
Key [, Column ] ] }

l
l

Attributes
"Variables & Prompts" tab
Properties of Workflow and
Schedule tasks

Object and PromptSet


variables
l
l

Object variables
PromptSet
variables

Syntax:
&Variable name#

l
l
l

PromptSet variables are derived


from PromptSet objects.

Script
Attributes
"Variables & Prompts" tab
Properties of Workflow and
Schedule tasks

Object and PromptSet variables


can be used in various object
locations. They can also be
inherited from child objects.
Script variables
Data types:
l
l
l
l

unsigned
signed
float
string

Syntax:
&Variable name#

Script variables are specifically


used for storing and using
values in Process tabs. They
can also be used in some
attributes.
You can use the script element
:DEFINE in order to declare
script variables with a particular
data type.
The script element :RESET can
be used to assign values of
script variables to a different
Process tab.

l
l

Script
Attributes

Automation Engine

163

3.2 Alphabetical Listing


3.2.1 Agent
Agent
The agent enables the execution of Jobs, FileTransfers, Console and File System events,
thereby allowing the processing of various operation steps in a target system.
Object class: System object
Object type (short name): HOST
Creating an Agent object manually is neither possible nor necessary as this is done automatically
and saved in the folder HOST (system client 0000) at the very first agent logon to the UC4 system.
The same is true if you want to rename the Agent object.
The name of an agent is defined in its INI file and cannot be comprised of more than 32 characters.
All agent names will be displayed in uppercase. Do not use special national language characters in
order to avoid problems in the respective target system. Note that an agent cannot be selected in
other objects if its name consists of more than the allowed maximum number of characters.

See also:
Handling Agents
Header tab
The Header tab is a general tab which is available in every UC4 object.
Object: Agent
Object class: System object
Object type (short name): HOST

164

Chapter3 Objects

Description

Field/Control

Description

Header
Title

Define object titles here. This title should contain a short and characteristic
description of the corresponding object as it is displayed in all overviews.

Created

Indicates the user who created this object including the date and time.

Modified

Indicates the user who last modified this object including the date and time. The
number of times the object has been modified is displayed to the right.

Last used

Indicates user, date and time regarding the most recent use of the object. The
number of times the object has been used is displayed to the right.
Set this function in the UC4 variable UC_SYSTEM_SETTINGS.

Archive keys

Two keywords of your choice can be specified.

Attributes Tab
The Attributes tab is object-specific and is only available in Agent objects. You can specify the
license category that should be used in this tab.
Object: Agent
Object class: System object
Object type (short name): HOST

Description

Field/Control
Element

Description

Automation Engine

165

License Category

The License Category that should be used by the agent can be selected
here. Allowed values are Production and Test, depending on whether
the agent runs in a production or non-production environment.

Trustable IPAddresses

If your UC4 system runs with encryption, you can specify IP addresses
(separated by semicolons) from which the agent accepts nonencrypted connections.
Communication to UC4 components such as the job messenger, Event
Monitors (BS2000, z/OS) or the Output Collector (NSK) takes place
without encryption. By default, the agent accepts non-encrypted
messages from the local host (127.0.0.1) and its own IP address.
If Event Monitors on z/OS are used in LPARs on different computers,
you must specify the relevant IP addresses here.
Releasing individual IP addresses is only reasonable if the UC4
Automation Engine should always reject login attempts of former
agent versions (see "Compatibility").

Service Manager
Record

The settings that are defined here are required for the connection
between the agent and a ServiceManager. Agents can so start directly
via the UserInterface (System Overview) or by using the script element
MODIFY_SYSTEM.
All values will automatically be replaced if the search for a
corresponding ServiceManager service was successful. This search
can be opened by using the"Refresh ServiceManager Scan" command
in the System Overview's context menu. The default port number 8871
is used for the scan unless a different specification is provided in the
setting SMGR_PORT_RANGE of the UC4 Variable UC_SYSTEM_
SETTINGS.

Phrase

Name of the ServiceManager environment.

Name

Name of the service in the agent's ServiceManager .

Port

Port number of the ServiceManager.

Linked to
ServiceManager

Links the agent with the ServiceManager.


This specification is automatically set if the ServiceManager scan for
the agent was successful. With this option being deactivated, you can
no longer start the agent via the System Overview nor by using
MODIFY_SYSTEM.

Agent Tab
The Agent tab is object-specific, and in this form is only available in "Agent" objects. It is only
displayed in SAP agents and contains the parameters for connecting to the SAP system.
Object: Agent
Object class: System object
Object type (short name): HOST

166

Chapter3 Objects

Description

Select a Connection object for the areas to be controlled with UC4. To establish a connection, the
SAP agent uses the parameters specified for the particular areas.
Field/Element

Description

ABAPBasis

For the connection to the SAP system.

Java Basis

For the connection to the Java Scheduler.

Process Integration

For the connection to the SAPXI.

System Landscape
Directory

For the connection to the System Landscape Directory.

Note that modifications made in a Connection object only become effective after a restart of the
SAP Agent.
Connection objects can also be stored using the Agent Variables in the Agent object.

See also:
UC4 and SAP

Authorizations tab
The Authorizations tab is an object-specific tab which is only available in "Agent" objects. It
can be used to define authorizations in order to access hosts with the agent. Authorizations are
part of the UC4 Authorization System.
Object: Agent
Object class: System object
Object type (short name): HOST

Automation Engine

167

Description

All clients available in the UC4 system are listed in this tab. Each table line corresponds to one
client.
Authorizations can be defined manually or via anAgent/Client-Assignment object.
The UC4 administrator can define an object which automatically starts whenever an agent's
authorizations are modified. This is done in the UC4 Variable UC_HOSTCHAR_DEFAULT, key
EXECUTE_ON_ASSIGNMENT.
Field/Control
Element

Description

Client

Name of the client for which access rights are set. The client number and, if
available, the title (to be entered in the Head tab of the client) are displayed.

Read

Allowed to send data by a file transfer

Write

Allowed to receive data from a file transfer

Execute

Allowed to execute Jobs

See also:
Client
Documentation Tabs
Documentation tabs are user-defined and client-specific tabs which can be assigned to all
object types in UC4.
Object: Agent
Object class: System object
Object type (short name): HOST

168

Chapter3 Objects

All Documentation tabs that have been defined by the UC4 administrator in the UC4 variable
UC_OBJECT_DOCU are shown. Note that imported objects have their own Documentation tabs.
The Version Management tab displays the stored object versions if this function has been
activated.

Structured Documentation

Each of these tabs can also be displayed in structured form. Structured Documentation can be used
to split complex object information in well-arranged parts. Each documentation element can be used
to store texts, but also to define attributes.
You can also define links (e.g. to files, folders or to documents in the Intranet and Internet etc.) in
structured documentation. Files are then displayed with the associated program, folders are
opened, URLs call the standard browser etc. The particular actions depend on the installed
programs and the user's PC configuration.

Automation Engine

169

New Documentation tabs initially only include the "Content" folder. This is your starting point for
creating a further structure. To create and edit this structure, you can use the following popup-menu
commands :
Command

Description

Add attribute

Creates a new attribute in the highlighted element.

Add node after

Inserts a new element after the highlighted element.

Add node before

Inserts a new element before the highlighted element.

Add node child

Creates a new element one level below the highlighted element.

Duplicate node

Duplicates the highlighted element and its attributes and contents.

Delete node

Deletes the highlighted element irrevocably.

You can create one or more attributes for each individual element. Basically, there are two different
types: text and enumeration. You can add one or more of these attributes to an element. Determine
the attribute's name and then select whether it is a text or an enumeration. In enumerations, you can
specify the entries that should be included.

170

Chapter3 Objects

Names of elements and attributes should comply with the XML naming convention. Letters,
numbers and the characters "-", ".", "_" can be used. Keep the following rules in mind:
l
l
l
l

The first letter of a name must neither be a number, nor ".", nor "-".
The name must not include blanks.
Do not use colons as they are reserved characters.
Names must not begin with "XML", regardless if uppercase or lowercase letters are used.

Agent Variables
Agent information and settings are mostly stored in agent variables. These variables are either
available as Variable objects in the system client 0000 or directly stored in the database. If they
are stored in the database, they are referred to as virtual agent variables. They can be read with
the script element GET_VAR, but they cannot be set with the statement :PUT_VAR.
The correct syntax is: GET_VAR (Agent variable,Agent name)
For example: :SET &jobreport# = GET_VAR('UC_EX_PATH_JOBREPORT','WIN01')
The UC4 administrator can specify all agent variables in the agent's INI file (section
[VARIABLES]). In doing so, values can be set in accordance with your environment.
For example:
[VARIABLES]
UC_HOST_CODE=UC_CODE
UC_HOST_JCL_VAR=NSK
UC_EX_PATH_BIN=$data01.uc4
UC_EX_PATH_JOBREPORT=$data01.
UC_EX_JOB_MD=$data01.uc4.ucxjns1r

Automation Engine

171

Agent Variables in the System Client 0000


Agent Variable

Description

UC_EX_ERP_
CONNECT

Contains connection specifications for the particular Enterprise


Business Solution.

UC_EX_HOSTCHAR

Contains particular settings for one or several agents.

Virtual Agent Variables


Virtual agent variables are usually defined in the [VARIABLES] section of the agent's INI file. The
values of some agent variables, are automatically retrieved by the agent. In this case, there is no
need to define them in the INI file (see the table below).
When the agent starts, all virtual variables will be passed on to the Automation Engine.
Note that you cannot define variables that are not listed below. Although you can create userdefined variables, they cannot be read.
Agent
Variable

Description

Definition
in INI file

UC_EX_
DAYLIGHT

This variable checks whether the current time is Daylight Savings


Time.

No

The agent retrieves this information from the system time and
passes it on to the Automation Engine.
Allowed values: "Y" and "N"
"Y" - Daylight Savings Time
"N" - Standard Time
The value of this variable is automatically set and cannot be
defined in the INI file.
UC_EX_
HOST_ROLE

The agent's role.


Any name that can be used as a filter in agent groups. Several
role names must be separated with a ";" character. This
parameter is limited to 256 characters.
Roles are converted to uppercase letters.
This definition does not affect the a gent itself.

Yes

172

Chapter3 Objects

UC_EX_IP_
ADDR

The IP address or the host name.

No

When the agent starts, it retrieves the IP address of the computer


on which it is running automatically. It passes this information on
to the Automation Engine where it is stored in this variable.
The Automation Engine uses the agent's IP address and port
number (variable UC_EX_IP_PORT) in the Header and Trailer
Includes and passes this information on to the job messenger.
The job messenger uses this data to connect to the agent.
The agent itself usually uses these values only for the
Sysplex configurations of a z/OS mainframe system (z/OS
agent).
If the agent runs in a cluster, you can enter this cluster's
virtual IP address here.

UC_EX_IP_
PORT

The port number of the agent.

UC_EX_JOB_
MD

The path and file name of the job messenger.

No

For further information, see also the description of UC_EX_IP_


ADDR.
Required

This variable must be defined. When the agent starts, it checks


this value and terminates when the path is not valid.
This value is used in the Header and Trailer objects which include
the messenger calls for the job start and job end.

UC_EX_
LICENCE_
CLASS

The license class according to the acquired UC4 license as well


as the hardware and software that is used.

Yes

UC_EX_MIB_
INFO

Additional information about the agent for the MIB (7.1.1.16).

No

UC_EX_MIB_
MONITORING

This variable indicates whether the agent's availability is


monitored.

No

When the license class is set to "S", the agent passes the value
"127.0.0.1" on when it starts instead of the host's actual IP
address.

Allowed values: "0" and "1"


"0" - The agent's availability is not monitored.
"1" - The agent's availability is monitored.

Automation Engine

UC_EX_
PATH_
BACKUP

The directory in which the backup files of theFile Rollback of jobs


and file transfers are stored.

173

Yes

Only affects Windows and UNIX agents.


Default value:
"..\BACKUP" (Windows) or "../backup" (UNIX)
If the directory does not yet exist, it will be created when the
agent starts.
Within the backup folder, the files are stored in the following
structure /<Client>/<Date>/<RunID>/
The backup directory for the filebased rollback is
automatically created when you start the agent. This directory
is available for jobs and file transfers. You can define the path
for the backup directory in the Agent Variable UC_EX_PATH_
BACKUP. Note that for using the filebased rollback, you need
the OS user under which the related jobs and file transfers are
started, and write access to the backup directory.

UC_EX_
PATH_BIN

The directory in which the agent is installed.

UC_EX_
PATH_
JOBREPORT

The directory in which the agent stores job reports.

Required

This variable must be defined. When the agent starts, it checks


this value and terminates when the path is not valid.
Required

This variable must be defined. When the agent starts, it checks


this value and terminates when the path is not valid.
The SAP agent stores the restart file also in this directory.

UC_EX_
PATH_TEMP

The directory in which the agent stores generated jobs on a


temporary basis.

Required

This variable must be defined. When the agent starts, it checks


this value and terminates when the path is not valid.
UC_EX_
PATH_TEMP_
IFS

The IFS directory in which the status store files of file transfers
should be stored.

UC_EX_SIM_
IDENT

The name of the $IDENT statement.

UC_EX_
VERSION

The version of the agent.

UC_HOST_
CODE

The name of the code table of the system client 0000.

Yes

Only relevant for OS/400 agents, and only when the value
"IFS" is set in the INI-file parameter store_type=
Yes

Only relevant for the GCOS agent.


No

The agent retrieves this value automatically.

Default value: "UC_CODE"


The character version that is defined here is used for transporting
jobs to the host and for the automatic file transfer of the job report.

Yes

174

Chapter3 Objects

UC_HOST_
CONN_ABAP

Connection object for the ABAP basis that should be used in the
Agent object.

Yes

UC_HOST_
CONN_JAVA

The Connection object for the Java basis that should beused in
the Agent object.

Yes

UC_HOST_
CONN_PI

The Connection object for the Process Integration that should be


used in the Agent object.

Yes

UC_HOST_
CONN_SLD

The Connection object for the Landscape Directory that should be


used in the Agent object

Yes

UC_HOST_
HW

The hardware information of the computer (such as the system


type, the number of processors or the processor type).

No

The agent retrieves this value automatically.


UC_HOST_
JCL_VAR

The reference to Includes that are used when the job is


generated.

Yes

These are generally the Includes HEADER.*, TRAILER.* and


RESTART.* of the system client 0000. User-defined Includes
can also be used.
UC_HOST_
SW

The operating system of the computer.

No

UC_HOST_
SW_VERS

The OS version.

UC_SIEBEL_
LOGPATH

The directory in which the Siebel log files are stored.

Yes

UC_SIEBEL_
SRVRMGR

The directory in which the Siebel Server Manager (srvrmgr.exe) is


stored.

Yes

The agent retrieves this value automatically.


No

The agent retrieves this value automatically.

See also:
Agent

3.2.2 AgentGroup
AgentGroup
An AgentGroup combines agents of the same platform. The agents to be included in an
AgentGroup are specified by entering the agent name or via filters. A task which runs in an
AgentGroup is processed on one or all of the AgentGroup's agents, depending on the specified
mode.
Object class: System object
Object type (short form): HOSTG
Host group selection, which includes selection of the agent for a task, is made before its script is
processed. :PUT_ATT can be used to define a different agent but not a different AgentGroup.
The script function PREP_PROCESS_AGENTGROUP can be used to read the agents of an
AgentGroup.

Automation Engine

175

Header tab
The Header tab is a general tab which is available in every UC4 object.

Description

Field/Control

Description

Header
Title

Define object titles here. This title should contain a short and
characteristic description of the corresponding object, as it is displayed
in all overviews.

Created

Indicates the user who created this object including the date and time.

Modified

Indicates the user who last modified this object including the date and
time. The number of times the object has been modified is displayed to
the right.

Last used

Indicates the user who last used the object including the date and time.
The number of times the object has been used is displayed to the right.

Archive keys

Two keywords of your choice can be specified here.

AgentGroup Tab
The AgentGroup tab is object type-specific, and in this form is only available in objects of type
"AgentGroup". It can be used to define agents and AgentGroup settings.
Object: AgentGroup
Object class: System object
Object type (short form): HOSTG

176

Chapter3 Objects

Description

Field/Control

Description

Platform

An AgentGroup integrates agents of a particular platform. Subsequent


modification of the selected platform is only possible if all agents and filters
shown in the right window area have been deleted.
Attention: Platform and OS are not the same. For example, an AgentGroup
with the platform "WINDOWS" can only contain Windows agents. This
does not include a SAP agent which runs on Windows. It can only be
selected in AgentGroups with the platform "SAP".
In Jobs, you can only select agents and AgentGroups of the corresponding
Job platform or Solution (RA).

Solution

Name of the RA Solution for RA agents


This field is required if "CIT" has been selected as the platform. No agent can
be added if this field is empty. Only agents of the selected Solution can be
assigned to the AgentGroup.

Table

The table serves to specify the agents belonging to a particular AgentGroup.


Click the button Add hosts to select particular agents. You can also specify
filters for the name or other attributes such as archive keys. Filters are set
directly in the individual table columns.
The agent order in the table is relevant for the modes "First" and "Next
listed". Lines can be rearranged using the arrows shown at the right window
edge. These entries are processed from top to bottom.
The wildcard character "*" is automatically inserted in the columns when a
particular agent is added.

Name

Name of the agent or filter for several agents.


Click the button Add hosts to select agents or enter the name or filter directly in
this text field. The wildcard characters "*" and "?" can be used. "?" stands for
exactly one character, "*" for any number of characters.

Automation Engine

Version

Filter for the version

HW

Filter for the hardware

SW

Filter for the software

SW Version

Filter for the software version

Archive 1
Archive 2

Filter for the archive keywords

Role

Filter for a role

177

This field offers all roles of this client's agents for selection.
The UC4 administrator can determine roles for each Agent. These are
stored in the Agent Variable UC_EX_HOST_ROLE.
Mode

The mode determines on which AgentGroup agent the task should be executed.

Any

On any randomly selected Agent

First

On the first available agent depending on the table order

Next listed

On the next active Agent. The order results from the table.

Load
dependent

On the agent which shows the lowest workload. This is done by checking
resource allocation:
1. Agents without resource limits are preferably used.
2. The agent with the least workload (resource-wise) is used if there are
resource limits for all agents.
3. In both cases, the following applies: If agents have the same resource limits,
the agent with the fewest active tasks is used.
One agent can be allocated to several clients.
A task's start time is used for agent selection. The task switches to the
status "Waiting for resource" if there are currently insufficient resources on
this Agent. It waits until processing is possible again. It does NOT change
the agent even if there would be sufficient resources on a different one.

All

On all agents

Parallel

Maximum number of tasks running parallel


Allowed values: 0 to 9999
Default value: 9999
Value "0" has the effect that the AgentGroup does not process tasks.

178

Chapter3 Objects

Force
Complete
Broadcast

This setting forces the task to be executed on all agents including those that
were not active at the time of activation.
There is a peculiarity if this setting is used together with a limitation of the
maximum number of tasks that can run parallel.
Example:
A job should run using the setting "a maximum of 3 parallel-running tasks" on all
AgentGroup agents. Only six of the ten agents are active. If the AgentGroup
intends to start a job on a computer whose agent is not active, this task
switches to status "Waiting for host". The AgentGroup adds it to the maximum
number of tasks that can run parallel because the task is already in a starting
stage.
Three tasks will switch to status "Waiting for host" because more than three
agents are inactive. Thus, AgentGroup processing is stopped even if there
would be active agents on which the job could run.

Add hosts

Opens a window which displays the agents of the selected JCL variant that
have not yet been assigned to the AgentGroup. Filter definitions are not
considered.

Simulation

Opens a window which lists the agents belonging to the AgentGroup according
to the specifications made in the table. An arrow points to the agent in which the
next task will run.

See also:
System Overview - AgentGroups
Authorizations tab
The Authorizations tab is object type-specific, and in this form is only available in "AgentGroup"
objects. It can be used to define authorizations for using AgentGroups in the individual clients.
AgentGroups are an integral part of UC4's authorization system.
Object: AgentGroup
Object class: System object
Object type (short form): HOSTG
This tab is only displayed in AgentGroup objects of system client 0000.

Automation Engine

Description

This tab lists all clients which are available in the UC4 system. Each table line corresponds to a
client. A client's access rights to an AgentGroup can be specified here.
Field/Control

Description

Client

Name of the client for which access rights are defined. The client number and
title (if existing) are displayed in the client's Header tab.

Read

The AgentGroup can be selected as sender in FileTransfers.

Write

The AgentGroup can be selected as receiver in FileTransfers.

Execute

The AgentGroup can be selected in Jobs.

See also:
Client
Documentation Tabs
The table shown below describes the XML file structure of a Variable object and explains the
individual elements.

179

180

Chapter3 Objects

All Documentation tabs that have been defined by the UC4 administrator in the UC4 variable
UC_OBJECT_DOCU are shown. Note that imported objects have their own Documentation
tabs.
The Version Management tab displays the stored object versions if this function has been
activated.

Structured Documentation

Each of these tabs can also be displayed in structured form. Structured documentation can be used
to split complex object information in well-arranged parts. Each documentation element can be used
to store texts, but also to define attributes.
You can also define links (e.g. to files, folders or to documents in the intranet and Internet etc.) in
structured documentation. Files are then displayed with the associated program, folders are
opened, URLs call the standard browser etc. The particular actions depend on the installed
programs and the user's PC configuration.

Automation Engine

181

New Documentation tabs initially only include the "Content" folder. This is your starting point for
creating a further structure. To create and edit this structure, you can use the following context
menu commands:
Command

Description

Add attribute

Creates a new attribute in the highlighted element.

Add node after

Inserts a new element after the highlighted element.

Add node before

Inserts a new element before the highlighted element.

Add node child

Creates a new element one level below the highlighted element.

Duplicate node

Duplicates the highlighted element and its attributes and contents.

Delete node

Deletes the highlighted element irrevocably.

You can create one or more attributes for each individual element. Basically, there are two different
types: text and enumeration. You can add one or more of these attributes to an element. Determine
the attribute's name and then select whether it is a text or an enumeration. In enumerations, you can
specify the entries that should be included.

182

Chapter3 Objects

Names of elements and attributes should comply with the XML naming convention. Letters,
numbers and the characters "-", ".", "_" can be used. Keep the following rules in mind:
l
l
l
l

The first letter of a name must neither be a number nor "." nor "-".
The name must not include blanks.
Do not use colons as they are reserved characters.
Names must not begin with "XML", regardless if uppercase or lowercase letters are used.

Structured documentation can be read with specific script elements (XML_*).


AgentGroup Monitor
The AgentGroup monitor displays tasks which are active or have been active depending on the
selected Agent. Its display corresponds to the Activity Window.
Object: AgentGroup
Object class: System object
Object type (short form): HOSTG
A context menu is available (right mouse click) which can be used to execute various commands
referring to individual tasks or the AgentGroup. For example, details, statistics or the report of
individual tasks can be viewed, tasks can be edited or generated jobs displayed.

Automation Engine

183

Task states can be exported and AgentGroup properties can be displayed if the context menu is
opened without an object being highlighted. The tab Attributes can be used to change the number of
parallel-running tasks. This requires the authorization "M" (Modify) for AgentGroups.

Calling the monitor


Right-click the
AgentGroup in the
Activity Window

Select the command Monitor in the context menu

Select the AgentGroup


in the Activity Window

Select the command Monitor in the menu File

184

Chapter3 Objects

See also:
AgentGroup
AgentGroup Attributes
The following overview lists the attributes of an AgentGroup object and describes their functions,
allowed values and ways of modification.

Tab

Attribute

Description

Value

Access
Via:

FILTER_
ARCHIVE_
KEY1

Filter table - Archive 1

User-defined,
limited to 60
characters.

Change
Program

FILTER_
ARCHIVE_
KEY2

Filter table - Archive 2

User-defined,
limited to 20
characters.

Change
Program

FILTER_
HOSTROLE

Filter table - Role

User-defined,
limited to 256
characters.

Change
Program

FILTER_NAME

Filter table - Name

User-defined,
limited to 32
characters.

Change
Program

See also:
AgentGroup
Attributes
UC4.DB Change
AgentGroups
In order to be able to execute tasks on a computer, you require an Agent. This agent initiates the
start of tasks, monitors them during their execution and sends current status information to the
UC4 Automation Engine. AgentGroups combine agents in order to avoid that several objects are
created when a task is processed on several hosts.
An AgentGroup can only include agents of the same platform (such as UNIX).
An agent can also be assigned to several AgentGroups.
Examples of applications:
l
l
l
l

Execution of a task on several hosts


Distribution of a file to several hosts
Monitoring of several hosts with Event or RemoteTaskManager objects
Monitoring of a task on the host with the lowest workload

All of a client's AgentGroups are listed in the System Overview. The context menu provides
several commands which can be used for all of the AgentGroup's agents.

Automation Engine

185

Creation

Assign agents to an AgentGroup by selecting particular ones or defining filters for names or other
attributes. Roles are useful for filtering attributes. The UC4 administrator can assign roles to each
agent via the variable UC_EX_HOST_ROLE. These roles can then be used in AgentGroup filters.
Examples of AgentGroup definitions:
l
l
l

The agents WIN01 and WIN02


All UNIX agents which have the role "DATABASE"
All SAP agents which have the archive key "Maintenance"

In AgentGroups, you can specify any agents and filter specifications of your choice.

AgentGroups of system client 0000 can also be used in other clients. This requires that the UC4
administrator sets the relevant rights for the AgentGroup. The client's AgentGroup is used if the
system client contains an AgentGroup of the same name.
Note that an AgentGroup of system client 0000 does not necessarily supply the same agent in
each client. Agents obtain client authorizations after installation which can differ from each
other.

Mode

An AgentGroup does not only combine agents; it also controls the execution of tasks via a specified
mode. On the one hand, AgentGroups execute tasks on all agents, and on the other hand, they
realize workload distribution because they start tasks on particular agents.
The following modes are available:
l
l
l
l
l
l

Randomly selected Agent


The first active agent in the table
The next agent listed in the table
The agent with the lowest workload
On all active agents
On all active and inactive agents

The simulation function displays the agents which belong to an AgentGroup and the agent on
which the next task will run.

186

Chapter3 Objects

View

The Activity Window displays tasks that run only on one agent due to a specified AgentGroup mode
with a one-line entry. The column Host indicates which agent has been selected. An AgentGroup
container that obtains an entry for each task execution is displayed if the task runs in mode "All".
This container contains the same name as the task and also shows an antenna symbol which is
included in the object-type symbol. The type is "C_HOSTG".

The AgentGroup container represents the superordinate task. Keep this in mind when you use
script elements that retrieve parent values (e.g.: SYS_ACT_PARENT_NAME). The
AgentGroup container and the task have the same name but each one has its own RunID.
The Detail Window of the AgentGroup's statistical record shows how tasks have ended. "0" signals
that all tasks have ended successfully, "1" that some tasks were canceled and "2" that no task has
ended successfully.
The Activity Window provides several commands for AgentGroups which can be called using the
context menu. One of the available commands opens a monitor which displays tasks executions
that took place because of the AgentGroup.

Execution

The task changes to the status "Waiting for Host" if no agent could be retrieved at the time of task
execution (such as all agents were inactive or the AgentGroup filters did not supply results). The
system regularly checks whether agents are available and active.
The UC4 administrator can specify this interval in the UC4 Variable UC_SYSTEM_SETTINGS
using the key AGENTGROUP_CHECK_INTERVAL.
Task start is initiated as soon as a host could be selected for the task. Workflows contain additional
options allowing you to specify that those tasks that use the same AgentGroup should run on the
same Agent. Without this option, there is the possibility that in particular modes or if agents become
inactive or active, different agents are selected because tasks are started at different times.
Use the script function GET_ATT to retrieve the agent on which the task will run.
If a task is restarted, it runs on the AgentGroup agent that has originally been selected.

3.2.3 Agent/Client Assignment


Agent/Client Assignment
You cannot use agents immediately after they have been installed in the UC4 system. For
security reasons, you must determine the clients in which the individual agents can be used and
the rights that they should have.

Automation Engine

187

Object class: System object


Object type (short name): HSTA
Rights can be assigned directly in the Agent object, Authorizations tab. This can be very timeconsuming if you use numerous agents; therefore, you can alternatively use an Agent/Client
Assignment object (HSTA). This object enters the relevant rights in the corresponding Agent
objects.
HSTA objects can only be created in system client 0000.
Use the Filter tab to define the agents for which the assignment should be used. The
Authorizations tab is decisive for the rights that should be assigned to the individual Agent objects.
The HSTA object is a passive object. It contains the filter settings, but the actual rights are only
assigned if:
l
l

a new agent that complies with the filter settings is authenticated.


the command "Execute host assignments" is called from the toolbar button Simulation.

Note that for performance reasons, rights are not assigned with each agent start but only when it
starts for the first time.
Note that newly created HSTA objects cannot be used immediately. They must be released in
the System Overview.
The UC4 administrator can use the key EXECUTE_ON_ASSIGNMENT in the UC4Variable
UC_HOSTCHAR_DEFAULT to define an object that should start if an Agents authorizations
have been changed.

Simulation

Click on "Simulation" in the HSTA object's toolbar. A window opens which displays the agents to
which the filter definition applies and the rights that they should have in the relevant clients.
A simulation does not trigger an agent assignment. It only displays the effects that the agent
assignment would have if the HSTA object were released.

188

Chapter3 Objects

Header tab
The Header tab is a general tab which is available in every UC4 object.

Description

Field/Control Description
Title

Define object titles here. This title should contain a short and characteristic
description of the corresponding object as it is displayed in all overviews.

Created

Indicates the user who created this object including the date and time.

Modified

Indicates the user who last modified this object including the date and time. The
number of times the object has been modified is displayed to the right.

Last used

Indicates the user who last used the object including the date and time. The
number of times the object has been used is displayed to the right.
Only displayed if the update function in the UserInterface settings has been
activated.

Archive keys

Two keywords of your choice can be specified here.

Filter Tab
The Filter tab determines the agents for which the client assignment should be used.

Automation Engine

189

Description

The filter line order is irrelevant.


The wildcard characters "*" and "?" can be used in some columns. "*" stands for any number of
characters, "?" for only one.
Field/Element

Description

Name

Name of the agent or filter for several agents

Host type

Type of Agent

Version

Agent version including hotfix level

HW

Computer hardware information


(e.g., system type, number of processors, processor type)

SW

Computer's OS

SW version

OS version

Role

Agent roles
The UC4 administrator determines the role names in
the Agent Variable UC_EX_HOST_ROLE.

IP address

Agent's TCP/IP address

License cat.

Name of the license category which has been assigned to


the Agent

Wildcard
characters
allowed

190

Chapter3 Objects

Field/Element

Description

Not

Activate this checkbox if you want to use the filter


settings of this line to exclude agents (instead of selecting
them).

Wildcard
characters
allowed

Example:
You want to assign all Windows agents except for
WIN01. First create a line in which you filter all Windows
agents. Then insert a second line in which you select the
agent WIN01 and activate the checkbox in the column
Not.

Authorizations tab
The Authorizations tab can be used to determine which type of rights the filtered agents should
have in the individual clients.

Description

All clients available in the UC4 system are listed in this tab. Each table line represents one client.
Field/Element

Description

Client

Name of the client for which access rights are determined. The client number
and, if available, its title (to be specified in the client's Header tab) are
displayed.

Automation Engine

Selection

191

Activate this checkbox if the client should be considered for agent assignment.
The agent only obtains the rights that have been ticked in the selection
checkbox.
Example:
The agent UNIX01 possesses all rights in clients 1, 2 and 3. You want to delete
the execution right for UNIX agents in client 3. Activate the selection checkbox
for this client and untick the column Execute. The right for client 3 in agent
UNIX01 will now be adjusted when a client assignment is triggered. All rights
for clients 1 and 2 remain unchanged in the Agent object.

Read

FileTransfer as sender is permitted.

Write

FilTransfer as receiver is permitted.

Execute

Jobs can be started.

Documentation Tabs
Documentation tabs are user-defined and client-specific tabs which can be assigned to all
object types in UC4.

All Documentation tabs that have been defined by the UC4 administrator in the UC4 variable
UC_OBJECT_DOCU are shown. Note that imported objects have their own documentation
tabs.
The Version Management tab displays the stored object versions if this function has been
activated.

Structured Documentation

Each of these tabs can also be displayed in structured form. Structured documentation can be used
to split complex object information in well-arranged parts. Each documentation element can be used
to store texts, but also to define attributes.

192

Chapter3 Objects

You can also define links (e.g. to files, folders or to documents in the intranet and Internet etc.) in
structured documentation. Files are then displayed with the associated program, folders are
opened, URLs call the standard browser etc. The particular actions depend on the installed
programs and the user's PC configuration.

New Documentation tabs initially only include the "Content" folder. This is your starting point for
creating a further structure. To create and edit this structure, you can use the following context
menu commands:
Command

Description

Add attribute

Creates a new attribute in the highlighted element.

Add node after

Inserts a new element after the highlighted element.

Add node before

Inserts a new element before the highlighted element.

Add node child

Creates a new element one level below the highlighted element.

Duplicate node

Duplicates the highlighted element and its attributes and contents.

Delete node

Deletes the highlighted element irrevocably.

You can create one or more attributes for each individual element. Basically, there are two different
types: text and enumeration. You can add one or more of these attributes to an element. Determine
the attribute's name and then select whether it is a text or an enumeration. In enumerations, you can
specify the entries that should be included.

Automation Engine

193

Names of elements and attributes should comply with the XML naming convention. Letters,
numbers and the characters "-", ".", "_" can be used. Keep the following rules in mind:
l
l
l
l

The first letter of a name must neither be a number nor "." nor "-".
The name must not include blanks.
Do not use colons as they are reserved characters.
Names must not begin with "XML", regardless if uppercase or lowercase letters are used.

3.2.4 Calendar
Calendar
Calendars are used to handle execution dates and times of objects. You can specify on which
days particular tasks should start.
These criteria are also referred to as Calendar conditions (e.g.: a Workflow which should only run on
Saturdays).
Object class: Active object
Object type (short name): CALE
A Calendar Assistant is available which can be used to summarize particular days in Calendar
keywords (e.g. the first workday of a month). There is no limit on the number of Calendar keywords
used in a Calendar.
Calendar keywords can be used in the following objects:
Object Type

Description

Notification

Messages can be sent to individual users or user groups depending on


Calendar keywords

194

Chapter3 Objects

Event

Calendar conditions can be used to determine the point in time for an


Event to be executed

Workflow and
Schedule

Calendar conditions can be specified in tasks

Calendar objects do not require specification of a validity period (e.g. 2005-2007) because
keywords are based on particular days or dates regardless of the year. Days are calculated with
the keys "NOW_MINUS" and "NOW_PLUS" which are specified by the UC4 administrator in
the UC4 UC_CLIENT_SETTINGS. By default, days are calculated 1 year back and 2 years
ahead.
Calendar keywords of type "Static" are an exception. They require a validity period to be
specified and must therefore be maintained.
Holiday Calendars are available in the system client 0000 which can be used in the objects of all
clients.
There is a peculiarity when duplicating Calendars. It is explained in the example shown below:
1. Calendar A has a Group and a Roll Calendar keyword both of which refer to one of the
Calendar's keywords.
2. Calendar A is duplicated, the copy is named B.
3. The Group and Roll Calendar keywords of Calendar B, however, do not refer to the Calendar
keyword in B but to the one in Calendar A
Please follow the recommendations given for transporting, importing and exporting Calendar
objects.

See also:
Useful Calendar Keywords
Transferring SAP Calendar Definitions
Header Tab
The Header tab is a general tab which is available in every UC4 object.

Automation Engine

195

Description

Field/Control

Description

Title

Define object titles here. This title should contain a short and
characteristic description of the corresponding object as it is displayed
in all overviews.

Created

Indicates the user who created this object including the date and time.

Modified

Indicates the user who last modified this object including the date and
time. The number of times the object has been modified is displayed to
the right.

Last used

Indicates the user who last used this object, the day and time. Far right,
the number of object usage is displayed.

Archive keys

Two keywords of your choice can be specified in all executable objects


and the Sync object. These keys are added to the statistical data each
time the object is processed.
Statistical data can be selected using these archive keys. Archive keys
are displayed in the Statistical Overview and can be printed.

Extended Reports

Extended reports can be written for all executable objects. These log,
for instance, the complete script with all Includes, the generated JCL
from Jobs or accesses to UC4 objects.

Default (UC_
CLIENT_SETTINGS)

Those extended reports to be written are defined client-wide in the UC4


Variable "UC_CLIENT_SETTINGS". These pre-settings are used for
the object.

All

All extended reports are written for this object.


This option overwrites possible pre-settings of the client.

196

Chapter3 Objects

None

No extended reports are written for this object.


This option overwrites possible pre-settings of the client.

Calendar Tab
The Calendar tab is only available in the "Calendar" object. It is object type-specific and can be
used to specify Calendar days.
Object: Calendar
Object class: Active object
Object type (short name): CALE

Description

The tab shows a Calendar in which the weeks can be displayed in vertical or horizontal order. The
following buttons are available in the UserInterface's toolbar: (vertical order)
(horizontal
order). The default view for opening Calendar objects can be specified in the
UserInterface'ssettings. The corresponding dialog is called via the command Settings which is
available in the UserInterface's Options menu.
A list of all created Calendar keywords is shown on the right side of the Calendar tab. Colored
symbols display the different available types:
Symbol

Type
Static
Yearly
Monthly
Weekly

Automation Engine

197

Group
Roll
These various keyword types are available in order to facilitate the quick and easy creation of
Calendar keywords. A Calendar Assistant is provided for each type and can be used to assign days
to the particular keywords.
Best practice is to use keywords whose meanings are immediately apparent. UC4 recommends
assigning days according to the relevant keywords. The individual keywords can then be linked
to each other using the keyword type "Group".
UC4 strongly recommends creating several small Calendar objects with few keywords instead
of one huge Calendar object in order to keep well-performing Calendar calculations. Make sure
that Calendar keywords referring to each other are stored in one Calendar object as this
facilitates transport, import and export procedures.
Various commands are available in the popup menu. Note that the keyword type "Static" comprises
of some additional commands

These steps are required for creating a Calendar keyword:


1.
2.
3.
4.
5.

Click New keyword in the context menu and select the appropriate type.
A dialog opens in which you can enter a name.
Right-click the new keyword and call the command Calendar Definition...
The relevant assistant for the selected keyword type opens. Now specify the days that
should be included in this Calendar keyword.
Store the Calendar object. The assigned days are then added to the Calendar.

Non-stored Calendar keywords are displayed in Italics.


The days of the Calendar keyword that is highlighted are shown gray in the Calendar tab.
Additionally, the days that are assigned to a particular keyword are displayed pink. Those assigned
to more than one keyword are shown yellow.
The current day is marked with a red circle.

198

Chapter3 Objects

Highlighting
The command Highlight options... is also available via the context menu. Settings specified here
are shown with a red line in order to provide a clear overview. This function, however, can be
activated or deactivated according to your demands using the command Highlight in the context
menu.

The search function is very useful for finding objects that use a particular Calendar keyword. It is
also possible to replace a particular Calendar keyword that is used in objects. The corresponding
functions are called Search for Use... and Replace....
Periodic View
Static Calendar keywords can also be displayed in the "Calendar" tab in a different way which is
called "Periodic View". Call it via the View menu or the

button in the toolbar.

The periodic view is only available if the UC4 administrator has made a period definition in the
UC4 Variable UC_CALENDAR_PERIOD.
Use it to picture a fiscal year which is not identical to the normal calendar year (1/1 until 12/31) but
contains a particular number of periods, for example.
The periodic view displays days and weeks on the basis of the defined periods. Period names are
displayed as you defined them. The days of every second month are displayed gray in order to make
it easier to view the regular months within the defined periods. The week number is also provided
with the calendar weeks resulting from the user-defined year (left side of the period, orange) or from
a regular calendar year (right side of the period, gray) being distinguished.
Exactly one keyword has been assigned to the Calendar days shown in magenta red. Yellow days
have more than one assignment. Days assigned to a selected keyword (in show mode) are
displayed with a dark gray background.
Move the mouse pointer over the Calendar view and the particular period is highlighted in blue.

Automation Engine

199

See also:
Type - Static
Type - Yearly
Type - Monthly
Type - Weekly
Type - Group
Type - Roll
Types of Calendar Keywords

Static
Use this type when the Calendar keyword should include:
l

Days within a specified period of time

As opposed to other types, the static Calendar keywords require a validity period to be specified.
Call the corresponding command from the context menu immediately following Calendar keyword
creation and assign a period (e.g. 01.07.2006 - 31.08.2006).
Note: Changing a Calendar's validity period requires manual adjustment of the days specified in
it via Calendar keywords in accordance with the new validity period.
Use one of the other keyword types if days should be specified that are not restricted to a
particular period.
One of the commands in the context menu of a static Calendar keyword is Show mode. It is
useful if your Calendar should show the individual days of a Calendar keyword on the one hand
but you do not intend to assign days on the other hand.
Days can be assigned to a Calendar keyword in several ways.

200

Chapter3 Objects
l

Particular days
Click the context menu command Assign Days. Now the days that should be included in this
Calendar keyword can be highlighted with the mouse button. Clicking on a day that has
already been assigned removes this day from the Calendar keyword.
Reverse assignment is also possible using the command Assign keywords. Highlight an
individual day (mouse click) and assign it to an existing Calendar keyword (right-click with
the mouse). This is a useful method if you intend to assign particular days to several
Calendar keywords.

The Form assistant supports you in assigning recurring days to a Calendar keyword. Highlight a
Calendar keyword and open the Form assistant via the context menu.
"Range" refers to a period within the validity period of the whole Calendar. It can be changed when
the definition of days should not be applied to the whole Calendar. This function can also be used to
delete days within a specified period. All days of a Calendar keyword are deleted when the check
box "Delete all entries..." is checked.

The section "Definitions" suggests several ways of assigning days.


l

Particular days of a week


Highlight those days of a week that should be used throughout the whole Calendar.

Automation Engine

201

Example: Each Saturday and Sunday

Particular recurring days


An interval can be specified for Calendar keywords that should contain days that recur
regularly. The table shown below lists examples for which the year 2004 and an interval of 3
days serve as a basis.
Option

Description

Day

Every nth day throughout the specified validity period (e.g. 08/27, 08/30,
09/02...)

Month (from
date)

The first day of every nth month (e.g. 03/01, 06/01, 09/01...)

Day of the
Month

Every nth day throughout the months (e.g. June 3, July 3, August 3...)

Last day of
the Month

Every nth last day of each month (e.g. 10/29, 11/28, 12/29...)

Working
day
keyword

Any keyword of the Calendar can be used as a workday keyword (e.g.: the
keyword WD_WORK includes the days from Monday to Thursday and is
used for the examples listed below).

Working
Day

Every nth day throughout the validity period of the keyword (e.g. Tue 01/06,
Mo 01/12, Thu 01/15...)

Working
day of the
week

Every nth day of a week (e.g. Wed 04/06, Wed 04/13, Wed 04/20...)

Working
day before
weekend

Every nth day before the weekend starts (e.g. Tue 05/04, Tue 05/11, Tue
05/18...)

Working
day of the
month

Every nth day of a month (e.g. Wed 05/05, Thu 06/03, Tue 07/06...)

Last
working day
of the
month

The nth last day of a month (e.g. Mon 03/29, Tue 04/27, Wed 05/26...)

Calendar
Period

Day of
Period

Every nth day of the periods (e.g. Period 1: 04/03, Period 2: 10/18)

Last Day of
Period

Every nth last day of a period (e.g. Period 1: 03/28, Period 2: 12/12)

Other Calendar keywords


The definition of a Calendar keyword can also be extended or reduced for the days of other
Calendar keywords. Either select "+" or "- " and then specify the Calendar keyword.

202

Chapter3 Objects

See also:
Calendar tab
Type - Yearly
Type - Monthly
Type - Weekly
Type - Group
Type - Roll

Yearly
You can use this type if the Calendar keyword should include:
l

days or date periods that occur in annual intervals.

The keyword type "Yearly" requires an interval to be specified. By default, 1 is suggested, which
means that every year is considered. In the next step you can define from which year onwards the
definition should be applied.
Note that the year as of which a yearly Calendar keyword is valid must not lie in the future.
Otherwise, an error occurs if this keyword is accessed. A message informs that it does not lie
within the validity range.
Now select your preferred method for filling in the Calendar: "On defined Calendar days" or "In a
defined interval". With the first one, you can specify exactly which days should be included in the
keyword or click on that particular month if every day should be assigned. The second method can
be used to define a date period and use the option of including only every nth day in the keyword.

Example 1

The Calendar keyword contains the following days as of 2006:


01.01.2006
15.07.2006 - 17.07.2006
31.12.2006

Automation Engine
01.01.2007
15.07.2007 - 17.07.2007
31.12.2007
etc.

Example 2

The Calendar keyword contains the following days (every 2nd year) as of 2006:
01.03.2006
12.03.2006
23.03.2006
03.04.2006
14.04.2006
25.04.2006
06.05.2006
17.05.2006
28.05.2006
01.03.2008
12.03.2008
23.03.2008
03.04.2008
14.04.2008
25.04.2008
06.05.2008
17.05.2008
28.05.2008
etc.

See also:
Calendar tab
Type - Static
Type - Monthly
Type - Weekly

203

204

Chapter3 Objects

Type - Group
Type - Roll

Monthly
Use this type when the Calendar keyword should include:
l

Days or date periods occurring in monthly intervals

In keyword type "Monthly", you can first specify an interval. By default, 1 is used which means that
every month is considered. Now specify the months during which the definition should be valid.
Now select your preferred method for filling in the Calendar: "On defined Calendar days" or "In a
defined interval". With the first one, you can select which day of the month (1st, 2nd, etc) counted
from the beginning or end should be included in the Calendar (e.g. the 10th day of the month, the 3rd
last day of the month).
Note: If the 31st day counted from the beginning of a month is selected, months with fewer days
are not included in this Calendar keyword.
The second method can be used to define a date period and use the option of including only every
nth day in the keyword.
Note that the day calculation for the Calendar keyword is made separately for each year. The
effect is that there are gaps or smaller intervals at the turn of a year.
Example: all days of each fifth month
Based on the settings specified in the Calendar keyword, January, June and November are
highlighted. Without the turn of the year being considered, the next calculated month would be April.
But as the Calendar calculation starts each year from the beginning, the next calculated month is
January again.

Example 1

The Calendar keyword includes the following days (e.g. as of 2006):


27.01.2006
24.02.2006

Automation Engine
27.03.2006
26.04.2006
27.05.2006
26.06.2006
27.01.2007
24.02.2007
27.03.2007
26.04.2007
27.05.2007
26.06.2007
etc.

Example 2

The Calendar keyword includes the following days (e.g. as of 2006):


01.09.2006
13.09.2006
25.09.2006
01.10.2006
13.10.2006
25.10.2006
01.09.2007
13.09.2007
25.09.2007
01.10.2007
13.10.2007
25.10.2007
etc.

See also:
Calendar tab
Type - Static

205

206

Chapter3 Objects

Type - Yearly
Type - Weekly
Type - Group
Type - Roll

Weekly
Use this type when the Calendar keyword should include:
l

Days occurring in weekly intervals

In keyword type "Weekly", you can first specify an interval. By default, 1 is used which means that
every week is considered. Now specify the weeks during which the definition should be valid and
then select the particular days of the week that should be included in the Calendar keyword.
Note that the day calculation for the Calendar keyword is made separately for each year. The
effect is that there can be gaps at the turn of a year because a year includes 52 or 53 weeks.
Example: each second Saturday
Based on the settings specified in the Calendar keyword, December 6 and 20 are highlighted.
Without the turn of the year being considered, the next calculated Saturday would be January 3,
2009.
Due to the setting FIRST_WEEK_METHOD, the first week of 2009 starts on January 5. Therefore,
the next calculated Saturday is January 10 (gap!). Below is a summary showing the Calendar
keywords which are close to the turn of the year:
December 6, December 20, (January 3 is omitted), January 10 etc.

Example

The Calendar keyword includes the following days (e.g. as of 2006):


01.02.2006
08.02.2006
15.02.2006

Automation Engine

207

22.02.2006
01.03.2006
08.03.2006
01.02.2007
08.02.2007
15.02.2007
22.02.2007
01.03.2007
08.03.2007
etc.

See also:
Calendar tab
Type - Static
Type - Yearly
Type - Monthly
Type - Group
Type - Roll

Group
Use this type if the Calendar keyword should include:
l

Days that are composed of various Calendar keywords

Calendar keywords of type "Group" are a combination of several Calendar keywords that are
connected to each other. Three connection types are available:
1. Days which exist in at least one of the specified keywords are assigned to the Calendar
keyword.
2. The Calendar keyword only includes days which occur in all the specified keywords.
3. The Calendar keyword only includes days that do not occur in the indicated keywords.
It is not necessary to select a particular connection type. You can also use two or more types at the
same time for your definitions.
Note that these combinations are very strong tools. Nevertheless, UC4 recommends keeping
your keyword definitions in order to keep a clear overview.

208

Chapter3 Objects

Example 1

The Calendar keyword comprises all days included in WORKDAYS_SHIFT01 with the exception of
those that are part of SUNDAY.

Example 2

The Calendar keyword comprises all days of WORKDAYS_SHIFT01 which are also part of
WORKDAYS.

See also:
Calendar tab
Type - Static
Type - Yearly
Type - Monthly
Type - Weekly
Type - Roll

Automation Engine

209

Roll
This type of calendar keyword is helpful when you want to use days that are based on another
calendar keyword but you want to adjust these days if particular conditions apply.
Roll-type keywords are based on a source calendar and one of its keywords whose specified days
can be adjusted by using one of the various options that are provided. You can even consider
irregularities such as holidays (see the example below).
Double-clicking the roll-type keyword opens its definition window (alternately, you can also open the
context menu). In the Attributes tab, you can now select the source calendar and the keyword you
want to use.The following options are now available:
l

Attributes tab:
You can move the days that are specified in the source calendar forward or backward by
using field "Adjust by +/- n days". You can also define that you want to use the valid days of
an additional calendar keyword.
Example 1:
The days from Mondays to Fridays which are specified in a keyword should be moved
forward for one day. You need to specify "Adjust by + 1 day" and the resulting days will then
be Tuesdays to Saturdays.
Example 2:
A calendar keyword that includes Tuesdays should be moved backward for two days. You
use the keyword Monday to Wednesday for this purpose ("Adjust by -2 days). Note that the
resulting days will then be Wednesdays (not Sundays).

If Collisions tab:
This tab is helpful when days possibly overlap with other calendar keywords and when you
want to react to such an overlap.
1. Enter the Calendar object and the keyword that can cause an overlap.
2. In the Action and Offset columns, you can specify whether the day that overlaps with
the selected calendar keyword should be moved forward or backward for n days.
3. When you move this day forward or backward, you can also specify a particular
calendar keyword that should be used instead.

Each table line of the If Collisions tab stands for one keyword and the reaction to possible overlaps.
Note that the order of the lines is decisive for the processing of roll-type keywords. The system
starts by checking each specified day whether there will be an overlap with the keyword that is
specified in the first line. The same verification is made with the second line. When an overlap is
detected, the defined action will take place. The result will then be checked against the calendar
keyword of the next line etc. The example shown below describes this process in detail.
You can use the arrows on the right side to rearrange the order of the lines.
You can use one or both of the available tabs to define your roll-type calendar.
Note that there is a difference in moving calendar days in the Attributes tab forward (+) or
backward (-) for 0 days when you use the valid days of another calendar. The algebraic signs
(+/-) are handled differently in such a case. "+" means that the system searches the next valid
day in the future (forward direction) and "-" means that the next valid day is searched in the past
(backward direction).

210

Chapter3 Objects

Example
This example creates a calendar keyword that includes the last days of all months. The system
takes into account that the last day of a month should always be the last working day of the
particular month.

The days that are included in LAST_DAY_OF_MONTH form the basic keyword. Depending on the
particular month, this can be the 28th, 29th, 30th or 31st.

You can now use the If Collisions tab in order to define the day that should be moved to the past.
The first line indicates that when the last day of a month falls on a weekend, this day will be moved
to the past (backward direction to the previous workday which is a Friday). The keyword
WORKDAYS includes Mondays to Fridays. The second line indicates that when the last day of a
month falls on a holiday, this day will again be moved backward. This day can also be a Friday.

See also:
Calendar tab
Type - Static
Type - Yearly

Automation Engine

211

Type - Monthly
Type - Weekly
Type - Group
Documentation Tabs
Documentation tabs are user-defined and client-specific tabs that can be assigned to all UC4
objects.

All Documentation tabs that have been defined by the UC4 administrator in the UC4 Variable
UC_OBJECT_DOCU are shown. Note that imported objects have their own documentation
tabs.
The Version Management tab displays the stored object versions if this function has been
activated.

Structured Documentation

Each of these tabs can also be displayed in structured form. Structured Documentation can be used
to split complex object information in well-arranged parts. Each documentation element can be used
to store texts, but also to define attributes.
Defining links (such as to files, folders or to documents in the Intranet and Internet) is also possible
in structured documentation. Files are then displayed with the associated program, folders are
opened, URLs call the standard browser etc. The particular actions depend on the installed
programs and the user's PC configuration.

212

Chapter3 Objects

New Documentation tabs initially only include the "Content" folder. This is your starting point for
creating a further structure. To create and edit this structure, you can use the following popup-menu
commands :
Command

Description

Add attribute

Creates a new attribute in the highlighted element.

Add node after

Inserts a new element after the highlighted element.

Add node before

Inserts a new element before the highlighted element.

Add node child

Creates a new element one level below the highlighted element.

Duplicate node

Duplicates the highlighted element and its attributes and contents.

Delete node

Deletes the highlighted element irrevocably .

You can create one or more attributes for each individual element. Basically, there are two different
types: text and enumeration. You can add one or more of these attributes to an element. Determine
the attribute's name and then select whether it is a text or an enumeration. In enumerations, you can
specify the entries that should be included.

Automation Engine

213

Names of elements and attributes should comply with the XML naming convention. Letters,
numbers and the characters "-", ".", "_" can be used. Keep the following rules in mind:
l
l
l
l

The first letter of a name must neither be a number, nor ".", nor "-".
The name must not include blanks.
Do not use colons as they are reserved characters.
Names must not begin with "XML", regardless if uppercase or lowercase letters are used.

Structured documentation can be read with specific script elements (XML_*).

3.2.5 Client
Client
The "Client" object defines a self-contained environment within a UC4 system. In this
environment, you can control and monitor the tasks of the connected computers.
Object class: System object
Object type (short name): CLNT
A Client object is the first object that must be created before you can start working with UC4. Within
a UC4 system, a client is clearly identified by its four-digit client number. You can select any
number between 0001 and 9999. All other objects of a UC4 system object (Users, UserGroups,
TimeZones, Jobs, Workflows, etc.) are always directly assigned to a particular client.
Clients are defined in the system client 0000. You can create a new client environment by creating a
new Client object that must be renamed afterwards. Select a four-digit name for this new Client
object.
Note that the Client object is moved to the client environment after it has been renamed. You
can edit it subsequently in the System Overview. Select "Client" from the context menu and

214

Chapter3 Objects

edit the corresponding client using the command "Edit" (right-click the mouse). Alternately, you
can log on to the client with a user and edit the Client object that is stored in <No folder>.
When you log on to a UC4 systems system client 0000 for the first time, you can use the User
object "UC/UC" in combination with the password "UC". UC4 recommends changing this
password immediately after you have logged on for the first time.

System Client 0000

Client 0000 of a UC4 system is also referred to as the system client. You can use this client to
administer the system-internal objects and key settings. Some settings affect all existing clients
unless they have been excluded by using local settings and options. Only UC4 administrators can
change or extend system-client settings.
All other clients and selected users with administrative rights for local clients are created in the
system client.
Some of the system client's internal objects are overwritten when a UC4 update installation is made
and can disappear.

Local Clients 0001 to 9999

Client numbers that range from 0001 to 9999 are referred to as local clients. Some client settings
can also be changed locally (in the client itself). For this purpose, you required the relevant rights.
Client numbers cannot be changed within local clients.
Some of the objects that are supplied in system client 0000 can be overridden by objects that exist
in local clients of the same name. Therefore, you can define settings for each local client which
differ from the system client.

See also:
User
User Group
Header tab
The Header tab is a general tab which is available in every UC4 object.
Object: Client
Object class: System object
Object type (short name): CLNT

Automation Engine

215

Description

Field/Control Description
Title

Define object titles here. This title should contain a short and characteristic
description of the corresponding object as it is displayed in all overviews.

Created

Indicates the user who created this object including the date and time.

Modified

Indicates the user who last modified this object including the date and time. The
number of times the object has been modified is displayed to the right.

Last used

Indicates user, date and time regarding the most recent use of the object. The
number of times the object has been used is displayed to the right.
Only displayed if the update function in the UserInterface settings has been
activated.

Attributes Tab
The Attributes tab is object type-specific and in this form only available in the "Client" object.
This tab can be used to define a (client-wide) valid TimeZone and to activate SNMP monitoring.
Object: Client
Object class: System object
Object type (short name): CLNT

216

Chapter3 Objects

Contents

Field/Control Description
Element
TimeZone

Time zone default setting for the current client. This time zone applies for all
tasks and their corresponding date/time displays for which no time zone was
explicitly defined. If no time zone has been chosen, the UC4 Automation
Engine's UTC applies client-wide.

MIB - Info

Settings for MIB client group entries. These are displayed in the System
Overview and provided for the MIB. There is no UC4 control over these fields.

Monitoring

Activation of this check box initiates SNMP monitoring of this client. This
function allows the supervision of this client's productive status.

Additional Info Additional client information for the MIB (5.1.1.6).


Not currently in use.

See also:
Time
About SNMP
Settings Tab
The Settings tab shows the content of the UC4 Variable UC_CLIENT_SETTINGS. The
different client areas can so also be directly configured in the client object.
Object class: System object
Object type (short name): CLNT
A message is displayed if the UC4 Variable UC_CLIENT_SETTINGS is being edited by a user. In
this case, client settings cannot be changed from within this tab.

Automation Engine

217

Documentation Tabs
Documentation tabs are user-defined and client-specific tabs that can be assigned to all object
types in UC4.
Object: Client
Object class: System object
Object type (short name): CLNT

All Documentation tabs that have been defined by the UC4 administrator in the UC4 variable
UC_OBJECT_DOCU are shown. Note that imported objects have their own documentation
tabs.

218

Chapter3 Objects

The Version Management tab displays the stored object versions if this function has been
activated.

Structured Documentation

Each of these tabs can also be displayed in structured form. Structured Documentation can be used
to split complex object information in well-arranged parts. Each documentation element can be used
to store texts, but also to define attributes.
You can also define links (such as to files, folders or to documents in the Intranet and Internet etc.)
in structured documentation. Files are then displayed with the associated program, folders are
opened, URLs call the standard browser etc. The particular actions depend on the installed
programs and the user's PC configuration.

New Documentation tabs initially only include the "Content" folder. This is your starting point for
creating a further structure. To create and edit this structure, you can use the following popup-menu
commands :
Command

Description

Add attribute

Creates a new attribute in the highlighted element.

Add node after

Inserts a new element after the highlighted element.

Add node before

Inserts a new element before the highlighted element.

Add node child

Creates a new element one level below the highlighted element.

Duplicate node

Duplicates the highlighted element and its attributes and contents.

Delete node

Deletes the highlighted element irrevocably.

You can create one or more attributes for each individual element. Basically, there are two different
types: text and enumeration. You can add one or more of these attributes to an element. Determine

Automation Engine

219

the attribute's name and then select whether it is a text or an enumeration. In enumerations, you can
specify the entries that should be included.

Names of elements and attributes should comply with the XML naming convention. Letters,
numbers and the characters "-", ".", "_" can be used. Keep the following rules in mind:
l
l
l
l

The first letter of a name must neither be a number, nor ".", nor "-".
The name must not include blanks.
Do not use colons as they are reserved characters.
Names must not begin with "XML", regardless if uppercase or lowercase letters are used.

3.2.6 Cockpit
Cockpit
The Cockpit can be used to visualize various values and conditions. They can be retrieved from
UC4 and the system it monitors and controls. For example, you can use it to have the currently
used disk space displayed, or the number of UC4 users, or an agent's shutdown. The Cockpit
and its display elements can be defined as you need them.
Object class: Executable object
Object type (short name): CPIT
Only the numerical contents of Variable objects can be displayed.
The cockpit retrieves its values from Variable objects. It can convert the numerical contents of
these Variables and display them according to the definitions that have been made. The contents of
these Variables can be retrieved from processing operations and processes such as:
l

Event monitoring (for example, information about a file system, availability or non-availability
of files or agents, or the occurrence of console messages)

220

Chapter3 Objects
l
l

l
l

Analyses of data sequences (for example, a file is checked for a number of specific entries)
Access to SNMP values that are client-specifically generated by UC4 and stored in the UC4
Variable "UC_SNMP_VALUES" (number of active Users, active agents, blocked tasks and
active Notifications)
Values or conditions that are stored by active tasks (for example, Job, Workflow, CallAPI)
Values or conditions that are stored by UC4-external processes via the CallAPI.

When you activate the Cockpit, its monitor displays automatically if this has been specified in the
UserInterface settings. The monitor view is periodically updated when the activities are refreshed or
can be manually refreshed by clicking the F5 key.
Creating Cockpits
Cockpits display values and states that they retrieve from Variable objects graphically.

Procedure

1. Click in the toolbar. A window that lists all the available object types opens. Select type
Cockpit (CPIT).
2. Assign an appropriate name and open the Cockpit object. Click the Cockpit tab.
3. You can use the complete tab area in order to design your graphical view of data. Pies, bars,
traffic lights, lamps, boxes and frames are at your disposal.
4. Display elements can be grouped within frames. Create a frame and then press CTRL in
order to select an element that should be moved to the frame. The selected element is
displayed with a red frame and can be moved to the frame or out of it.
5. In each element, you must specify the Variable from which the value that should be
displayed derives and how it should be displayed. You can use the context menu command
"Properties" for this purpose.
6. The General tab can be used to change the displayed element's type if needed. Enter a label
for the element and how the value should be displayed (for example, value in percent). You
can also adjust the font type and the size.
7. In some elements, you can decide whether the element should be displayed in accordance
with specified threshold values (the specified threshold values are displayed in different color
ranges). The On/Off function displays the element red if its value is 0 and green if its value is
not equal to zero. Specify this setting as you need it.
8. In the Data source tab, you can now select the Variable object and the validity key that
includes the value that should be displayed. Click OK to save all the modifications that you
made in the properties.
9. The properties of all other display elements can be configured in the same way.
10. You can use the optional settings of the Runtime tab in order to monitor the execution of the
Cockpit object.
11. In the Process tab, you can store UC4 script elements.
12. Start the Cockpit object. The Cockpit monitor provides a graphical display of all current
values.
There are various other settings that can be specified in the Cockpit object. For details, refer to
the documentation about the individual tabs.
Header tab
The Header tab is a general tab which is available in every UC4 object.

Automation Engine

221

Description

Field/Control

Description

Header
Title

Define object titles here. This title should contain a short and
characteristic description of the corresponding object as it is displayed
in all overviews.

Created

Indicates the user who created this object including the date and time.

Modified

Indicates the user who last modified this object including the date and
time. The number of times the object has been modified is displayed to
the right.

Last used

Indicates user, date and time regarding the most recent use of the
object. The number of times the object has been used is displayed to
the right.

Active

With this option being deactivated, the object will automatically be set
to inactive after its activation and not processed.
Therefore, the tasks obtain the status ENDED_INACTIVE_OBJECT
(return code: 1925).
This setting is available in the Header tab of all executable objects and
is set by default.

Archive keys

Two keywords of your choice can be specified in all executable objects


and the Sync object. These keys are written to the statistical data each
time the object is processed.
Statistical data can be selected using these archive keys. Archive keys
are displayed in the Statistical Overview and can be printed.

222

Chapter3 Objects

Extended Reports

Extended reports can be written for all executable objects. They log the
complete script with all Includes, the generated JCL of Jobs or
accesses to UC4 objects.

Default (UC_
CLIENT_SETTINGS)

If you select this option the reports the UC4 administrator defined in the
UC4 Variable UC_CLIENT_SETTINGS with the key "EXT_
REPORTS" are generated.

All

All extended reports are written for this object.


This option overwrites possible pre-settings of the client.

None

No extended reports are written for this object.


This option overwrites possible pre-settings of the client.

Sync Tab
The Sync tab is object-type specific and is available in all executable UC4 objects.
Sync objects synchronize task on the basis of defined conditions. Enter one or several Sync
objects including the actions that should be taken in this tab if you want to make use of this
possibility.

The Sync objects are checked one after the other when the task starts. The UC4 Automation
Engine tries to use the Sync object of the first line by calling the start action. If this is not possible
because this is not allowed by the Sync object's current condition, the task waits, aborts or is
skipped. The type of reaction depends on the Else condition defined in the tab's last column. If
"wait" has been specified, the task waits until it can use the Sync object with the start action. Then
the UC4 Automation Engine checks the Sync object in the next line etc. The task starts as soon all
Sync objects could successfully be used. Depending on the task's end status, either an abend or
end action is processed.
Up to 500 Sync objects can be specified.
All Sync objects must not include a total of more than 5000 rules. Rules are defined actions that
are specified directly in the Sync object.

Automation Engine

223

Task ends are administered by work processes but only the primary work process releases busy
Syncs. Because of this task allocation, it can take several seconds until a Sync is released after
a task has ended. In this case, the report entry includes a time stamp that shows a time that is
later than the task has ended. Such delays occur when the primary's work load is high or if it is
processing lots of Syncs.
Note that using many Sync objects and rules can reduce task clarity. UC4 recommends
reducing the number of Sync object to a minimum.

Description

Only actions that have been defined in the Sync object can be selected.
Field/Control

Description

Sync object

Selects the Sync object that should be used to synchronize the task.

Start action

Defines the action that should be taken when the task starts. If this is
not possible because of the Sync's status, the Else condition becomes
effective.

Abend action

This action is processed if the task aborts.

End action

This action is processed if the task ends successfully.

Else

You can define here what should happen to the task if the start action
cannot be executed:
l

l
l

The task should wait until the start action can be


executed (WAIT).
The task aborts (ABEND).
The task is skipped (SKIP).

See also:
Sync
Cockpit - Cockpit Tab
The Cockpit tab is object-type specific and is only available in "Cockpit" objects. In this tab, you
can set the Cockpit's display elements and its properties.
Object class: Cockpit
Object class: Executable object
Object type (short name): CPIT

224

Chapter3 Objects

You can stores the size and the order of the display elements in the Cockpit tab and the size of the
object itself. In doing so, you can set up the display in your preferred way.

Creating and positioning display elements

In the "Cockpit" tab, you can use the display elements Box, Bar, Pie, Traffic Light and Lamp. Use
the popup-menu command "Display Element" to create a display element.

All display elements can be arranged as required and their size can be adjusted. By using the
mouse, you change the position or size by 10 pixel. You can be more precise by using the keyboard.
The arrow keys can be used to change the size by pressing the SHIFT key and the position by
pressing the CTRL key (by 1 pixel). Display elements can be grouped into frames. Press the CTRL
key and click on an element. This element is now shown with a red frame. Drag it into the frame.
Vice versa, you can also remove a display element from a frame.
Displayed elements cover each other if they overlap. The highlighted element is always in the
foreground. Keep this in mind when you move or change frames within a Cockpit.
Display elements and frames can be copied and pasted. You can do so with all objects between
different cockpits. Use the key combination CTRL+C and CTRL+V or the relevant popup-menu
command. You can also delete display elements and frames that are no longer required.

Automation Engine

225

Defining Properties

In the properties of a display element, you can define its precise function, display and data source.
Select the popup-menu command Properties in the highlighted display element.

Display of Elements

You can change the way that elements are displayed at any time. Simply select a different display
element from the dropdown list. In the text field Caption , replace the default value by your specific
term which serves as the label in the Cockpit. This field is limited to 30 characters. Select from the
dropdown list what should be displayed in the second line. This can be the monitored value (as a
number or in percent), the value and maximum value (numbers next to each other), an empty line or
a text. Font settings can be specified using "Font..." command.

Function of Elements

Display elements work in different ways:


l

l
l

The display elements can display the monitored value in the colors green, yellow or red at
runtime.
The display elements can also be used for a simple on/off display (green or red).
Any text of a UC4 Variable can be displayed with a box.

Threshold values (primarily for traffic light, pie and bar)


In order to display three colors, you must select the option Threshold values . Specify the
minimum and maximum value as well as the threshold values for the yellow indicator. At runtime,
the values are displayed in the colors that are defined here.

226

Chapter3 Objects

On/Off (primarily for box and lamp)


To use box or lamp for on/off display, you must select the option On/Off . At runtime, the values are
displayed in the colors that are defined here. If the value equals zero, the display is "Off" (red). If it
does not equal zero, the display is "On" (green).

Data Source of the Elements

In the Data source tab of the properties, you can define the Variable object that is used to retrieve
the monitored value or status. You can specify static or dynamic variables.
Use the dropdown list "Key" in order to determine the particular entry that should be used to retrieve
the value. If you do not specify an entry, the system automatically uses the first line.
In static variables, the value is always read from the "Value 1" column, and in dynamic variables
always from the first basic column (the first column that is shown after the Result column).
Variables & Prompts Tab
The Variables & Prompts tab is object type-specific and is available in every executable object
in UC4.
Object: FileTransfer
Object class: Executable object
Object type (short name): JOBF
This tab has two tasks:
l
l

It stores object variables.


It assigns PromptSet objects.

Object variables

Automation Engine

227

Object variables include values that belong directly to the object and can be read in the Process
tabs. Variable names and values are determined in the table shown below.
In the Value column, you can also enter predefined variables. Do so using the Variables...
button in the object's toolbar.
The same rules apply for object variable names and for script variables. If you omit the preceding
"&", it is automatically added during the storing process and is available the next time the object
opens.
Object variables and PromptSet variables can be inherited from the superordinate object. For
example, a Schedule's tasks can use the object variables of the Schedule object.
Field/Element

Description

Inherit from parent


All variables (default)

The object obtains all object variables and PromptSet variables of


the superordinate task.

Only defined variables

The object only obtains the object variables of the superordinate


task that have been defined in its "Variables & Prompts" tab.
PromptSet variables are only inherited if the PromptSet object
complies with these values and the value that should be
overwritten has not been changed in the "Variables & Prompts"
tab.

No variables

The object obtains all object variables and PromptSet variables of


the superordinate task.

Note that inherited variables overwrite existing object variables if they have the same name. In
contrast, PromptSet variables are never overwritten.
The following procedure can be used if you want to overwrite PromptSet variables with the value
of a parent variable:
Open the task's Workflow or Schedule properties and switch to the Variables & Prompts tab.

228

Chapter3 Objects

Select the PromptSet area and use the Workflow's or Schedule's variable name as the value of
the relevant PromptSet element. If the particular PromptSet element is not a text field, click its
labeling.
PromptSet objects

In the Variables & Prompts tab, you can also select one or several PromptSet objects that should
be called during the activation process. In doing so, you can overwrite the default values of
PromptSet elements. These modifications do not affect the PromptSet object itself.
You can use the "+" and "-" buttons to add or remove PromptSet objects. Several PromptSet
objects are called from top to bottom. Use the arrow buttons if you want to change this order.
You can change default values either by directly modifying the elements or by clicking on the blue
text to the left of the element. After clicking on the blue text, a gray text field is shown instead of the
particular PromptSet element and you can enter a new value. You can also enter predefined
variables. If you click again, the element is shown as at the beginning and previous entries are
deleted.
Predefined variables are already deleted when the PromptSet input mask is called. Note that the
values of predefined variables can change during the object's execution (for example, with UC4
Script) but the PromptSet variable still stores the old value.
An error occurs if the object should be stored and an element's value does not fulfill the
limitations of the PromptSet properties (min. value, max. value, max. length, value required etc).
The affected fields are highlighted in yellow.
If the values differ from the reference values, an error only occurs when the object starts and an
attempt is made to send the prompt. Ensure that the data type and other limitations (min. value,
max. value, format) of the reference variable are preserved.
Using the same variable names has the effect that the object variable values are overwritten by
the PromptSet variables. The value of the PromptSet object that has last been called is used if
selected PromptSet objects include identical variable names.

Automation Engine

229

Graphical elements that are removed from the PromptSet object are also removed from the
Variables & Prompts tab. Modifications that are made in the PromptSet object's default values
do not affect the Variables & Prompts tab. The values of the PromptSet object are only
available when the PromptSet object is newly selected.

See also:
Object Variable
Designer tab
Runtime tab
The Runtime tab is object-class specific and is available in every executable object in UC4. It
can be used to specify parameters for a task's runtime behavior.

The Runtime tab is structured as follows:


l
l
l
l
l
l

Return code handling


Forecast setting
Evaluation of estimated runtime (runtime evaluation)
Monitoring of maximum runtime (runtime monitoring)
Monitoring of minimum runtime (runtime monitoring)
Reaction if the runtime is longer or shorter than defined (runtime monitoring)

Description

Field/Control
Definition for ENDED_
OK

Description

230

Chapter3 Objects

Return code <=

Maximum return code for the normal end of a task.


A task ends normally (Status "ENDED_OK") if its return code lies
below or is equal to the specified maximum return code.
You can also set this value using the script statement :EXIT.

Else execute

If the relevant task does not end with a return code that lies within
the ENDED_OK zone, you can define an alternative object that
should be processed.

End status for Forecast

Selection list for the end status that this task should return when
you make a Forecast calculation.

Estimated runtime (ERT)


Current ERT =

Display of this task's next estimated runtime (ERT).


You can specify an estimated runtime here. This value then applies
until an ERT calculation has been made after the task's next run.
Format: "hours:minutes:seconds".

Use default (UC_


CLIENT_SETTINGS)

Selecting this option has the effect that the calculation method that
the UC4 administrator has specified in the UC4 Variable UC_
CLIENT_SETTINGS using the key "ERT_METHOD" will be used
for the estimated runtime.

Fixed value

Enter a fixed value as the estimated runtime.


Format: "seconds"

Dyn. method

Selection list for the dynamic method that is used to calculate the
estimated runtime from the actual runtime.
Possible selection: average, linear regression, maximal value

from the last ... runs

Number of past runs that are considered for the ERT calculation.
Allowed values: 0 to 25.

+ ... %

Value in percent for an upward ERT correction.

Differences > ... % are


ignored

You can ignore possible huge deviations for the estimated runtime.

but do use ... runs at least

Number of past runs that should be considered regardless of


deviations. Allowed value: 0 to 25.

Show chart

Button for updating the estimated runtime according to the current


settings. A diagram is displayed in a separate window which
represents the last 25 ERT/RRT runs. An already open window will
be updated.

Reset values

Button for deleting the real and estimated runtimes.


After a security query, all stored runtimes will be cleared.

Upper limit (in percent) until which the real runtime should be used
to calculate the estimated runtime.

Maximum runtime
(MRT)
None

The maximum runtime is not monitored.

Automation Engine

Fixed value

231

The maximum runtime is monitored.


The allowed time is entered as a fixed value in the format
"hours:minutes:seconds". An action (ELSE condition) must be
specified which reacts when maximum runtime is exceeded.

ERT

The maximum runtime is monitored.


The valid estimated runtime (ERT) at the time of the task's
activation is used as the maximum runtime. An action (ELSE
condition) must be specified which reacts when maximum runtime
is exceeded.

+ ... %

A correction in percent can be specified for ERT for the maximum


runtime. The determined value is added to the estimated runtime.

Curr. date + day(s)


Time

The maximum runtime is monitored.

TimeZone

Selection of a TimeZone object.

Define a number of days and a particular time until which the task
must be finished. The starting point for the date calculation is the
task's real date. An action (ELSE condition) must be specified
which reacts when maximum runtime has been exceeded.

Minimum runtime (SRT)


None

The minimum runtime is not monitored.

Fixed value

The minimum runtime is monitored.


The minimum runtime is used as a fixed value in the format
"hours:minutes:seconds". An action (ELSE condition) must be
specified which reacts if the runtime falls below the minimum
runtime.

ERT

The minimum runtime is monitored.


The valid estimated runtime at the time of the task's activation is
used as the minimum runtime. An action (ELSE condition) must be
specified which reacts when runtime falls below the minimum
runtime.

- ... %

A correction value in percent can be specified for ERT for the


minimum runtime. The determined value is subtracted from the
estimated runtime.

Else
Cancel / Quit

With this checkbox being activated, the task will be canceled or


ended if the runtime has been exceeded. Only available when the
maximum runtime is monitored.

Execute

Selecting this checkbox determines a task's execution. You can


directly select an executable object. This task will be activated if
the runtime is above or below the expected value. Only available
when runtime is monitored.

Comments

232

Chapter3 Objects

A different definition of runtime monitoring can be used for tasks that run in a Workflow or are
activated using a "Schedule" object. You can define this in the properties of the affected objects
(Runtime tab). In doing so, you can implement specific requirements for runtime monitoring which
refer to the special context of Workflows or Schedules. The task settings that are defined in the
Workflow or Schedule override the settings that were made in the task itself.
By default, the settings for runtime monitoring as defined in the task also apply to the Workflow or
Schedule.

See also:
Runtime Evaluation
Runtime Monitoring
Process Tab
The Process tab is an object-type-specific tab in which processing instructions are stored in
UC4's scripting language.
Object class: Cockpit
Object class: Executable object
Object type (short name): CPIT

Description

The script is processed at Cockpit activation.


A Cockpit's script cannot contain JCL lines.

See also:

Automation Engine

233

Script Editor
About UC4 Scripts
SampleCollection
Documentation Tabs
Documentation tabs are user-defined and client-specific tabs which can be assigned to all UC4
objects.

All Documentation tabs that have been defined by the UC4 administrator in the UC4 variable
UC_OBJECT_DOCU are shown. Note that imported objects have their own documentation
tabs.
The Version Management tab displays the stored object versions if this function has been
activated.

Structured Documentation

Each of these tabs can also be displayed in structured form. Structured Documentation can be used
to split complex object information in well-arranged parts. Each documentation element can be used
to store texts, but also to define attributes.
You can also define links (e.g. to files, folders or to documents in the Intranet and Internet etc.) in
structured documentation. Files are then displayed with the associated program, folders are
opened, URLs call the standard browser etc. The particular actions depend on the installed
programs and the user's PC configuration.

234

Chapter3 Objects

New Documentation tabs initially only include the "Content" folder. This is your starting point for
creating a further structure. To create and edit this structure, you can use the following popup-menu
commands :
Command

Description

Add attribute

Creates a new attribute in the highlighted element.

Add node after

Inserts a new element after the highlighted element.

Add node before

Inserts a new element before the highlighted element.

Add node child

Creates a new element one level below the highlighted element.

Duplicate node

Duplicates the highlighted element and its attributes and contents.

Delete node

Deletes the highlighted element irrevocably.

You can create one or more attributes for each individual element. Basically, there are two different
types: text and enumeration. You can add one or more of these attributes to an element. Determine
the attribute's name and then select whether it is a text or an enumeration. In enumerations, you can
specify the entries that should be included.

Automation Engine

235

Names of elements and attributes should comply with the XML naming convention. Letters,
numbers and the characters "-", ".", "_" can be used. Keep the following rules in mind:
l
l
l
l

The first letter of a name must neither be a number, nor ".", nor "-".
The name must not include blanks.
Do not use colons as they are reserved characters.
Names must not begin with "XML", regardless if uppercase or lowercase letters are used.

Structured documentation can be read with specific script elements (XML_*).

Cockpit - Monitor
A Cockpit's monitor view is available while the object is being executed. You can specify in the
settings of the UserInterface whether it should open automatically when the object is activated.
A separate window displays for each active Cockpit.

236

Chapter3 Objects

The display elements represent the values and conditions that have been defined in the Cockpit
tab. These values and conditions are periodically refreshed and the display is updated when the
activities are refreshed or can be manually refreshed by clicking the F5 key.
The statistical overview, the last report and the properties of the display elements (write protected)
can be called by using the context menu commands . You can also quit the Cockpit
If you change the size of the monitor window, the size and position of the display elements are also
adjusted.However, these new sizes are not permanently stored
Calling the Monitor
Automatically

The Cockpit monitor automatically displays while the Cockpit is being


executed.
Select Options -> Settings -> Activity Refresh and check Cockpit in
the UserInterface.

Right-click the Cockpit Select Monitor in the context menu.


in the Activity Window
Cockpit selection in
the Activity Window

Select File -> Monitor in the UserInterface.

See also:
Cockpit
Cockpit Attributes
The following overview lists the attributes of a Cockpit object and describes their functions,
allowed values and ways of modification.

Automation Engine

Tab

237

Attribute

Labeling

Value

Access
Via:

ARCHIVE_
KEY1

Archive key 1

User-defined,
limited to 60 characters.

GET_ATT
:PUT_ATT,
predefined
variable

ARCHIVE_
KEY2

Archive key 2

User-defined,
limited to 20 characters.

GET_ATT
:PUT_ATT,
predefined
variable

DATE_
CREATED

Created on

The time stamp in the format "YYYYMM-DD HH:MM:SS"


If not available: "0000-00-00 00:00:00"

GET_ATT

DATE_
MODIFIED

Modified on

The time stamp in the format "YYYYMM-DD HH:MM:SS"


If not available: "0000-00-00 00:00:00"

GET_ATT

DCMODUS

Mode
UserInterface

"Y" - UserInterface is active


"N" - No UserInterface is active

GET_ATT

LAST_
DATE

Last used on

The time stamp in the format "YYYYMM-DD HH:MM:SS"


If not available: "0000-00-00 00:00:00"

GET_ATT,
predefined
variable

LAST_
USER

Last used by

The name of the User object,


limited to 200 characters.

GET_ATT,
predefined
variable

MAX_
RETCODE

ENDED_OK until
return code

User-defined,
limited to 11 characters.

GET_ATT
:PUT_ATT

MODIFY_
COUNT

Modified

The number of object modifications.

GET_ATT

OBJECT_
NAME

Object name

User-defined,
limited to 200 characters.

Change
Program

OBJECT_
TITLE

Title

User-defined,
limited to 255 characters.

GET_ATT,
:PUT_ATT,
predefined
variable

USAGE_
COUNT

Last used

The number of object usages.

GET_ATT,
predefined
variable

USER_
CREATED

Created by

The name of the User object,


limited to 200 characters.

GET_ATT,
predefined
variable

USER_
MODIFIED

Changed by

The name of the User object,


limited to 200 characters.

GET_ATT,
predefined
variable

See also:

238

Chapter3 Objects

Cockpit
Attributes
:PUT_ATT Statement
GET_ATT Function
UC4.DB Change

3.2.7 CodeTable
CodeTable
CodeTables define a complete character set.
Object class: Passive object
Object type (short name): CODE

Description

Some operating systems and applications supported by UC4 use special sets of characters. During
an exchange of data between UC4 and the operating systems and applications, these character
sets must be converted when necessary. This conversion is based on the character sets defined in
the "CodeTable" object. CodeTables are used for data transmission between the UC4 Automation
Engine and the agents, during file transfer from agent to agent, and during the preparation of data
sequences (UC4 Script).
The UC4 Automation Engine works with the UC_CODE CodeTable. If necessary, the characters in
this CodeTable are converted into characters which correspond to the target system's character
set. Likewise, characters must be converted from the target system's character set into UC_CODE
code table characters.
The UC_CODE code table and the agent code tables for operating systems and applications are
supplied in client 0000. Of course, the CodeTables contain default character sets for all supported
target systems and should be able to be implemented without difficulty.
CodeTable

Target System

Character Set

ASCII_850

MS DOS

With German umlauts

BS2000_DEUTSCH

BS2000

With German umlauts

BS2000_EDF041

BS2000

In accordance with EDF041

BS2000_
INTERNATIONAL

BS2000

Alphanumeric with special characters

CODE

Template for new code tables to be created

EBCDIC_00037

USA

EBCDIC_00237

OS/400

Germany and Austria

EBCDIC_00500

International

EBCDIC_01141

Germany and Austria, with symbol

IBM_3270_DEUTSCH

With German umlauts

IBM_3270_
INTERNATIONAL

z/OS

International

Automation Engine

UC_CODE

MPE
NSK
Oracle
Applications
PeopleSoft
SAP
UNIX
VMS
Windows

239

Basic character set used by UC4

Creation of new CodeTables


In some cases, it can become necessary to use a code table which differs from the supplied code
tables. If so, a separate CodeTable must be created in such a way that a client 0000 code table
having the most similar character set is duplicated and adapted. Should a CodeTable be valid only
for a particular client, it can also be duplicated directly into a local client and changed by an
authorized user. The newly created code table can now be selected in the "FileTransfer" object and
used.
CodeTables in local clients cannot use the same object names as those used by the
CodeTables from the system client. CodeTables with which the agents work by default must
always be saved in client 0000. For reasons of security and clarity, it is recommended that
CodeTables be saved exclusively in client 0000. This is the simplest way to ensure that only
authorized users can make changes to these CodeTables.

See also:
CodeTables - Usage
Header tab
The Header tab is a general tab which is available in every UC4 object.

240

Chapter3 Objects

Description

Field/Control

Description

Title

Define object titles here. This title should contain a short and
characteristic description of the corresponding object as it is displayed
in all overviews.

Created

Indicates the user who created this object including the date and time.

Modified

Indicates the user who last modified this object including the date and
time. The number of times the object has been modified is displayed to
the right.

Last used

Indicates user, date and time regarding the most recent use of the
object. The number of times the object has been used is displayed to
the right.

Code Tab
The Code tab is object type-specific and is only available in "CodeTable" objects. It contains the
table for the conversion of character sets.
Object: CodeTable
Object class: Passive object
Object type (short name): CODE

Description

CodeTable definitions can be specified in the Code tab. Codes are assigned in a table through
editing the fields. Codes can be displayed in ASCII or hexadecimal format. Use the context menu to
change the display which also provides access to the properties of the particular highlighted field.

Automation Engine

241

Activate the option Text characters if this character should be considered for the conversion. The
particular fields are then shown in color in the Code tab. When processing Jobs and FileTransfers,
these characters are then converted in accordance with the CodeTable - i.e. the character is first
searched in CodeTable1 and then compared to the one in CodeTable2. The alternative character is
used if the requested character is not found.
Only one character can be defined as alternative character.
The attributes 3 to 8 are always displayed gray because they are currently not in use.
The most common CodeTables are supplied with UC4 in order to assure smooth FileTransfers. In
some special cases, it might become necessary to customize CodeTables. You can also create
your own CodeTables which convert exactly to your requirements.

See also:
CodeTable - Usage
Documentation Tabs
Documentation tabs are user-defined and client-specific tabs that can be assigned to all UC4
objects.

242

Chapter3 Objects

All Documentation tabs that have been defined by the UC4 administrator in the UC4 variable
UC_OBJECT_DOCU are shown. Note that imported objects have their own documentation
tabs.
The Version Management tab displays the stored object versions if this function has been
activated.

Structured Documentation

Each of these tabs can also be displayed in structured form. Structured Documentation can be used
to split complex object information in well-arranged parts. Each documentation element can be used
to store texts, but also to define attributes.
You can also define links (e.g. to files, folders or to documents in the Intranet and Internet etc.) in
structured documentation. Files are then displayed with the associated program, folders are
opened, URLs call the standard browser etc. The particular actions depend on the installed
programs and the user's PC configuration.

Automation Engine

243

New Documentation tabs initially only include the "Content" folder. This is your starting point for
creating a further structure. To create and edit this structure, you can use the following popup-menu
commands :
Command

Description

Add attribute

Creates a new attribute in the highlighted element.

Add node after

Inserts a new element after the highlighted element.

Add node before

Inserts a new element before the highlighted element.

Add node child

Creates a new element one level below the highlighted element.

Duplicate node

Duplicates the highlighted element and its attributes and contents.

Delete node

Deletes the highlighted element irrevocably.

You can create one or more attributes for each individual element. Basically, there are two different
types: text and enumeration. You can add one or more of these attributes to an element. Determine
the attribute's name and then select whether it is a text or an enumeration. In enumerations, you can
specify the entries that should be included.

244

Chapter3 Objects

Names of elements and attributes should comply with the XML naming convention. Letters,
numbers and the characters "-", ".", "_" can be used. Keep the following rules in mind:
l
l
l
l

The first letter of a name must neither be a number, nor ".", nor "-".
The name must not include blanks.
Do not use colons as they are reserved characters.
Names must not begin with "XML", regardless if uppercase or lowercase letters are used.

Structured documentation can be read with specific script elements (XML_*).

CodeTable - Usage
The following document informs about the character sets UC4 uses system internally.

Automation Engine

245

Diagram of Data Traffic

UC4 Automation Engine

UC4 basically uses UC_CODE for the data traffic between the UC4 Automation Engines and
agents and between the agents themselves.
UC4 Automation
Engine

CodeTable

Windows

UC_CODE

UNIX

UC_CODE

Data is saved in the database in accordance with the settings made in the database interface. Be
careful when installing the database and configuring the database interface that the correct
character set and the correct code conversion are set.

246

Chapter3 Objects

Agent

The CodeTable name used an agent by default can be defined in its INI file. CodeTable names are
assigned with the parameter UC_HOST_CODE= in the section [VARIABLES].
When the agent logs on to the UC4 Automation Engine, the UC4 Automation Engine stores the
CodeTable names for this particular agent in its internal host table. The UC4 Automation Engine
reads the CodeTable from client 0000 and transfers it to the agent. The agent then uses this
CodeTable for all Jobs and FileTransfers which do not require different CodeTables.
CodeTables used by agents by default must always be stored in client 0000. Modifications
made in these CodeTables are take effect after a re-logon to the UC4 Automation Engine.
Default CodeTables of Agents
Agent

CodeTable

BS2000

BS2000_DEUTSCH

Database

UC_CODE

GCOS8

UC_CODE

JMX

UC_CODE

MPE

UC_CODE

NSK

UC_CODE

Oracle
Applications

UC_CODE

z/OS

IBM_3270_INTERNATIONAL

OS/400

EBCDIC_00273

PeopleSoft

UC_CODE

SAP

UC_CODE

Siebel

UC_CODE

UNIX

UC_CODE

VMS

UC_CODE

Windows

UC_CODE

Agent - Job Execution

If a particular CodeTable was not specified for a job, the default CodeTable of the agent used for
executing this particular job applies. The UC4 Automation Engine sends the job data (JCL) using
UC_CODE to the agent. The agent converts the JCL (if required) according to the target system's
character set. In doing so, the agent uses the default CodeTable sent to it by the UC4 Automation
Engine during the login procedure. The job is saved in the defined working directory. After job
execution, the agent reads the report from this file. The report is converted in accordance with the
character set of UC_CODE and sent to the UC4 Automation Engine.
If a job does not use the default CodeTable - but instead, for example, an ASCII character set for
DOS outputs in Windows - this CodeTable is first sent to the agent. In doing so, the UC4
Automation Engine starts searching this CodeTable in the local client. If this CodeTable is not found

Automation Engine

247

there, the CodeTable of client 0000 is used. This CodeTable, however, is only valid temporarily and
is exclusively used for this particular job's JCL and report.

Agent - FileTransfer

If particular CodeTables were not specified for FileTransfers, the default CodeTables of the involved
agents apply. The agent converts the source file to UC_CODE (if required) and sends it to the
partner agent. It is then converted from UC_CODE to the character set of the particular agent's
default CodeTable and written to the target file.
For FileTransfers, a CodeTable can explicitly be specified for sending and/or receiving agent(s).
This is essential when the contents of the file to be transferred do not comply with the default
CodeTables of the involved agents. The UC4 Automation Engine sends the required CodeTable to
the agent so that it can correctly convert the file's contents. Explicitly specified CodeTables are
only valid on a temporary basis and for the current FileTransfer. Subsequent FileTransfers and Jobs
are not affected.
It is also possible to create and use individual CodeTables for particular requirements. If these
are stored in the local client, they must not have the same object names as the CodeTables in
the system client.
Refer to the System Overview to see which CodeTables are used by the individual agents by
default.

3.2.8 Connection
Connection
Connection objects contain the connection parameters for RA Solutions, RA jobs and SAP
agents.
Object class: System object
Object type (short name): CONN
The Connection objects of RA Solutionsdiffer from the standard Connection objects that UC4
supplies. More detailed information about tabs is provided in the description of the relevant RA
Solution.
Header tab
The Header tab is a general tab which is available in every UC4 object.
Object: Connection
Object class: System object
Object type (short name): CONN

248

Chapter3 Objects

Description

Field/Control

Description

Header
Title

Define object titles here. This title should contain a short and characteristic
description of the corresponding object as it is displayed in all overviews.

Created

Indicates the user who created this object, the day and time.

Modified

Indicates the user who last modified this object, the day and time. The number
of modifications made is displayed on the far right.

Last used

Indicates the user who last used this object, the day and time. The number of
times the object has been used is displayed on the far right. You define this
function in the UC4 variable UC_SYSTEM_SETTINGS.

Archive keys

Two key words of your choice can be specified here.

Attributes Tab
The Attributes tab is object type-specific and is only available in objects of type "Connection"
(R3). It determines the connection type.
Object: Connection
Object class: System object
Object type (short name): CONN

Automation Engine

249

Description

Depending on the selected type, the object displays a tab in which the corresponding connection
parameters can be specified.

Remote Function Call Tab


The Remote Function Call tab is object type-specific and is only available in objects of type
"Connection". It is automatically displayed if the connection type "Remote Function Call" has
been selected in the Attributes tab.
Object: Connection
Object class: System object
Object type (short name): CONN

General tab
[General tab] [Secure Network Connection tab] [Interfaces tab]

250

Chapter3 Objects

Field/Element

Description

Connection Type

You can select whether the connection should be established to a


specific application server or via a balanced or group selection.

max. concurrent
connections

The agent dynamically administers the connections to the SAP


system. If one connection is busy, another one opens automatically.
This parameter determines the maximum number of simultaneous RFC
connections that the SAP can open per login combination (SAP client,
SAP user, SAP login language).
UC4 recommends specifying an unlimited setting (default value, no
value specified). Instead, match the Agent's resource setting (to be
configured in the UC4 Variable UC_HOSTCHAR- WORKLOAD_
MAX_JOB or the System Overview) with the number of SAP batch
processes. The advantage is that Jobs do not become active on the
Agent's side if the resource limit has been reached.
Note that to use an unlimited number of RFC connections you need to
configure this in SAP (see SAP note 314530).
Default value:unlimited

Connection
parameters for
"Specific
Application Server"
Application Server

The name of the application server.

System Number

The number of the SAP system (such as 00).

System Name

The system ID of the SAP system (such as T40).

SAP Router String

The name of the SAP router.

Automation Engine

Field/Element

Description

Connection
parameters for
"Balanced/Group
Selection"
System Name

The system ID of the SAP system (such as T40).

Message Server

The name of the message server.

SAPRouter String

The name of the SAP router.

Group

The name of the login group.

Login data
Client

The number of the SAP client.

User

The name of the SAP user.

Password

The password of the SAP user.

Language

SAP-specific short name for the login language.

Alternative Login

The Login object from which the login data (client, user, password) is
retrieved.

Secure Network Connection tab


[General tab] [Secure Network Connection tab] [Interfaces tab]

251

252

Chapter3 Objects

Field/Element

Description

Enable Secure
Network Connection
(SNC)

This activates or deactivates SNC mode.

Path to library which


provides SNC service

The name of the local SNC library.

Level of Security

The SNC service quality.

SNC Partner name

The name of the SNC partner system.

My name (overrides
default)

The own SNC name (optional).

Interfaces tab
[General tab ] [Secure Network Connection tab] [Interfaces tab]

Field/Element

Description

BC-XBP
Use UC4Interface

Activate this option if the SAP agent should use the default interface
plus the UC4 Interface.

Combine Job steps

This option can be used to combine the script elements R3_


ACTIVATE_REPORT, R3_ACTIVATE_EXT_PROGRAM and R3_
ACTIVATE_EXT_COMMAND in SAP in one Job if they are used in
immediate succession.

Automation Engine

Field/Element

Description

Interface version

The interface version of the XBP interface.

253

The setting "default" means that the SAP agent queries the SAP
system about the interface version in use.
For further information about the XBP interface refer to the SAP
documentation:
SAP Interface Repository: http://ifr.sap.com.
SAP Help Portal: http://help.sap.com.
Audit level

XMI log monitoring level

Block size in KBfor


Spool lists

The SAP spool is transferred block by block. UC4 recommends using


the default value because it will also be applied if this field does not
include a value or if value 0 has been specified.

BW-SCH
Allow parallel
execution of same
chain

With this option activated, the system allows a process chain to run
multiple times parallel.
The parallel execution of a process chain can result in a Dialog
service process in the BW Application Server being constantly
occupied.

Extended
InfoPackage
monitoring

Status monitoring type of the InfoPackage.

No extended
monitoring

No modification, present status monitoring continues .

Monitor until
MAXRUNTIME

It the technical status "Red" occurs, status monitoring continues until


the point in time specified in the parameter MAXRUNTIME= of the
script element BW_ACTIVATE_INFOPACKAGE or until the status
changes.

Repeat status check


... x

It the technical status "Red" occurs, status monitoring continues n


times. If the status changes, monitoring continues. If the status does
not change, the Job ends or aborts depending on the specification
made in the parameter ERROR=.

Repeat Data Request


checks

This parameter can be used to define how often BAPI_ISREQUEST_


GETSTATUS should be called if it returns an error message.
Default value:"0"
This is a workaround for a SAP error. More details are available in
the SAP note 672353.

254

Chapter3 Objects

Field/Element

Description

ipak change method

This option causes various technical calls of BAPI_IPAK_CHANGE.


"0" - No modification, present procedure continues.
"1" - BAPI_IPAK_CHANGE is called without using the parameter
SELECTIONS.
"2" - BAPI_IPAK_CHANGE is called with the parameter
SELECTIONS being empty.
"3" - BAPI_IPAK_CHANGE is no longer called. UC4 expects that the
start type "Immediately" has been specified in the Job object.
"4" - BAPI_IPAK_CHANGE is called using the following parameters:
INFOPACKAGE: The technical name of the InfoPackage (mandatory).
SCHEDULING_PARAMS: Previously read with BAPI_IPAK_
GETDETAILS, STARTTYP=I
INFO_CUBES: Only if BAPI_IPAK_GETDETAILS also supplies Info
Cubes.
RETURN: The export parameters, return information.

BC-XAL
Interface version

The version of the XAL interface.


The setting "default" means that the SAP agent queries the SAP
system about the interface version in use.

Enable system log on


failure

Activate this option if the report SLOG should be generated and


displayed in the report tab "SAP system log". It contains current SAP
system log messages if a SAP job has been canceled.

Monitor Set

The name of the monitor set.


For example: "SAP CCMS Monitor Templates"

Monitor

The name of the monitor.


For example: "Syslog"

MTSName

The short name of the monitor.


For example: "Background"

SMSE

The SMSE (Solution Manager Scheduling Enabler) interface.

Enable

This starts the RFC Server for the SMSEinterface and activates the
relevant settings.

UC4 User

The login data for the UC4 system


Note that you must specify the client, user name, department and the
password. Make sure that the user exists in the specified client.

RFC Server

The settings for the connection to the SAP system and for registering
the RFC Server.

Gateway host

The host name of the SAP gateway.

Gateway service

The service of the SAP gateway.

Program ID

The program ID.

RFC Destination

The name of the RFC destination.

Automation Engine

255

Internet Tab
The Internet tab is object type-specific and is only available in objects of type "Connection". It is
automatically displayed if the connection type "Internet" has been selected in the Attributes tab.

Object: Connection
Object class: System object
Object type (short name): CONN

Description

Field/Element

Description

Connection
Parameters
URL

URL to Java Scheduler


http://Server
name:Port/scheduler~runtime~gate~web/JXBPWebService
URLto Process Integration
http://Server name:Port
URL to System Landscape Directory
http://Server name:Port/sld/ds

The port is generally 50000.

256

Chapter3 Objects

Login Data
User

Name of the user

Password

Password of the user

Alternative Login

Login object from which the login data (user, password) is retrieved.

DB Tab
The DB tab is object type-specific and is only available in "Connection" objects of type
"Database".
Object: Connection
Object class: System object
Object type (short name): CONN

Connection objects of type "Database" are required for SQL variables that read their values from the
specified database when they are accessed. You can specify the Connection object which should
be used in the Variable tab.
Field/Element
Connection
parameters

Description

Automation Engine

Field/Element

Description

Database type

Type of database to which a connection should be established.

257

Example: Oracle
Possible database types:
l
l
l
l
l
l
l
l

Microsoft SQL Server


Oracle
IBM DB2
Sybase
MySQL
Informix
Oracle OCI (RAC)
SAP HANA

Server

Name of the computer on which the database is available.

Port

Port number for computer access.


If you specify the value "0", the Database Agent itself attempts to find a
suitable port.

Database

Name of the database that should be used.

Login Data
User

Name of the database user.

Password

Password of the database user.

Alternative Login

Login object whose login data (user, password) is used.

Test connection

An attempt is made to establish a connection to the database with the


specified parameters. Doing so requires a particular Database Agent
(for Variables) and a Login object to be selected via a separate dialog. A
Message Window displays the result of this test connection.

Additional
parameters
Parameters

Name of the parameter that should additionally be used to access the


database.
Example: MARSCONNECTION

Value

Value for the additional parameter.


Example for the parameter MARSCONNECTION: TRUE

The Connection String and Connection Properties tabs can be used to define how the additional
parameter should be passed on.
Documentation Tabs
Documentation tabs are user-defined and client-specific tabs which can be assigned to all UC4
objects.
Object: Connection
Object class: System object
Object type (short name): CONN

258

Chapter3 Objects

All Documentation tabs that have been defined by the UC4 administrator in the UC4 variable
UC_OBJECT_DOCU are shown. Note that imported objects have their own documentation
tabs.
The Version Management tab displays the stored object versions if this function has been
activated.

Structured Documentation

Each of these tabs can also be displayed in structured form. Structured documentation can be used
to split complex object information in well-arranged parts. Each documentation element can be used
to store texts, but also to define attributes.
You can also define links (e.g. to files, folders or to documents in the intranet and Internet etc.) in
structured documentation. Files are then displayed with the associated program, folders are
opened, URLs call the standard browser etc. The particular actions depend on the installed
programs and the user's PC configuration.

Automation Engine

259

New Documentation tabs initially only include the "Content" folder. This is your starting point for
creating a further structure. To create and edit this structure, you can use the following context
menu commands:
Command

Description

Add attribute

Creates a new attribute in the highlighted element.

Add node after

Inserts a new element after the highlighted element.

Add node before

Inserts a new element before the highlighted element.

Add node child

Creates a new element one level below the highlighted element.

Duplicate node

Duplicates the highlighted element and its attributes and contents.

Delete node

Deletes the highlighted element irrevocably.

You can create one or more attributes for each individual element. Basically, there are two different
types: text and enumeration. You can add one or more of these attributes to an element. Determine
the attribute's name and then select whether it is a text or an enumeration. In enumerations, you can
specify the entries it should include.

260

Chapter3 Objects

Names of elements and attributes should comply with the XML naming convention. Letters,
numbers and the characters "-", ".", "_" can be used. Keep the following rules in mind:
l
l
l
l

The first letter of a name must neither be a number nor "." nor "-".
The name must not include blanks.
Do not use colons as they are reserved characters.
Names must not begin with "XML", regardless if uppercase or lowercase letters are used.

Structured documentation can be read with specific script elements (XML_*).

3.2.9 Dashboard
Dashboard
This object represents a dashboard that is used by the product Enterprise Control Center (ECC).
Dashboards are not used within the Automation Engine.
Object class: Passive object
Object type (short form): DASH
Header tab
The Header tab is a general tab which is available in every UC4 object.

Automation Engine

261

Description

Field/Control

Description

Header
Title

Define object titles here. This title should contain a short and
characteristic description of the corresponding object as it is displayed
in all overviews.

Created

Indicates the user who created this object including the date and time.

Modified

Indicates the user who last modified this object including the date and
time. The number of times the object has been modified is displayed to
the right.

Last used

Indicates the user who last used the object including the date and time.
The number of times the object has been used is displayed to the right.

Archive keys

Two keywords of your choice can be specified.

Documentation Tabs
Documentation tabs are user-defined and client-specific tabs that can be assigned to all UC4
objects.

262

Chapter3 Objects

All Documentation tabs that have been defined by the UC4 administrator in the UC4 variable
UC_OBJECT_DOCU are shown. Note that imported objects have their own documentation tabs.
By default, RA Solutions contain the Documentation tab Signature which contains the RA
Solution's signature data.
The Version Management tab displays the stored object versions if this function has been
activated.

Structured Documentation

Each of these tabs can also be displayed in structured form. Structured documentation can be used
to split complex object information in well-arranged parts. Each documentation element can be used
to store texts, but also to define attributes.
You can also define links (e.g. to files, folders or to documents in the intranet and Internet etc.) in
structured documentation. Files are then displayed with the associated program, folders are
opened, URLs call the standard browser etc. The particular actions depend on the installed
programs and the user's PC configuration.

Automation Engine

263

New Documentation tabs initially only include the "Content" folder. This is your starting point for
creating a further structure. To create and edit this structure, you can use the following context
menu commands:
Command

Description

Add attribute

Creates a new attribute in the highlighted element.

Add node after

Inserts a new element after the highlighted element.

Add node before

Inserts a new element before the highlighted element.

Add node child

Creates a new element one level below the highlighted element.

Duplicate node

Duplicates the highlighted element and its attributes and contents.

Delete node

Deletes the highlighted element irrevocably.

You can create one or more attributes for each individual element. Basically, there are two different
types: text and enumeration. You can add one or more of these attributes to an element. Determine
the attribute's name and then select whether it is a text or an enumeration. In enumerations, you can
specify the entries that should be included.

264

Chapter3 Objects

Names of elements and attributes should comply with the XML naming convention. Letters,
numbers and the characters "-", ".", "_" can be used. Keep the following rules in mind:
l
l
l
l

The first letter of a name must neither be a number nor "." nor "-".
The name must not include blanks.
Do not use colons as they are reserved characters.
Names must not begin with "XML", regardless if uppercase or lowercase letters are used.

Structured documentation can be read with specific script elements (XML_*).

3.2.10 Documentation
Documentation
This object serves to administer the documentation of any desired client. Use it for describing
complex interrelations such as the coaction of several objects.
Object class: Passive object
Object type (short name): DOCU
Individual Documentation tabs can be defined in the UC4 variable UC_OBJECT_DOCU for this
particular object type or for all object types "*".
The Version Management tab displays the saved versions of the UC4 object if this function was
activated in the UC4 Variable UC_CLIENT_SETTINGS.
Header tab
The Header tab is a general tab which is availablein every UC4 object.

Automation Engine

265

Description

Field/Control

Description

Title

Define object titles here. This title should contain a short and
characteristic description of the corresponding object as it is displayed
in all overviews.

Created

Indicates the user who created this object including the date and time.

Modified

Indicates the user who last modified this object including the date and
time. The number of times the object has been modified is displayed to
the right.

Last used

Indicates user, date and time regarding the most recent use of the
object. The number of times the object has been used is displayed to
the right.

Documentation Tabs
Documentation tabs are user-defined and client-specific tabs that can be assigned to all UC4
objects.

266

Chapter3 Objects

All Documentation tabs that have been defined by the UC4 administrator in the UC4 variable
UC_OBJECT_DOCU are shown. Note that imported objects have their own documentation
tabs.
The Version Management tab displays the stored object versions if this function has been
activated.

Structured Documentation

Each of these tabs can also be displayed in structured form. Structured Documentation can be used
to split complex object information in well-arranged parts. Each documentation element can be used
to store texts, but also to define attributes.
You can also define links (e.g. to files, folders or to documents in the Intranet and Internet etc.) in
structured documentation. Files are then displayed with the associated program, folders are
opened, URLs call the standard browser etc. The particular actions depend on the installed
programs and the user's PC configuration.

Automation Engine

267

New Documentation tabs initially only include the "Content" folder. This is your starting point for
creating a further structure. To create and edit this structure, you can use the following popup-menu
commands :
Command

Description

Add attribute

Creates a new attribute in the highlighted element.

Add node after

Inserts a new element after the highlighted element.

Add node before

Inserts a new element before the highlighted element.

Add node child

Creates a new element one level below the highlighted element.

Duplicate node

Duplicates the highlighted element and its attributes and contents.

Delete node

Deletes the highlighted element irrevocably.

You can create one or more attributes for each individual element. Basically, there are two different
types: text and enumeration. You can add one or more of these attributes to an element. Determine
the attribute's name and then select whether it is a text or an enumeration. In enumerations, you can
specify the entries that should be included.

268

Chapter3 Objects

Names of elements and attributes should comply with the XML naming convention. Letters,
numbers and the characters "-", ".", "_" can be used. Keep the following rules in mind:
l
l
l
l

The first letter of a name must neither be a number, nor ".", nor "-".
The name must not include blanks.
Do not use colons as they are reserved characters.
Names must not begin with "XML", regardless if uppercase or lowercase letters are used.

Structured documentation can be read with specific script elements (XML_*).

3.2.11 Event
Event
This object type serves to trigger Events on the basis of pre-defined conditions.
Object class: Executable object
Object type (short name): EVNT
The "! Process" tab is the core of each Event object. The processing statements specified here are
processed as soon as the defined condition applies.
The condition specified in the ! Process tab is the Event that is triggered.
The conditions that can be defined depend on the Event type. The following Event types are
available:
Event
type

Default
template

Description

Time

EVNT.TIME

The Event is triggered in the defined intervals.

Automation Engine

269

File
System

EVNT.FILE

It is checked in the defined intervals whether the condition of the


File System tab applies. If so, the Event is triggered.

Database

EVNT.DB

It is checked in the defined intervals whether the condition of the


Database tab applies. If so, the Event is triggered.

Console

EVNT.CONS

The Event is immediately triggered when all the conditions defined


in the Console tab apply.

Activated Event objects are mostly in the status "Sleeping". In Time Events, the status changes to
"Active" in the defined intervals and then the Event is triggered. The same is true for File System
Events and Database Events with the only exception being that the settings of the File System tab
are checked before the Event is triggered. Only if the specified settings apply (for example, the
defined number of files is exceeded), the Event is triggered. Console Events only react when the
settings specified in the Console tabs apply. They constantly monitor the Console messages - not
in intervals as the two other Event types. Console Events are always in the status "Sleeping".

See also:
! Process tab
File System tab
Database tab
Console tab"
Header tab
The Header tab is a general tab which is available in every UC4 object.

270

Chapter3 Objects

Description

Field/Control

Description

Header
Title

Define object titles here. This title should contain a short and
characteristic description of the corresponding object as it is displayed
in all overviews.

Created

Indicates the user who created this object including the date and time.

Modified

Indicates the user who last modified this object including the date and
time. The number of times the object has been modified is displayed to
the right.

Last used

Indicates user, date and time regarding the most recent use of the
object. The number of times the object has been used is displayed to
the right.

Active

With this option being deactivated, the object will automatically be set
to inactive after its activation and not processed.
Therefore, the tasks obtain the status ENDED_INACTIVE_OBJECT
(return code: 1925).
This setting is available in the Header tab of all executable objects and
is set by default.

Archive keys

Two keywords of your choice can be specified in all executable objects


and the Sync object. These keys are written to the statistical data each
time the object is processed.
Statistical data can be selected using these archive keys. Archive keys
are displayed in the Statistical Overview and can be printed.

Extended Reports

Extended reports can be written for all executable objects. They log the
complete script with all Includes, the generated JCL of Jobs or
accesses to UC4 objects.

Default (UC_
CLIENT_SETTINGS)

If you select this option the reports the UC4 administrator defined in the
UC4 Variable UC_CLIENT_SETTINGS with the key "EXT_
REPORTS" are generated.

All

All extended reports are written for this object.


This option overwrites possible pre-settings of the client.

None

No extended reports are written for this object.


This option overwrites possible pre-settings of the client.

Sync Tab
The Sync tab is object-type specific and is available in all executable UC4 objects.
Sync objects synchronize task on the basis of defined conditions. Enter one or several Sync
objects including the actions that should be taken in this tab if you want to make use of this
possibility.

Automation Engine

271

The Sync objects are checked one after the other when the task starts. The UC4 Automation
Engine tries to use the Sync object of the first line by calling the start action. If this is not possible
because this is not allowed by the Sync object's current condition, the task waits, aborts or is
skipped. The type of reaction depends on the Else condition defined in the tab's last column. If
"wait" has been specified, the task waits until it can use the Sync object with the start action. Then
the UC4 Automation Engine checks the Sync object in the next line etc. The task starts as soon all
Sync objects could successfully be used. Depending on the task's end status, either an abend or
end action is processed.
Up to 500 Sync objects can be specified.
All Sync objects must not include a total of more than 5000 rules. Rules are defined actions that
are directly entered in the Sync object.
Task ends are administered by work processes but only the primary work process releases busy
Syncs. Because of this task allocation, it can take several seconds until a Sync is released after
a task has ended. In this case, the report entry includes a time stamp that shows a time that is
later than the task has ended. Such delays occur when the primary's work load is high or if it is
processing lots of Syncs.
Note that using many Sync objects and rules can reduce task clarity. UC4 recommends
reducing the number of Sync object to a minimum.

Description

Only actions that have been defined in the Sync object can be selected.
Field/Control

Description

Sync object

Selects the Sync object that should be used to synchronize the task.

272

Chapter3 Objects

Start action

Defines the action that should be taken when the task starts. If this is
not possible because of the Sync's status, the Else condition becomes
effective.

Abend action

This action is processed if the task aborts.

End action

This action is processed if the task ends successfully.

Else

You can define here what should happen to the task if the start action
cannot be executed:
l

l
l

The task should wait until the start action can be executed
(WAIT).
The task aborts (ABEND).
The task is skipped (SKIP).

See also:
Sync
Event - Calendar Tab
The Calendar tab is object type-specific and in this form only available in "Event" objects. In this
tab you can define Calendar, Calendar keyword and period (time) entries. An Event will only be
triggered if at least one of the entries applies or if there is no entry at all.

Description

Field/Control

Description

Calendar

Here you can select a Calendar.

Automation Engine

Keyword

273

A list appears that includes all the calendar keywords of the selected
calendar. Select the calendar keyword that should be applied for
running the Event object.
Note that when you select a Calendar, that you must also select a
Calendar keyword.

From

The beginning of the time period in which the Calendar and calendar
key should be considered.

To

The end of the time period in which the Calendar and calendar key
should be considered.
To use a time period, you must define a beginning and an end.

The calendar and time conditions are always checked before the Event is checked. The current date
and time are used as a reference and the Event's active TimeZone is also considered. This includes
that activating an Event and specifying a logical time does not make sense.
The Event is checked and triggered if at least one entry applies or if there is no entry.
Note that time specifications are checked for full minutes, i.e. the ending time 23:59 hours lasts
until 23:59:59. Hence, the Event can also be triggered in the last 59 seconds.
Calendar, calendar keyword and time period can be used in as follows:
l
l
l

Definition of Calendar and calendar keyword.


Definition of Calendar and calendar keyword including time period.
Definition of time period without Calendar and calendar keyword.

Attributes Tab
The Attributes tab is object type-specific and only available in "Event" objects.
It can be used to define start parameters.
Object: Event
Object class: Executable object
Object type (short name): EVNT

274

Chapter3 Objects

Description

Field/Control

Description

Attributes
Group

If the Event object should be started by a Group, this Group can be


selected here. If there is no entry, the Event object is activated
immediately.
Note that the entry specified in here is not considered if the Event
object is started through a Workflow, a Schedule or as a recurring task.

Queue

Selection of a Queue object in which the FileTransfer should be


processed. The FileTransfer automatically starts in the Client Queue
(object name: CLIENT_QUEUE) if nothing has been specified in this
field.

Int. Account

Specification of an internal account


Contents do not affect the UC4 system's internal processing. You can
access the attribute "Int. Account" with script elements and integrate it
in your processes.

Parallel running Tasks

Automation Engine

Max ...

275

Setting that defines the maximum number of parallel executions for this
Event object.
Allowed values: 0 to 99999
Default: 0 (no limit on tasks running parallel)
Examples:
Max. "1" - At any time, not more than one Event execution must be
available.
Max. "2" - At any time, not more then two active Event executions must
be available.
etc.

Else: Wait Abort

Instruction that defines how this Event object should be handled if the
execution exceeds the specified maximum number of tasks that can
run at the same time.
Wait = The Event object waits until execution is possible.
Abort = The Event object is interrupted.

UC4 Priority ... (0-255)

Priority that should be used to executed this job in UC4


Allowed values: 0 to 255
Default: 0
The priority the UC4 administrator specified in the UC4 Variable
UC_CLIENT_SETTINGS (key "TASK_PRIORITY") is used if you
select value "0".

TimeZone

TimeZone to be used

Generate at runtime

With this option being activated, the script is not executed at object
activation but only when it starts. These can be two different points in
time (for example, when the object is executed by a Workflow).

Event Tab
The Event tab is object type-specific and only available in "Event" objects. It can be used to
define Event monitoring.
Object: Event
Object class: Executable object
Object type (short name): EVNT
This tab is not displayed in Event objects of type "FileSystem". In this case, the settings can be
specified in the "FileSystem" tab.

276

Chapter3 Objects

The tab's content depends on the Event type. Time and Console Events do not require particular
settings while FileSystem Events do.
l

Time Events do not contain the execution option Until the first hit as they are used for
periodic monitoring.
Console Events generally only include the execution options "Repeated" and "Until the first
hit" as these permanently monitor the Console. All control elements of the Timer Control
section are therefore disabled.

Description

Field/Control

Description

Event
Check
Repeated

The Event object is activated periodically.

Single

The Event object is activated only once.

Until the first hit

The File System Event is activated until the specified condition applies.

Timer Control
Check in intervals of

Specify an interval (in minutes), in which the Event object should


become active.

Check time

Specify a time at which the event should become active every day.

First Check

Configuration for "Execution in intervals of"

When time has


expired

The Event object will become active for the first time after the
expiration of a specified time interval.

Automation Engine

277

Immediately

The Event object will become active for the first time upon its
activation, regardless of the specified time interval.

Start after check


time

Configuration for "Time of Execution"

Do not check

If the Event object starts after the specified time, it becomes active as
of the next day.

Check

If the Event object starts after the specified time it becomes


immediately active.

Some of the settings specified in this tab can be read at runtime. Script elements are used to
access the attributes of this object.
File System Tab
The File System tab is object-type specific and is only available in event-type objects. You can
use it to define the conditions of the various event types. This document describes the File
System tab of the file-system event type.
Object: Event
Object class: Executable object
Object type (short name): EVNT
Note that there are agents that do not support all options.

Description

Field/Element
File System

Description

278

Chapter3 Objects

Host

Select the name of the target system - the agent in the target system whose file system should to be monitored. You can also specify an
agent group.

Path

Specify a drive, a path or a signature to which the monitoring should


refer.
Depending on the respective target system, you can name files, drives,
volumes, paths, Generation Data Groups etc.
The wildcard characters "*" or "?" can be used. "*" stands for any
number of characters, "?" for exactly one.
The characters *and ? are always used as wildcard characters. Note
that you cannot use them to define specific files that include these
characters in their names.
Note that wildcard characters must not be used in paths.

Include subdirectories

Select this box to include files of sub-directories. This function is only


available for VMS, UNIX and Windows agents.
Note that activating this option affects the performance of your UC4
system negatively.

Event
Check

Condition that should be checked in the file system.


Allowed values:
PATH_SPACE_UNUSED - available memory or disk space (BS2000)
PATH_FILE_COUNT - number of files
PATH_SPACE_USED - used memory or disk space
FILESYSTEM_SPACE_FREE - free space of volumes (z/OS) or of a
drive (Windows)
FILE_SIZE - size of a file (the agent converts the file size and the
specified value into bytes so that both values can be compared).
Operator for the assignment of values
Specify a value to which the selected check and operator should refer.
The unit for measuring the value (such as bytes, KB, MB) can be
selected from a list. If the target system works with a different unit, it
will be converted accordingly.
Select "Host specific" if the measuring unit that is specified in the
target system (such as PAM pages in BS2000) should be used.
The list is disabled if selecting a particular unit is not useful (with
PATH_FILE_COUNT, for example).

and

Condition that should be checked in the file system.


Allowed values:
FILE_CHANGED - file's last modification time
FILE_STABLE - file-size modification

Automation Engine

within

279

Period that should be used for checking the last modification time or
file-size modification.
For example:within the past 6 hours

Consider All Files

If wildcard characters are used or sub-directories are included in the


search, a file can be found several times. You can select whether the
specified conditions must apply to all found files.
For performance reasons, you can specify a maximum number of
files that should be found. The UC4 administrator can determine the
upper limit in the UC4 Variable UC_HOSTCHAR_DEFAULT using
the key MAX_FILE_COUNT.

Check
Timer control

The possible settings in these two areas comply with the settings that
are specified in the Event tab.
The period in which a file system can be checked depends on the
settings that are made in the event area. For this reason, you can
specify the relevant options here and not in a separate tab.
The option Automatically is only displayed when an z/OS agent is
selected. The Event object now checks if the indicated file is being
closed and triggers an event.

Comments

The system checks in a pre-determined interval whether the condition that is specified in the File
System tab applies and if so, it triggers the event (such as !Process). You can define a condition in
the event area as shown below:
l
l
l

Only select a check in the first combo box (such as:PATH_FILE_COUNT > 50).
Only select a check in the second combo box (such as:FILE_STABLE within the past hour).
Select a check in both combo boxes. Both conditions must apply to have the event triggered
(such as: FILE_SIZE > 100 MB and FILE_CHANGED within the past half hour).

Note that you cannot use a combination of all conditions.


In !Process, you can use the function GET_EVENT_INFO in order to read the file name or size.
The script element GET_FILESYSTEM also supplies information about the file system.
FILE_CHANGED
The agent checks whether a particular file has been changed in the past n hours:minutes:seconds.
The file system event is processed until the first hit has been found. The first check is made as soon
as the Event object has been activated.
Selecting FILE_CHANGED has the effect that the frequency that the agent uses to check the
conditions cannot be specified in the Event object. In this case, the UC4 administrator
determines the interval in the UC4 Variable UC_HOSTCHAR_DEFAULT using the key
EVENT_CHECKINTERVAL.
For example:
FILE_CHANGED within the past three hours.
!Process is triggered if the outcome of the check is that the file has been changed within the past
three hours.

280

Chapter3 Objects

Under Windows, the creation date of a file changes when it is copied. The modification date
remains unchanged. Therefore, the Windows agent retrieves both data and uses the most recent
date for its check.
FILE_STABLE
The agent checks whether the file size has remained the same during the last n
hours:minutes:seconds. The first check is made as soon as the Event object has been activated.
You can use this option in order to react to the end of a file transfer, for example.
Selecting FILE_STABLE has the effect that the frequency that the agent uses to check the
conditions cannot be specified in the Event object. In this case, the UC4 administrator
determines the interval in the UC4 Variable UC_HOSTCHAR_DEFAULT using the key
EVENT_CHECKINTERVAL.
For example:
FILE_STABLE within the past hour.
!Process will only be triggered if the outcome of the check is that the file size has remained the
same within the past hour.
z/OS:Information on Volumes
You can use the Path entry field in order to name volumes using "VOL=Volume".
For example: "VOL=ALG*1" supplies information about all volumes that commence with ALG and
end with 1. Any characters can be used in between. In our example, they are limited to 4 characters
as the name of a volume consists of eight characters.
The closing of files can be monitored on z/OS.
The following applies for other operation systems such as UNIX, VMS and MPE:
PATH_SPACE_USED - Sum of file sizes in the specified path.

See also:
GET_EVENT_INFO
GET_FILESYSTEM
GDG support
Console Tab
The Console tab is object-type specific and it is only available in "Event" objects. It can be used
to define the conditions of particular Event types.
Object: Event
Object class: Executable object
Object type (short name): EVNT
Event type "Console" currently supports the monitoring of:
l
l
l
l
l
l

Console output in BS2000.


Console output in z/OS (Multiple Console Support - MCS).
Message queue in OS/400.
Events in SAP.
Status changes of XI communication channels.
Windows Event Viewer.

Automation Engine

281

The Event monitors the target system according to the specifications made in this tab. The script
statements and functions that are specified in the !Process tab are executed if conditions such as
the Event ID or message filter apply.
Occurring Events of type "Console" are always in the status "Sleeping."
Message filter specifications must always start with a wildcard character.

BS2000
[BS2000] [z/OS] [OS/400] [SAP] [Windows]

Description

Field/Control

Description

Event type Console


Host

Select the agent whose console output should be monitored. You can
also specify an AgentGroup.

Table
Message filter

Specify the console-output filter that should be searched.


You can use the wildcard characters "*" and "?". "*" stands for any
number of characters, "?" for one specific character.

282

Chapter3 Objects

Comments

In BS2000, you can monitor the console output. To do so, you must install the utility for the Console
UCXEB2xU. It should run parallel to the BS2000 agent.

z/OS
[BS2000] [z/OS] [OS/400] [SAP] [Windows]

Description

Field/Control

Description

Event type Console


Host

Select the agent whose console output should be monitored. You can
also specify an AgentGroup.

System name

Specify a filter for the user-defined system name that can be used to
distinguish various OS instances.
Maximum 8 digits.

OS-Name

Set a filter for the OS name as defined by IBM. Currently, it is always


"MVS."
Maximum 8 figures.

Table

Automation Engine

Job name

283

Select a filter for a job name (maximum 32 characters).


You can use the wildcard characters "*" and "?". "*" stands for any
number of characters, "?" for one specific character.

Message filter

Specify a filter for the console output (for example, *VOL01D*).


You can use the wildcard characters "*" and "?". "*" stands for any
number of characters, "?" for one specific character.

Comments

In z/OS, you can monitor the console output (Multiple Console Support - MCS). To do so, you must
install the Event Monitor UCXEMxx and start it with a corresponding entry in the z/OS agent's INI
file.

OS/400
[BS2000] [z/OS] [OS/400] [SAP] [Windows]

Description

Field/Control

Description

Event type Console


Host

Select the agent whose message queue should be monitored. You can
also specify an AgentGroup.

284

Chapter3 Objects

Message type

Specifies the message type.


Allowed values:
"01" - Completion
"02" - Diagnostic
"04" - Informational
"05" - Inquiry
"06" - Sender's copy
"08" - Request
"10" - Request with prompting
"14" - Notify (handled exception)
"15" - Escape (handled exception)
"16" - Notify (unhandled exception)
"17" - Escape (unhandled exception)
"21" - Reply, not validity checked
"22" - Reply, validity checked
"23" - Reply, message default used
"24" - Reply, system default used
"25" - Reply, from system reply list

Severity

Define the severity of the message.


Allowed values: "0" to "99"

Table
Message ID

Specify a filter for the message ID.


You can use the wildcard characters "*" and "?". "*" stands for any
number of characters, "?" for one specific character.

Message filter

Specify a filter for the message text.


You can use the wildcard characters "*" and "?". "*" stands for any
number of characters, "?" for one specific character.

Comments

In OS/400, you can monitor message queues. Use the OS/400 agent's INI file to define the
particular message queue that should be monitored.

SAP
[BS2000] [z/OS] [OS/400] [SAP] [Windows]

The SAP Console Event distinguishes several data sources.

Automation Engine

285

ABAP Event History

Description

Field/Control

Description

Event type Console


Host

Select an agent that is connected to the SAP system and whose


Events should be monitored. You can also specify an AgentGroup.

Data source

The ABAP Event history serves as the data source.

Table
Event ID

Filter for the name of the SAP ABAP Event.


You can use the wildcard characters "?" and "*". "?" for one specific
character, "*" stands for any number of characters.

Event Parameter

Filter for the parameter of the SAP ABAP Event.


You can use the wildcard characters "?" and "*". "?" for one specific
character, "*" stands for or any number of characters.

Event Server

Filter for the batch-server name of the SAP ABAP Event.


You can use the wildcard characters "?" and "*". "?" for one specific
character, "*" stands for or any number of characters.

Comments

XBP 3.0 is required in order to monitor SAP Events via the Event type "Console."
The XBP interface version that is used must be specified in the SAP agent's Connection object.

286

Chapter3 Objects

The agent periodically polls the SAP system for occurred SAP Events and reports them to the
active Console Events. The UC4 administrator can define the required interval in the UC4
Variable UC_HOSTCHAR_DEFAULT, key JOB_CHECKINTERVAL.
Note that as of version 8.00A, the SAP agent always uses the XBP interface. This includes that the
SAP criteria profiles must be adjusted in order to ensure that the selected triggered events are
logged in the Event History. Otherwise, the Console Event cannot react.
Use the transaction SM64 in order to create a criteria profile for the Event history.
The script function GET_EVENT_INFO supplies additional information about the SAP event.

Java Event History

Description

Field/Control

Description

Event-type Console
Host

Select an agent that is connected to the SAP system and whose


Events should be monitored. You can also specify an AgentGroup.

Data source

The Java Event History serves as the data source.

Table
Event Type

Selection of a filter for the type of SAP Java Scheduler Event.


The drop-down menu's content is retrieved from the UC4 Variable UC_
SAP_XJBP_EVENTTYPES which is available in the system client 0.
The Variable object is supplied with all possible Event types and should
not be changed by users.

Automation Engine

Event Parameter

287

Filter for the parameters of the SAP Java Scheduler Event.


You can use the wildcard characters "*" and "?". "?" stands for exactly
one, "*" for any number of characters.

Event Additional
Parameter

Filter for additional parameters of the SAP Java Scheduler Event.


You can use the wildcard characters "*" and "?". "?" stands for exactly
one, "*" for any number of characters.

Comments

The agent periodically polls the SAP system for occurred SAP Events and informs the active
Console Events. The UC4 administrator can define the interval in the UC4 Variable UC_
HOSTCHAR_DEFAULT, key JOB_CHECKINTERVAL.
The script function GET_EVENT_INFO supplies additional information about the SAP Event.

XI Communication Channels

Description

Field/Control

Description

Event type Console


Host

Select an agent which is connected to the XI system whose


communication channels should be monitored. You can also specify an
AgentGroup.

288

Chapter3 Objects

Login

Name of a Login object which contains the XI object.


Use different Login objects for SAP and XI systems if both are installed
on the same host. Otherwise, the Login entry would not be unique.
The Login object overrules the User specified in the Connection object.

Data source

XI communication channels serve as data source.

Table
Channel

Filter for the communication channel.


You can use the wildcard character "*".

Partner

Filter for the partner.


You can use the wildcard character "*".

Service

Filter for the service.


You can use the wildcard character "*".

State

Filter for the status.


Possible values: "ERROR", "OK", "INACTIVE", "UNKNOWN" and
"UNREGISTERED"

Activation state

Filter for the activation status.


Possible values: "STARTED" and "STOPPED"

Comments

The filter list describes the nominal status of one or several communication channels. An Event is
triggered for each communication channel that
l
l

Does not meet the nominal status when the Event object starts
Switches to a different status (regardless if nominal status or different).

No Event is triggered if the communication channel meets the nominal condition when the Event
object starts.
The script function GET_EVENT_INFO supplies additional information about the XI communication
channel.

Windows
[BS2000] [z/OS] [OS/400] [SAP] [Windows]

Automation Engine

289

Description

Field/Control

Description

Event type Console


Host

Select the agent whose Event Viewer should be monitored by


Windows. You can also specify an AgentGroup.

Type

Select the log that should be monitored from the list (system, security,
application, directory service, DNS server or File Replication Service).

Source

Determine the Windows Event's source.

Category

Enter the Windows Event's category.


The category is defined by the source that has logged the Event. It
combines Events of the same categorical value. Category names must
be numbers.
No particular category is filtered if value "0" has been specified.

Table
Event-ID

Enter the Event ID of the Windows Event.


No particular event ID is filtered if value "0" has been specified.

Type

Select the Windows Event's type from the list.

User

Specify a User to whom the Windows Event should be assigned.

Message filter

Specify a filter for the description of the Windows Event.


You can use the wildcard characters "*" and "?". "*" stands for any
number of characters, "?" for one specific character.

290

Chapter3 Objects

Comments

In Windows, you can monitor the Windows Event Viewer. The first step that is required in order to
react to particular messages is to analyze the Event Viewer. The required entries are provided in the
Event details. You can open them by double-clicking a line in the Windows Event Viewer.
In Microsoft Windows, message texts consist of static and variable parts. The Event only supplies
the variable message parts. If you use a message filter, the Event only reacts if variable message
parts are searched. Refer to the document that describes the script function GET_WIN_EVENT in
order to obtain more detailed information about querying a variable message text.
See also:
GET_CONSOLE
GET_WIN_EVENT
Database Tab
The Database tab is object type-specific and is only available in Event-type objects. It is
displayed in Database Events and includes the definition of two values that should be compared
to each other.
Object: Event
Object class: Executable object
Object type (short name): EVNT

The above tab shows three sections. Enter the first value in the section "Value 1" and the second
one in "Value 2". In the "Operator" section, select the operator that should be used in order to
compare the values as shown below:
Value1 Operator Value2
Operators:

Automation Engine
l
l
l
l
l
l
l

291

> (greater than)


< (less than)
= (equal to)
<> (not equal to)
>= (greater than or equal to)
<= (less than or equal to)
pattern ("Value 1" includes the values that are specified in "Value")

The following sources are available for values:


l
l
l

SQLquery
Statistical value
Variable object

The sources can be combined as you need them. For example, you can compare a value of an SQL
query with a Variable object, or a statistical value with an SQL query, or two values of different or
the same Variable object(s).
Time stamps of SQL queries and Variable objects are converted to the format "YYYY-MM-DD
HH:MM:SS".
Note that fractional digits are truncated. Read the values in !Process by using the script function
GET_EVENT_INFOand multiply them with 10n in order to move the commas. Subsequently,
the values in !Process are ready to be compared.
Examples:
123.44 * 100 (corresponds to 102) =12344
123.5555 * 10000 (corresponds to 104) = 12355555

SQL query

The value is retrieved from an SQL query.


SQL queries can only be processed by a Database Agent.
Field/Element

Description

SQL

SQL query.
Max. 4096 characters

Host

Name of the Database Agent that processes the SQL query.


AgentGroups cannot be selected in Database Events.

Login

Name of the Login object that is used to log on to the database.

292

Chapter3 Objects

Server

Name of the computer on which the database is available.


Format: Server name:Port
For example: PC01:2281
The default ports are:
l
l
l
l

MSSQLServer:1433
Oracle: 1521
DB2:50000
MySQL: 3306

Do not complete this field if the query should be made in an Oracle


database in RAC.
Database

Name of the database.

Only Microsoft
Access:file name

Path and file name of the MS Access database.

Click the button that shows three dots next to the text field SQL . An easy-to-handle editor opens in
which you can enter the SQL query. Fill in the text fields Server, database etc., and the right editor
section shows the corresponding database structure.
You can use object variables within an SQL query.
The Database Event does not abort if the SQL query is incorrect.
Note that some databases distinguish uppercase and lowercase characters.
Result:A value
If the SQL query returns a particular value, this value will be used.
Result: No value
!Process is not processed.
Result:NULL
The Database Event converts NULL to the string "NULL".
Result:Several values or data records
If the SQL query returns more than one value, the first value of the first data record is used.
Example of an SQL result:
Last name

First name

Location

Smith

John

Seattle

Green

Peter

New York

The Database Event uses the value "Smith".


Reading the results using GET_EVENT_INFO
The script element GET_EVENT_INFOcan be used to access the values of the SQL query in
!Process.
Note that the Database Event only reads the first 10 columns. Column contents that exceed 255
characters are truncated.

Automation Engine

293

Statistical value

The value is directly specified.


Field/Element

Description

Statistical value

Any value.
Max. 40 characters

Variable object

The value is retrieved from a Variable object.


Field/Element

Description

Variable object

Name of a static or dynamic Variable object

Key column (in static


Variable objects)
First value column (in
dynamic Variable
objects)

Value of the Key column or the first value column in order to determine
the Variable object's entry that should be used.
The value is retrieved from the Value 1 column (in static variables) or
the first value column (in dynamic variables).

The Database Event is not activated if the key does not exist in the specified Variable object.
If the key does not include a value, the reaction depends on the setting that has been defined in the
Variable object's Attributes tab. The system either logs an error message or uses the initial values.
The Database Event does not abort.

See also:
GET_EVENT_INFO
Runtime tab
The Runtime tab is an object-specific tab that is available in every executable object in UC4. It
can be used to specify parameters for a task's runtime behavior.

294

Chapter3 Objects

The Runtime tab is structured as follows:


l
l
l
l
l
l

Return code handling


Forecast setting
Evaluating the estimated runtime (Runtime Evaluation)
Monitoring the maximum runtime (Runtime Monitoring)
Monitoring the minimum runtime (Runtime Monitoring)
Reaction to runtimes that have been exceeded or not reached (Runtime Monitoring).

Description

Field/Control

Description

Definition for
ENDED_OK
Return Code <=

The maximum return code for a task's normal end.


A task ends normally (Status "ENDED_OK") if its return code lies
below or is equal to the specified maximum return code.

Else execute

You can execute an object if the task does not end with a return code
that lies within the ENDED_OK area.
Note that this object will not be processed if the task is terminated
by using the script statement :EXIT.

End status for


Forecast
Estimated runtime
(ERT)

A selection list for the end status that this task should return when you
make a forecast calculation.

Automation Engine

Current ERT =

295

Displays the task's next estimated runtime (ERT).


You can enter the estimated runtime here. This value applies until the
ERT calculation is made after the task's next execution.
Format: "hours:minutes:seconds".

Use default (UC_


CLIENT_SETTINGS)

Selecting this option has the effect that the calculation method that the
UC4 administrator specified in the UC4 Variable UC_CLIENT_
SETTINGS using the key "ERT_METHOD" is used to calculate the
estimated runtime.

Fixed value

A fixed value is entered as the estimated runtime.


Format: "seconds"

Dyn. method

Selection list for the dynamic method that is used to calculate the
estimated runtime from the real runtime.
Possible selection: Average, linear regression, maximal value

from the last ... runs

The number of past runs that are considered for the ERT calculation.
Allowed values: 0 to 25.

+ ... %

The value in percent for an upward ERT correction.

Differences > ... % are You can ignore possible huge differences to of actual runtimes.
ignored
Upper limit (in percent) for actual runtimes that should be included in
estimated runtime calculation.
but do use ... runs at
least

The number of past runs that should be considered regardless of


differences. Allowed value: 0 to 25.

Show Chart

A button that can be clicked in order to update the estimated runtime


according to the current settings. A diagram displays in a separate
window; it shows the last 25 ERT/RRT runs. Windows that are already
open are updated.

Reset Values

A button that can be used to delete the real and estimated runtimes.
A security query displays, confirm it and all saved runtimes are cleared.

Maximum runtime
(MRT)
None

The maximum runtime is not monitored.

Fixed value

The maximum runtime is monitored.


The allowed time is entered as a fixed value in the format
"hours:minutes:seconds". You must specify an action (ELSE
condition) that applies if the maximum runtime has been exceeded.

ERT

The maximum runtime is monitored.


The valid estimated runtime (ERT) at the time of the task's activation is
used as the maximum runtime. You must specify an action (ELSE
condition) that applies if the maximum runtime has been exceeded.

+ ... %

A correction in percent can be specified for ERT for the maximum


runtime. The determined value is added to the estimated runtime.

296

Chapter3 Objects

Curr. date + day(s)


Time

The maximum runtime is monitored.

TimeZone

Selection of a TimeZone object.

A number of days and time of day are set for when the task must be
finished. The starting point for the calculation of the date is the real date
of the task. You must specify an action (ELSE condition) that applies if
the maximum runtime has been exceeded.

Minimum runtime
(SRT)
None

The minimum runtime is not monitored.

Fixed value

The minimum runtime is monitored.


The allowed time is entered as a fixed value in the format
"hours:minutes:seconds". You must specify an action (ELSE
condition) that applies if the maximum runtime has been exceeded.

ERT

The minimum runtime is monitored.


The valid estimated runtime at the time of the task's activation is used
as its maximum runtime. You must specify an action (ELSE condition)
that applies if the maximum runtime has been exceeded.

- ... %

When you select the ERT, you can also specify a correction value in
percent for the maximum runtime. The value you determine is added to
the estimated runtime.

Else
Cancel / Quit

If you activate this check box is activated, the task is canceled or quit if
the runtime has been exceeded. Only available if the maximum runtime
is monitored.

Execute

If you activate this check box, you determine that the task is executed.
You can directly select the executable object. If the runtime is
exceeded or not reached, the specified task is executed. Only available
if the runtime is monitored.

Comments

A different type of runtime monitoring can be used for tasks that have been activated in a Workflow
or using the object "Schedule." You can define it in the properties of the relevant object (Runtime
tab). The setting that are defined within the context of a Workflow or Schedule overrule the settings
that have been defined in the task itself.
You can also assume these setting for runtime monitoring in the Workflow or Schedule. This is the
default setting.

See also:
Runtime Evaluation
Runtime Monitoring

Automation Engine

297

Variables & Prompts Tab


The Variables & Prompts tab is object type-specific and is available in almost every
executable object in UC4.
Object: Event
Object class: Executable object
Object type (short name): EVNT
This tab has two tasks:
l
l

It stores object variables.


It assigns PromptSet objects.

Object variables

Object variables include values that belong directly to the object and can be read in the Process
tabs. Variable names and values are determined in the table shown below.
In the Value column, you can also enter predefined variables. Do so using the Variables...
button in the object's toolbar.
The same rules apply for object variable names and for script variables. If you omit the preceding
"&", it is automatically added during the storing process and is available the next time the object
opens.
Object variables and PromptSet variables can be inherited from the superordinate object. For
example, a Schedule's tasks can use the object variables of the Schedule object.
Field/Element

Description

Inherit from parent


All variables (default)

The object obtains all object variables and PromptSet variables of


the superordinate task.

298

Chapter3 Objects

Only defined variables

The object only obtains the object variables of the superordinate


task that have been defined in its "Variables & Prompts" tab.
PromptSet variables are only inherited if the PromptSet object
complies with these values and the value that should be
overwritten has not been changed in the "Variables & Prompts"
tab.

No variables

The object obtains all object variables and PromptSet variables of


the superordinate task.

Note that inherited variables overwrite existing object variables if they have the same name. In
contrast, PromptSet variables are never overwritten.
The following procedure can be used if you want to overwrite PromptSet variables with the value
of a parent variable:
Open the task's Workflow or Schedule properties and switch to the Variables & Prompts tab.
Select the PromptSet area and use the Workflow's or Schedule's variable name as the value of
the relevant PromptSet element. If the particular PromptSet element is not a text field, click its
labeling.
PromptSet objects

In the Variables & Prompts tab, you can also select one or several PromptSet objects that should
be called during the activation process. In doing so, you can overwrite the default values of
PromptSet elements. These modifications do not affect the PromptSet object itself.
You can use the "+" and "-" buttons to add or remove PromptSet objects. Several PromptSet
objects are called from top to bottom. Use the arrow buttons if you want to change this order.
To adjust the task's PromptSet values, you directly modify the PromptSet elements.
Click on the blue description that displays next to the elements when you also want to use variables
in the default value. The effect is that the PromptSet elements now appear as a gray text field that
has the name of the related PromptSet variable. In this specific text field, you can either manually

Automation Engine

299

enter the predefined variables, or select them in a dialog that you call using the
button in the
toolbar.
Clicking the blue description again deletes your previous entries and the PromptSet element
appears in its original view.
Predefined variables are already deleted when the PromptSet input mask is called. Note that the
values of predefined variables can change during the object's execution (for example, with UC4
Script) but the PromptSet variable still stores the old value.
An error occurs when the object should be stored and an element's value does not fulfill the
limitations of the PromptSet properties (min. value, max. value, max. length, value required etc).
The affected fields are highlighted in yellow.
If the values differ from the reference values, an error only occurs when the object starts and an
attempt is made to send the prompt. Ensure that the data type and other limitations (min. value,
max. value, format) of the reference variable are preserved.
Using the same variable names has the effect that the object variable values are overwritten by
the PromptSet variables. The value of the PromptSet object that has last been called is used if
selected PromptSet objects include identical variable names.
Graphical elements that are removed from the PromptSet object are also removed from the
Variables & Prompts tab. Modifications made in the PromptSet object's default values do not
affect the Variables & Prompts tab. The values of the PromptSet object are only available
when the PromptSet object is newly selected.

See also:
Object Variable
Designer tab
Rollback Tab
The Rollback tab is an object-specific tab that is available in every executable object that can be
included in a Workflow.
The Rollback tab can be used to define actions that store the task (= Backup) and restore it (=
Rollback). These settings are only useful when the object runs in a Workflow because you can only
start a rollback process within a Workflow.
The backup and rollback functions are especially designed to undo erroneous installation and
deployment processes that are defined in the UC4 Deployment Manager but processed using
the Automation Engine.
Backup actions are will always be processed before the object runs and Rollback actions can only
be started via Workflows. For more information, see the related documentation.

300

Chapter3 Objects

Field/Element

Description

Enable Rollback

Use this to activate or deactivate the rollback settings..


When this option is deactivated, all the fields of this tab are
disabled.

Custom Rollback
Backup

Specify an executable object that is responsible for the


backup process.ed in the Backup object depend on the
relevant task's processes and actions. Note that you must
define them manually. For example, if you use the current
object to update your database, it is useful to backup the
database using the Backup object.
If you specify a Backup object, it will always automatically
run before the task runs, regardless of how the object is
activated.
The actions and steps that must be defined in the Backup
object depend on the processes and actions of the related
task. Note that you must define them manually. For
example, if you use an object to update your database, it is
useful to include a database using the Backup object.

Automation Engine

Rollback

301

Specify an executable object that is responsible for the


rollback process.
The definition of the Rollback object depends on the
current object or the Backup object and must be made
manually. The Rollback object's basic task is to undo
modifications in the case of an error in order to ensure that
a previous working status will be restored. For example, if
the Backup object creates a database backup, the
Rollback object should be able to restore this backup.
The Rollback object will be processed when the task
starts in Rollback mode which is only possible in a
Workflow.

Process Tab
The Process tab is a object-type-specific tab in which processing commands are stored in the
script language of UC4. The processing commands are processed at the time the Event is
activated.
Object: Event
Object class: Executable object
Object type (short name): EVNT

Description

The script is either processed at Event activation or start. This point in time depends on the setting
"Generate at runtime" which can be defined in the Attributes tab.

302

Chapter3 Objects

Processing commands which should be executed only at the occurrence of an Event must be
entered in the"! Process" tab.
An Event's script cannot contain JCL lines.

See also:
Script Editor
About UC4 Scripts
SampleCollection
! Process Tab
The ! Process tab is an object type-specific tab in which processing commands are stored in the
script language of UC4.The commands in this script are processed/executed when the event
occurs.
Object: Event
Object class: Executable object
Object type (short name): EVNT

Description

The "! Process" is processed every time the Event occurs.


An Event's "! Process" cannot contain JCL lines.

See also:
Script Editor
About UC4 Scripts
SampleCollection

Automation Engine

303

Documentation Tabs
Documentation tabs are user-defined and client-specific tabs which can be assigned to all UC4
objects.
All Documentation tabs that have been defined by the UC4 administrator in the UC4 variable
UC_OBJECT_DOCU are shown. Imported objects also have their own Documentation tabs.

The Version Management tab displays the stored object versions if this function has been
activated.

Structured Documentation

Each of these tabs can also be displayed in structured form. Structured Documentation can be used
to split complex object information in well-arranged parts. Each documentation element can be used
to store texts, but also to define attributes.
You can also define links (e.g. to files, folders or to documents in the Intranet and Internet etc.) in
structured documentation. Files are then displayed with the associated program, folders are
opened, URLs call the standard browser etc. The particular actions depend on the installed
programs and the user's PC configuration.

304

Chapter3 Objects

New Documentation tabs initially only include the "Content" folder. This is your starting point for
creating a further structure. To create and edit this structure, you can use the following popup-menu
commands :
Command

Description

Add attribute

Creates a new attribute in the highlighted element

Add node after

Inserts a new element after the highlighted element

Add node before

Inserts a new element before the highlighted element

Add node child

Creates a new element one level below the highlighted element

Duplicate node

Duplicates the highlighted element and its attributes and contents

Delete node

Deletes the highlighted element irrevocably

You can create one or more attributes for each individual element. Basically, there are two different
types: Text and Enumeration. You can add one or more of these attributes to an element. Determine
the attribute's name and then select whether it is a text or an enumeration. In enumerations, you can
specify the entries it should include.

Automation Engine

305

Names of elements and attributes should comply with the XML naming convention. Letters,
numbers and the characters "-", ".", "_" can be used. Keep the following rules in mind:
l
l
l
l

The first letter of a name must neither be a number, nor ".", nor "-".
The name must not include blanks.
Do not use colons as they are reserved characters.
Names must not begin with "XML", regardless if upper or lower case letters are used.

Structured documentation can be read with specific script elements (XML_*).

Event - Execution

Type-Specific Features

When you run an event, the system distinguishes event recognition and event handling.
Event recognition
After activation and start, the Event is in the condition SLEEPING. The system now permanently
monitors whether an Event occurs as previously specified. Event recognition distinguishes real
events and polling events.
l

Real Events:
A signal is generated if a real Event occurs. The responsible technical unit recognizes this
signal and creates a UC4 Event.
Real Events are messages on a BS2000 Console, SNMP Traps, UC4 internal signals
(Agent start, blocking status of a Workflow) or user signals via an interface, for example.

Polling Events:
No signal is generated if a polling Event occurs. Instead, the system periodically checks if an
Event of this type has occurred.
Polling Events are the presence or absence of particular files, the workload of the file

306

Chapter3 Objects
system, command results (analyzes of values and status information of the OS) or SNMP
values, for example.

Events can have values which means that a particular value is monitored. The Event is triggered as
soon as this value exceeds a defined limit. Events without values have no values to be monitored.
The occurrence of a defined condition represents the Event.
Event handling
Event handling is the processing of the !Process tab.
The post script of an Event is not processed at its activation time. It is processed when the defined
condition occurs. Active Event objects consider modifications made in !Process. As there is no
UserInterface available at that time, the same limitations apply as for Events that have been
generated at runtime.
Stop execution
A running Event object can be stopped and restarted at any time.
Handling
Right-click the object
Select Stop / Go in the context menu.
in the Activity Window.
End status
A normally ended Event ends on status ENDED_OK, a canceled object ends on status ENDED_
CANCEL.
A FileSystem Event which ends because of its runtime settings without the conditions having
occurred, it obtains the status ENDED_TIMEOUT.
Event - Restart

Type-Specific Features

Currently, the script is not processed when the Event is restarted.


Event Attributes
The following overview lists the attributes of an Event object and describes their functions,
allowed values and ways of modification.
The attributes of an event can only be written in the Process tab (when the event is activated).
The attempt to read or write an attribute that does not belong to the particular event type has the
effect that script processing will abort.

Attributes for all Event Types

Tab

Attribute

Description

Value

Access
Via:

Automation Engine

307

ARCHIVE_
KEY1

Archive key 1

User-defined,
limited to 60
characters.

GET_
ATT,
:PUT_
ATT,
Change
Program,
via script
variable,
predefined
variable

ARCHIVE_
KEY2

Archive key 2

User-defined,
limited to 20
characters.

GET_
ATT,
:PUT_
ATT,
Change
Program,
via script
variable,
predefined
variable

DATE_
CREATED

Created on

The time stamp in


the format "YYYYMM-DD
HH:MM:SS"
If not available:
"0000-00-00
00:00:00"

GET_ATT

DATE_
MODIFIED

Modified on

The time stamp in


the format "YYYYMM-DD
HH:MM:SS"
If not available:
"0000-00-00
00:00:00"

GET_ATT

DCMODUS

Mode UserInterface

"Y" - UserInterface
active
"N" - no
UserInterface active

GET_ATT

EVENT_
REPEAT

Event - Execution

"R" - Repeatedly
"S" - Single run
"F" - Until the first hit
is found.

GET_
ATT,
:PUT_
ATT

308

Chapter3 Objects

EVENT_TYPE,
EVENT_TYP

Event type

"CN" - Console
Event,
"DS" - Database
Event with time,
"DT" - Database
Event with interval
"FA" - File System
Event with
automatic
monitoring,
"FS" - File System
Event with time,
"FT" - File System
Event with interval
"TS" - Time Event
with time,
"TT" - Time Event
with interval

GET_
ATT,
predefined
variable

GEN_AT_
RUNTIME

Generate at runtime

"Y" - Yes, "N" - No

GET_ATT

GROUP

Group

The name of a
group,
limited to 200
characters.
" " - for immediate
start

GET_
ATT,
:PUT_
ATT,
Change
Program,
predefined
variable

INT_
ACCOUNT,
INT_ACC, K

Int. Account

User-defined,
limited to 16
characters.

GET_
ATT,
:PUT_
ATT,
Change
Program,
via script
variable,
predefined
variable

LAST_DATE

Last used on

The time stamp in


the format "YYYYMM-DD
HH:MM:SS"
If not available:
"0000-00-00
00:00:00"

GET_
ATT,
predefined
variable

LAST_USER

Last used by

The name of the


User object,
limited to 200
characters.

GET_
ATT,
predefined
variable

Automation Engine

309

MAX_
PARALLEL_
ELSE

Parallel running Tasks Else

"WAIT" - The event


waits until
processing is
possible.
"ABEND" - Event
processing is
interupted.

GET_
ATT,
:PUT_
ATT

MAX_
PARALLEL_
TASKS

Parallel running Tasks Max.

User-defined,
any value between
"0" and "99999".

GET_
ATT,
:PUT_
ATT,
predefined
variable

MAX_
RETCODE

ENDED_OK until
returncode

User-defined,
limited to 11
characters.

GET_
ATT,
:PUT_
ATT

MODIFY_
COUNT

Modified

The number of
object
modifications.

GET_ATT

OBJECT_
NAME

Object name

User-defined,
maximum 200
characters

Change
Program

OBJECT_
TITLE

Title

User-defined,
limited to 255
characters.

GET_
ATT,
:PUT_
ATT,
predefined
variable

PSCRIPT

The string in the Process tab of the event


should be changed.

Change
Program

QUEUE

Queue

GET_
ATT,
:PUT_
ATT,
Change
Program,
predefined
variable

SCRIPT

Modification of the !Process tab of events.

Change
Program

SYNC_
OBJECT

Assigned Sync object

Change
Program

The name of a
queue,
limited to 200
characters.

The name of a Sync,


limited to 200
characters.

310

Chapter3 Objects

TIMEZONE

TimeZone

User-defined
limited to 8
characters.

GET_
ATT,
:PUT_
ATT,
predefined
variable

UC4_
PRIORITY

UC4 Priority

User-defined,
any value between
"0" and "255".

GET_
ATT,
:PUT_
ATT,
predefined
variable

USAGE_
COUNT

Last used

The number of
object usages.

GET_
ATT,
predefined
variable

USER_
CREATED

Created by

The name of the


User object,
limited to 200
characters.

GET_
ATT,
predefined
variable

USER_
MODIFIED

Changed by

The name of the


User object,
limited to 200
characters.

GET_
ATT,
predefined
variable

Attributes for the Event Type "Time Event"

Tab

Attribute

Description

Value

Access
Via:

EVENT_
FIRST_
EXEC

First run

"N" - After the time has


expired
"S" - Immediately

GET_
ATT,
:PUT_
ATT

EVENT_
START_
AFTER_
SCH

Start after scheduled time

"N" - Do not run


"Y" - Run

GET_
ATT,
:PUT_
ATT

EVENT_
TIME

Timer control

MMMM - Minutes in
interval
HHMM - Start time

GET_
ATT,
:PUT_
ATT

Attributes for the Event Type "File System"

Note that hosts can only be changed within a platform (such as WIN01 to WIN02). Script
processing will abort if an attempt is made to change a BS2000 host to a UNIX host.

Automation Engine

Tab

311

Attribute

Description

Value

Access
Via:

EVENT_
COMP_
TYPE

Event - Comparing symbol

">" - Greater than


"<" - Less than
"=" - Equal to
"<>" Not equal to
">=" Equal to or
greater than
"<=" Equal to or
less than

GET_
ATT,
:PUT_
ATT

EVENT_
COMP_UNIT

Event - Unit

"HOST_
SPECIFIC" Complies with the
settings in the
target system,
"BYTE" - Byte,
"KB" - Kilobyte,
"MB"- Megabyte,
"GB" - Gigabyte,
"TB" - Terabyte

GET_
ATT,
:PUT_
ATT

EVENT_
COMP_
VALUE

Event - Comparative value

User-defined,
any value between
"0" and
"99999999".

GET_
ATT,
:PUT_
ATT

EVENT_
FILE_PATH

Path

User-defined,
limited to 255
characters.

GET_
ATT,
:PUT_
ATT,
Change
Program,
via script
variable

EVENT_
FIRST_
EXEC

First run

"N" - After time is


expired,
"S" - Immediately

GET_
ATT,
:PUT_
ATT

EVENT_
START_
AFTER_SCH

Start after scheduled time

"N" - Do not run,


"Y" - Run

GET_
ATT,
:PUT_
ATT

312

Chapter3 Objects

EVENT_
CHECK_
METHOD1

Event - Type of monitoring

"FILE_SIZE" - file
size
"PATH_FILE_
COUNT" - Number
of files
"PATH_SPACE_
ALLOCATED" Allocated hard
drive space
"PATH_SPACE_
USED" - Used
hard drive space,
"PATH_SPACE_
UNUSED" Available hard
drive space

GET_
ATT,
:PUT_
ATT

EVENT_
CHECK_
METHOD2

Event - and

"FILE_
CHANGED" - Last
modification time
of a size
"FILE_STABLE" File-size
modification

GET_
ATT,
:PUT_
ATT

Setting one of
these two
values has the
effect that the
following
attributes are
automatically
filled with the
suitable values:
EVENT_REPEAT
= "F"
EVENT_FIRST_
EXEC = "S"
EVENT_TYPE =
"FT"
EVENT_
CHECK_
WITHIN

Event- within

HHHHMMSS period

GET_
ATT,
:PUT_
ATT

EVENT_
CONSIDER_
ALL

Event- Consider All Files

"Y" - Yes,
"N" - No

GET_
ATT,
:PUT_
ATT

EVENT_
INCLUDE_
SUB_DIR

Event- Include subdirectories

"Y" - Yes,
"N" - No

GET_
ATT,
:PUT_
ATT

Automation Engine

313

EVENT_
TIME

Timer control

MMMM - Minutes
at interval
HHMM - Start time

GET_
ATT,
:PUT_
ATT

HOST

Host

The name of an
agent,
limited to 32
characters.

GET_
ATT,
:PUT_
ATT,
Change
Program

Attribute for the Event Type "Database"

T Attrib
a ute
b

Description

Value

Access
Via:

OPE
RATO
R

Operator

">" - Greater than


"<" - Less than
"=" - Equal to
"<>" Not equal to
">=" Greater than or equal to
"<=" Less than or equal to
"CONTAINS" - Contains

GET_ATT,
:PUT_ATT

OPE
RAN
D1_
MSA
CCE
SS_
FILE

Value 1 - only
Microsoft Access: file
name

The path and file name of the MS Access


database,
limited to 255 characters.

GET_ATT,
:PUT_ATT

OPE
RAN
D1_
SOU
RCE

Value 1 - source

"SQL" - SQLquery
"STATIC"- Statistical value"VARA"Variable object

GET_ATT,
:PUT_ATT

OPE
RAN
D1_
SQL_
AGE
NT

Value 1 - host

The name of a Database Agent,


limited to 32 characters.

GET_ATT,
:PUT_ATT

314

Chapter3 Objects

OPE
RAN
D1_
SQL_
DATA
BAS
E_
NAM
E

Value 1 - database

The database name,


limited to 30 characters.

GET_ATT,
:PUT_ATT

OPE
RAN
D1_
SQL_
LOGI
N

Value 1 - Login

The name of a Login object, limited to 200


characters.

GET_ATT,
:PUT_ATT

OPE
RAN
D1_
SQL_
SERV
ER_
NAM
E

Value 1 - Server

The name of the database computer,


limited to 30 characters.

GET_ATT,
:PUT_ATT

OPE
RAN
D1_
SQL_
QUE
RY

Value 1 - SQL

SQL statement,
limited to 255 characters.

GET_ATT,
:PUT_ATT

OPE
RAN
D1_
STAT
IC_
VALU
E

Value 1 - statistical
value

Statistical value,
limited to 40 characters.

GET_ATT,
:PUT_ATT

OPE
RAN
D1_
VAR
A_
KEY
WOR
D

Value 1 - validity key

The name of a key, limited to 200


characters.

GET_ATT,
:PUT_ATT

Automation Engine

315

OPE
RAN
D1_
VAR
A_
NAM
E

Value 1 - Variable
object

The name of a Variable object, limited to 200


characters.

GET_ATT,
:PUT_ATT

OPE
RAN
D2_
MSA
CCE
SS_
FILE

Value 2 - only
Microsoft Access: file
name

The path and file name of the MS Access


database,
limited to 255 characters.

GET_ATT,
:PUT_ATT

OPE
RAN
D2_
SOU
RCE

Value 2 - source

"SQL" - SQLquery
"STATIC"- Statistical value
"VARA"- Variable object

GET_ATT,
:PUT_ATT

OPE
RAN
D2_
SQL_
AGE
NT

Value 2 - host

The name of a Database Agent, limited to 32


characters

GET_ATT,
:PUT_ATT

OPE
RAN
D2_
SQL_
DATA
BAS
E_
NAM
E

Value 2 - database

Database name, limited to 30 characters.

GET_ATT,
:PUT_ATT

OPE
RAN
D2_
SQL_
LOGI
N

Value 2 - Login

The name of a Login object, limited to 200


characters.

GET_ATT,
:PUT_ATT

OPE
RAN
D2_
SQL_
QUE
RY

Value 2 - SQL

SQL statement,
limited to 255 characters.

GET_ATT,
:PUT_ATT

316

Chapter3 Objects

OPE
RAN
D2_
SQL_
SERV
ER_
NAM
E

Value 2 - Server

The name of the database computer,


limited to 30 characters.

GET_ATT,
:PUT_ATT

OPE
RAN
D2_
STAT
IC_
VALU
E

Value 2 - statistical
value

Statistical value,
limited to 40 characters.

GET_ATT,
:PUT_ATT

OPE
RAN
D2_
VAR
A_
KEY
WOR
D

Value 2 - validity key

The name of a key,


limited to 200 characters.

GET_ATT,
:PUT_ATT

OPE
RAN
D2_
VAR
A_
NAM
E

Value 2 - Variable
object

The name of a Variable object, limited to 200


characters.

GET_ATT,
:PUT_ATT

Attributes for Event Type "Console"

Tab

Attribute

Description

Value

Access
Via:

EVENT_
CATEGORY

Category
(only Windows)

User-defined,
any value
between "0" and
"99".

GET_
ATT,
:PUT_
ATT

When reading the


attribute, the
system returns a
16-figure value
with leading
zeros.

Automation Engine

317

EVENT_
SOURCE

Source
(only Windows)

User-defined,
limited to 32
characters.

GET_
ATT,
:PUT_
ATT,
via script
variable

EVENT_
SUB_TYPE

Type
(only Windows)

Monitoring the
event viewer of
Windows

GET_
ATT,
:PUT_
ATT

"SYSTEM" System log


"SECURITY" Security log
"APPLICATION"
-Application log
"DIRECTORY_
SERVICE" Directory service
log
"DNS_SERVER"
- DNS Server log
"FILE_
REPLICATION_
SERVER" - File
replication service
log
HOST

Host

The name of an
agent,
limited to 32
characters.

GET_
ATT,
:PUT_
ATT,
Change
Program,
predefined
variable

MSG_
SEVERITY

Severity
(only OS/400)

User-defined,
any value
between "0" and
"99".

GET_
ATT,
:PUT_
ATT

MSG_TYPE

Message type
(only OS/400)

User-defined,
any value
between "1" and
"25".

GET_
ATT,
:PUT_
ATT

See also:
Event
Attributes
GET_ATT function
:PUT_ATT statement
UC4.DB Change

318

Chapter3 Objects

3.2.12 FileTransfer
FileTransfer
A FileTransfer enables you to exchange files in various ways betweensystems and system
platforms.
Object class: Executable object
Object type (short name): JOBF
Creating FileTransfers
FileTransfers transfer one or several files.

Procedure

1. Click the button in the toolbar and a window listing all the available object types opens.
Select type FileTransfer (JOBF).
2. Assign an appropriate name and open the FileTransfer object. Then click the FileTransfer
tab.
3. In the upper area, all information required about the computer on which the file to be
transferred is stored can be indicated. The use of wildcards facilitates that several files can
be sent with one FileTransfer object.
4. The lower area can be used to specify all information about the computer to which the file(s)
should be sent.
5. Use the optional settings of the Runtime tab if the execution of the FileTransfer requires
monitoring.
6. UC4 script elements can be stored in the Process tab.
7. The time of script generation can be specified with the option Generate at runtime
(Attributes tab). If this option is activated, the script will not be executed at object activation
but rather when it is started. These can be two different points in time (e.g. when the object is
executed by a Workflow).
8. FileTransfers are executable objects.

Various other settings are possible in the FileTransfer object. Details are found in the
documentation about the individual tabs.
Header tab
The Header tab is a general tab that is available in every UC4 object.

Automation Engine

319

Description

Field/Control

Description

Header
Title

You can define object titles here. This title should include a short and
characteristic description of the corresponding object as it is displayed
in all overviews.

Created

Indicates the user who created this object including the date and time.

Modified

Indicates the user who has last modified this object including the date
and time. The number of times the object has been modified is
displayed to the right.

Last used

Indicates user, date and time regarding the most recent object usage.
The number of times that the object has been used is displayed to the
right.

Active

With this option being deactivated, the object will automatically be set
to inactive after its activation and not processed.
Therefore, the tasks obtain the status ENDED_INACTIVE_OBJECT
(return code: 1925).
This setting is available in the Header tab of all executable objects and
is set by default.

320

Chapter3 Objects

Archive keys

Two keywords of your choice can be specified in all executable objects


and in Sync objects. These keys are written to the statistical data each
time the object is processed.
Statistical data can be selected using these archive keys. Archive keys
are displayed in the Statistical Overview and can be printed.

Extended Reports

Extended reports can be written for all executable objects. They log the
complete script with all Includes, the generated JCL of Jobs or
accesses to UC4 objects.

Default (UC_
CLIENT_SETTINGS)

If you select this option, the reports that the UC4 administrator has
defined in the UC4 Variable UC_CLIENT_SETTINGS using the EXT_
REPORTS key are generated.

All

All extended reports are written for this object.


This option overwrites possible pre-settings of the client.

None

No extended reports are written for this object.


This option overwrites possible pre-settings of the client.

Sync Tab
The Sync tab is object-type specific and is available in all executable UC4 objects.
Sync objects synchronize task on the basis of defined conditions. Enter one or several Sync
objects including the actions that should be taken in this tab if you want to make use of this
possibility.

The Sync objects are checked one after the other when the task starts. The UC4 Automation
Engine tries to use the Sync object of the first line by calling the start action. If this is not possible
because this is not allowed by the Sync object's current condition, the task waits, aborts or is
skipped. The type of reaction depends on the Else condition defined in the tab's last column. If
"wait" has been specified, the task waits until it can use the Sync object with the start action. Then

Automation Engine

321

the UC4 Automation Engine checks the Sync object in the next line etc. The task starts as soon all
Sync objects could successfully be used. Depending on the task's end status, either an abend or
end action is processed.
Up to 500 Sync objects can be specified.
All Sync objects must not include a total of more than 5000 rules. Rules are defined actions that
are directly entered in the Sync object.
Task ends are administered by work processes but only the primary work process releases busy
Syncs. Due to this task allocation, it can take several seconds until a Sync is released after a
task has ended. In this case, the report entry includes a time stamp that shows a later time than
the task has ended. Such delays occur when the primary's work load is high or if it is processing
lots of Syncs.
Note that using many Sync objects and rules can reduce task clarity. UC4 recommends
reducing the number of Sync object to a minimum.

Description

Only actions that have been defined in the Sync object can be selected.
Field/Control

Description

Sync object

Selects the Sync object that should be used to synchronize the task.

Start action

Defines the action that should be taken when the task starts. If this is
not possible because of the Sync's status, the Else condition becomes
effective.

Abend action

This action is processed if the task aborts.

End action

This action is processed if the task ends successfully.

Else

You can define here what should happen to the task if the start action
cannot be executed:
l

l
l

The task should wait until the start action can be executed
(WAIT).
The task aborts (ABEND).
The task is skipped (SKIP).

See also:
Sync
Attributes Tab
The Attributes tab is object type-specific and is only available in "FileTransfer" objects. All
settings that are necessary to execute a FileTransfer are defined in this tab.
Object: FileTransfer
Object class: Executable object
Object type (short name): JOBF

322

Chapter3 Objects

Contents

Field/Control

Description

Attributes
Group

If the FileTransfer should be started by a Group, you can select this


Group here. If there is no entry, the FileTransfer is activated
immediately.
Note that the entry that is specified here is not considered if the
FileTransfer starts through a Workflow, a Schedule or as a recurring
task.

Queue

Selection of a Queue object in which the FileTransfer should be


processed. The FileTransfer automatically starts in the Client Queue
(object name: CLIENT_QUEUE) if nothing has been specified in this
field.

Int. Account

Specification of an internal account.


Contents do not affect the UC4 system's internal processing. You can
access the attribute "Int. Account" with script elements and integrate it
in your processes.

Consumption ...
(Resources)

Resources that are consumed during the execution.


Allowed values: "0" to "99999"
Default value: 0
The resource value that the UC4 administrator has defined with the
key "WORKLOAD_DEFAULT_FT" in the UC4 Variable UC_
SYSTEM_SETTINGS is used if value "0" is selected.

Automation Engine

323

UC4 Priority ... (0-255) Priority that should be used to execute this FileTransfer in UC4.
Allowed values: 0 to 255
Default value: 0
The priority that the UC4 administrator has specified in the UC4
Variable UC_CLIENT_SETTINGS with the key "TASK_PRIORITY" is
used if you select value "0".
TimeZone

TimeZone that should be used.

Attribute Dialog

If this check box is selected, a dialog will be displayed at activation in


which you can modify the attributes for the current execution of the
FileTransfer.

Generate at runtime

Select this check box if the object should not be generated at activation
time but at runtime.

Tasks running
parallel
Max ...

Setting that defines the maximum number of parallel executions for this
FileTransfer.
Allowed values: 0 to 99999
Default value: 0 (no limit on tasks running parallel)
Examples:
Max. "1" - At any time, not more than one FileTransfer execution must
be available.
Max. "2" - At any time, not more then two active FileTransfer
executions must be available.
etc.

Else: Wait Abort

Instruction that defines how this FileTransfer should be handled if the


execution exceeds the specified maximum number of tasks that can
run at the same time.
Wait = The FileTransfer waits until execution is possible.
Abend = The FileTransfer is interrupted.

Deactivate autom.
when finished

The Workflow's settings for automatic deactivation apply for


FileTransfers that are processed as part of this Workflow. These
settings overrule the settings of subordinate tasks.
If the Activity Window includes many tasks that are not
automatically or manually deactivated when they are finished, this
can negatively affect performance and the Activity refresh cycle.

No

The FileTransfer is not automatically deactivated and remains visible in


the Activity Window after it has been executed.

If the first program run


has error-free ended

The FileTransfer is automatically deactivated after its successful


execution. Interrupted FileTransfers remain visible in the Activity
Window and must be deactivated manually.
You can additionally specify a particular status for the error-free
execution and a time delay for de-activation. Do so by using the fields
Error-free status and/or Time delay ... Minutes.

324

Chapter3 Objects

After an error-free
restart

The FileTransfer is automatically deactivated after a successful restart.


Previously interrupted FileTransfers are also deactivated.
You can additionally specify a particular status for the error-free
execution and a time delay for de-activation. Do so by using the fields
Error-free status and/or Time delay ... Minutes.

Error-free status

Status that confirms a successful FileTransfer execution. If no status


is selected, the system-return codes 1900 - 1999 (ANY_OK) represent
error-free execution.

Always

The FileTransfer is always automatically deactivated after it has been


executed.
Additionally, you can specify a time delay for a deactivation in the
"Time delay" field.

Time delay ... Minutes

The FileTransfer is automatically deactivated after a specified number


of minutes. You can manually deactivate it before this time is over. The
time difference only affects FileTransfers whose execution also
resulted in an automatic deactivation.

Some of the settings that are specified in this tab can be read and modified at runtime. Attributes of
this object are accessed by using script elements. If the checkbox "Attribute Dialog" is active, the
user can influence the attributes. The script accessed the attributes subsequently.
FileTransfer Tab
The FileTransfer tab is object-type specific and in this form is only available in FileTransfer
objects. It is used to define parameters for file transfers and settings for the handling of files.
Object: FileTransfer
Object class: Executable object
Object type (short name): JOBF

Automation Engine

325

Description

Field/Control

Description

From

The source of the file transfer.

Host

Here you select the name of the agent where the file that should be
transferred is available. You can also specify an AgentGroup.
AgentGroups can either be used as the source OR as the target.
You cannot use both.

Code

Name of the CodeTable that is valid for the host.


In addition to the CodeTable objects, this combo box provides options
that can be used to transfer Unicode files. You can select the relevant
Unicode format:
l
l
l

<UTF 8>
<UCS 2BE>
<UCS 2LE>

Setting one of the above values has the effect that the code is not
converted and the selection field Code for the FileTransfer target is
grayed out.
Login

The name of a Login object.

Compression

The files are transferred in compressed form.

File

Specify the name of the source file, thereby using the directory, folder
or ID.
Partially-qualified FileTransfers: Use a filter that is composed of
wildcard characters and fixed parts of the file name instead of
specifying a complete file.
VMS
Note that the VMS agent does not resolve logical names. Directly
specify the directory and file name as otherwise, the file cannot be
found.

z/OS
The specification of z/OS files depends on the file system that you use
(USS or Host). For example:
USS file system (absolute path): /dir1/dir2/datei
USS file system (relative path): ./dir1/dir2/datei
Host file system: FLQN.DATASET.NAME
File Attributes

Additional entries for file attributes.


Note that there are platform-specific features.

326

Chapter3 Objects

Keep original file


attributes

Check this box to assume the source file(s) file attributes to the target
file(s).
Requirements:
l
l

The source and target platform must comply with each other.
The new FileTransfer protocol must be used (source and target
agent are of UC4 version 9.00A or later).

Otherwise, this option is ignored.


In BS2000, OS/400 and z/OS, you cannot overwrite the original
attributes with additional specifications in the FileTransfer object
(target). Any attempt to do so results in an error message and the
FileTransfer fails.
UC4 recommends activating this setting because the target file can
become corrupt if the attributes are not sent or modified when you
transfer text files between two OS/400 computers..
Use wildcards

FileTransfer with wildcard characters.


With this check box being activated, FileTransfers can be executed
with wildcards.

Include sub directories

A FileTransfer with wildcard characters


Check this box in order to include files in subdirectories of a
FileTransfer with wildcard characters. This is only available if both
platforms support this function and the option Use wildcards is
selected.
UC4 administrators can use the parameter WorkDirMatch= in the
INI files of UNIX agents in order to specify whether sub-directories
should be included in the search for files.

Transfer complete
subfolder structure

This is for partially qualified FileTransfers.


By default, empty folders are not considered when subdirectories are
transferred. Activate this option to include empty directories in
transfers.
Note that you can only use this setting when the option Include subdirectories is active.

Max. parallel running


transfers

FileTransfer with wildcard characters.


Set the number of files that should be transferred at the same time as a
FileTransfer that includes wildcard characters. The higher the number,
the higher the load on the participating computers. Only available if
"Use wildcards" is selected.
This setting is only relevant for the old FileTransfer protocol. It is
applied if at least one of the agents uses UC4 version 8.00A or
below. This setting is not evaluated if both agents are of version
9.00A or later.

Automation Engine

Abort at first error

327

For partially qualified FileTransfers.


Activate this check box if the FileTransfer should end after the first error
that occurs. Files that have not been transferred are ignored. With this
setting NOT being activated, the FileTransfer continues with the next
file.
FileTransfers cancelled due to this option receive the status ENDED_
NOT_OK.
This option is only relevant if the new FileTransfer protocol is used
(source and target agent are of version 9.00A or later). The old
protocol continues the FileTransfer even if the transfer of a
particular file fails.

Erase source file

Activate this check box in order to have the file deleted after the
transfer.
Note that particular rights are required under UNIX if this file should
be deleted.
A FileTransfer also ends with the status ENDED_OK if all files
have successfully been transferred but the source file could not be
deleted for some reason.

Format
Text

Activate this option button if the file is a text file.

Binary

Activate this option button if the file is a binary file.


Selecting a binary format can save you time when you transfer text
files. In this case, the text file is not changed (formatting such as
line breaks).

To

The target of the FileTransfer.

Host

Select the name of the host that should receive the file from the list box.
You can also define an AgentGroup.
AgentGroups can either be used as the source or as the target. You
cannot use a combination of both.

Code

The target of the FileTransfer.


Activate the code table from the list box that is valid for the target host.

Login

The source of the FileTransfer, name of a Login object.

File

Enter the location (directory, folder or ID) and the name of the target file.
You can also rename the file.
The following variable can be inserted in the target file name: &<FT_
SRC_HOST>. The FileTransfer replaces this variable with the
name of the file's original host.
For example: C:\temp\&<FT_SRC_HOST>_test*.txt
Partially-qualified FileTransfers: Use a filter that is composed of
wildcard characters and fixed parts of the file name instead of
specifying a complete file.

328

Chapter3 Objects

File Attributes

Additional entries for file attributes.


Note that there are platform- specific features.

File exists
Cancel

This is an option that cancels the FileTransfer if the file already exists in
the target system.

Overwrite

This is an option that overwrite the existing file in the target system.

Append

The transferred file is appended to an existing file in the target system.


Note that there are platform-specific features.

Comments

You can read and modify all settings that are specified in this tab at runtime. for this purpose, you
use script elements that access the object's attributes. A user can activate the checkbox "Attribute
dialog" in the Attributes tab in order to manipulate the attributes. In the script, the attributes are
accessed at a later point in time.

Platform-Specific Features

You can also specify file attributes for the file names of FileTransfer targets.
l
l
l
l
l
l
l
l

Agent for BS2000 - FileTransfer Support


Agent for GCOS 8 - FileTransfer Support
Agent for z/OS - FileTransfer Support
Agent - Interaction between UC4 and NSK - Execution of FileTransfers
Agent for OS/400 - FileTransfer Support
Agent for UNIX - FileTransfer Support
Agent for VMS - FileTransfer Support
Agent for Windows - FileTransfer Support

Runtime tab
The Runtime tab is an object class-specific tab which is available in every executable object in
UC4. It can be used to specify parameters for a task's runtime behavior.

Automation Engine

The Runtime tab is structured as follows:


l
l
l
l
l
l

Return code handling


Forecast setting
Evaluating the estimated runtime (Runtime Evaluation)
Monitoring the maximum runtime (Runtime Monitoring)
Monitoring the minimum runtime (Runtime Monitoring)
Reaction to runtimes that have been exceeded or not reached (Runtime Monitoring)

Description

Field/Control

Description

Definition for
ENDED_OK
Return code <=

Maximum return code for a task's normal end.


A task ends normally (Status "ENDED_OK") if its return code lies
below or is equal to the specified maximum return code.
To set the return code, you can also use the script element
:MODIFY_STATE.

Else execute

You can execute an object if the task does not end with a return code
that lies within the ENDED_OK area.
Note that this object will not be processed if the task is terminated
by using the script statement :EXIT.

End status for


forecast

Selection list for the end status that this task should return when you
make a Forecast calculation.

329

330

Chapter3 Objects

Estimated runtime
(ERT)
Current ERT =

Displays the task's next estimated runtime (ERT).


You can enter the estimated runtime here. This value applies until the
ERT calculation is made after the task's next execution.
Format: "hours:minutes:seconds".

Use default (UC_


CLIENT_SETTINGS)

Selecting this option has the effect that the calculation method that the
UC4 administrator specified in the UC4 Variable UC_CLIENT_
SETTINGS using the key "ERT_METHOD" is used to calculate the
estimated runtime.

Fixed value

A fixed value is entered as the estimated runtime.


Format: "seconds"

Dyn. method

Selection list for the dynamic method that is used to calculate the
estimated runtime from the real runtime.
Possible selection: Average, linear regression, maximal value

from the last ... runs

Number of past runs that are considered for the ERT calculation.
Allowed values: 0 to 25.

+ ... %

Value in percent for an upward ERT correction.

Differences > ... % are You can ignore possible huge differences to of actual runtimes.
ignored
Upper limit (in percent) for actual runtimes that should be included in
estimated runtime calculation.
but do use ... runs at
least

Number of past runs that should be considered regardless of


differences. Allowed value: 0 to 25.

Show Chart

Button that can be clicked in order to update the estimated runtime


according to the current settings. A diagram displays in a separate
window; it shows the last 25 ERT/RRT runs. Windows that are already
open are updated.

Reset Values

Button that can be used to delete the real and estimated runtimes.
A security query displays, confirm it and all saved runtimes are cleared.

Maximum runtime
(MRT)
None

The maximum runtime is not monitored.

Fixed value

The maximum runtime is monitored.


The allowed time is entered as a fixed value in the format
"hours:minutes:seconds". An action as an ELSE condition must be
specified which reacts when maximum runtime is exceeded..

ERT

The maximum runtime is supervised


The valid estimated runtime (ERT) at the time of the task's activation is
used as the maximum runtime. An action as an ELSE condition must
be specified which reacts when maximum runtime is exceeded.

+ ... %

A correction in percent can be specified for ERT for the maximum


runtime. The determined value is added to the estimated runtime.

Automation Engine

Curr. date + day(s)


Time

The maximum runtime is monitored.

TimeZone

Selection of a TimeZone object.

331

A number of days and time of day are set for when the task must be
finished. The starting point for the calculation of the date is the real date
of the task. An action as an ELSE condition must be specified which
reacts when maximum runtime is exceeded.

Minimum runtime
(SRT)
None

The minimum runtime is not monitored.

Fixed value

The minimum runtime is monitored.


The allowed time is entered as a fixed value in the format
"hours:minutes:seconds". You must specify an action (ELSE
condition) that applies if the maximum runtime has been exceeded.

ERT

The minimum runtime is monitored.


The valid estimated runtime at the time of the task's activation is used
as its maximum runtime. You must specify an action (ELSE condition)
that applies if the maximum runtime has been exceeded.

- ... %

When you select the ERT, you can also specify a correction value in
percent for the maximum runtime. The value you determine is added to
the estimated runtime.

Else
Cancel / Quit

If you activate this check box is activated, the task is canceled or quit if
the runtime has been exceeded. Only available if the maximum runtime
is monitored.

Execute

If you activate this check box, you determine that the task is executed.
You can directly select the executable object. If the runtime is
exceeded or not reached, the specified task is executed. Only available
if the runtime is monitored.

Comments

A different type of runtime monitoring can be used for tasks that have been activated in a Workflow
or using the object "Schedule." You can define it in the properties of the relevant object (Runtime
tab). The setting that are defined within the context of a Workflow or Schedule overrule the settings
that have been defined in the task itself.
You can also assume these setting for runtime monitoring in the Workflow or Schedule. This is the
default setting.

See also:
Runtime Evaluation
Runtime Supervision

332

Chapter3 Objects

Variables & Prompts Tab


The Variables & Prompts tab is object type-specific and is available in almost every
executable object in UC4.
Object: FileTransfer
Object class: Executable object
Object type (short name): JOBF
This tab has two tasks:
l
l

It stores object variables.


It assigns PromptSet objects.

Object variables

Object variables include values that belong directly to the object and can be read in the Process
tabs. Variable names and values are determined in the table shown below.
In the Value column, you can also enter predefined variables. Do so using the Variables...
button in the object's toolbar.
The same rules apply for object variable names and for script variables. If you omit the preceding
"&", it is automatically added during the storing process and is available the next time the object
opens.
Object variables and PromptSet variables can be inherited from the superordinate object. For
example, a Schedule's tasks can use the object variables of the Schedule object.
Field/Element

Description

Inherit from parent


All variables (default)

The object obtains all object variables and PromptSet variables of


the superordinate task.

Automation Engine

Only defined variables

333

The object only obtains the object variables of the superordinate


task that have been defined in its "Variables & Prompts" tab.
PromptSet variables are only inherited if the PromptSet object
complies with these values and the value that should be
overwritten has not been changed in the "Variables & Prompts"
tab.

No variables

The object obtains all object variables and PromptSet variables of


the superordinate task.

Note that inherited variables overwrite existing object variables if they have the same name. In
contrast, PromptSet variables are never overwritten.
The following procedure can be used if you want to overwrite PromptSet variables with the value
of a parent variable:
Open the task's Workflow or Schedule properties and switch to the Variables & Prompts tab.
Select the PromptSet area and use the Workflow's or Schedule's variable name as the value of
the relevant PromptSet element. If the particular PromptSet element is not a text field, click its
labeling.
PromptSet objects

In the Variables & Prompts tab, you can also select one or several PromptSet objects that should
be called during the activation process. In doing so, you can overwrite the default values of
PromptSet elements. These modifications do not affect the PromptSet object itself.
You can use the "+" and "-" buttons to add or remove PromptSet objects. Several PromptSet
objects are called from top to bottom. Use the arrow buttons if you want to change this order.
To adjust the task's PromptSet values, you directly modify the PromptSet elements.
Click on the blue description that displays next to the elements when you also want to use variables
in the default value. The effect is that the PromptSet elements now appear as a gray text field that

334

Chapter3 Objects

has the name of the related PromptSet variable. In this specific text field, you can either manually
enter the predefined variables, or select them in a dialog that you call using the
button.
Clicking the blue description again deletes your previous entries and the PromptSet element
appears in its original view.
Predefined variables are already deleted when the PromptSet input mask is called. Note that the
values of predefined variables can change during the object's execution (for example, with UC4
Script) but the PromptSet variable still stores the old value.
An error occurs if the object should be stored and an element's value does not fulfill the
limitations of the PromptSet properties (min. value, max. value, max. length, value required etc).
The affected fields are highlighted in yellow.
If the values differ from the reference values, an error only occurs when the object starts and an
attempt is made to send the prompt. Ensure that the data type and other limitations (min. value,
max. value, format) of the reference variable are preserved.
Using the same variable names has the effect that the object variable values are overwritten by
the PromptSet variables. The value of the PromptSet object that has last been called is used if
selected PromptSet objects include identical variable names.
Graphical elements that are removed from the PromptSet object are also removed from the
Variables & Prompts tab. Modifications that are made in the PromptSet object's default values
do not affect the Variables & Prompts tab. The values of the PromptSet object are only
available when the PromptSet object is newly selected.

See also:
Object Variable
Designer tab
Rollback Tab
The Rollback tab is an object-specific tab that is available in every executable object that can be
included in a workflow.
The Rollback tab can be used to define actions that store the task (= Backup) and restore it (=
Rollback). These settings are only useful when the object runs in a workflow because you can only
start a rollback process within a workflow.
The backup and rollback functions are especially designed to undo erroneous installation and
deployment processes that are defined in the UC4 Deployment Manager but are processed by
using the Automation Engine.
Backup actions will always be processed before the object is processed, and rollback actions can
only be started via workflows. For more information, see the related documentation.

Automation Engine

Field/Element

Description

Enable Rollback

Use this to activate or deactivate the rollback settings.

335

When this option is deactivated, all the fields of this tab are
disabled.
Custom Rollback
Backup

Specify an executable object that is responsible for the


backup process.
If you specify a Backup object, it will always automatically
run before the task runs, regardless of how the object is
activated.
The actions and steps that must be defined in the Backup
object depend on the processes and actions of the related
task. Note that you must define them manually. For
example, if you use an object to update your database, it is
useful to include a database using the Backup object.

336

Chapter3 Objects

Rollback

Specify an executable object that is responsible for the


rollback process.
The definition of the Rollback object depends on the
current object or the Backup object and must be made
manually. The Rollback object's basic task is to undo
modifications in the case of an error in order to ensure that
a previous working status will be restored. For example, if
the Backup object creates a database backup, the
Rollback object should be able to restore this backup.
The Rollback object will be processed when the task
starts in Rollback mode which is only possible in a
Workflow.

File Rollback

A file-based rollback is only available for Job and


FileTransfer objects that run on Windows or UNIX. In other
objects, the corresponding fields are disabled.
For a file-based rollback of Jobs, the system uses the
job's Agent, and for a file-base rollback of
FileTransfers, it uses the destination Agent.

Automation Engine

Backup

337

Specify the path or file(s) that should be stored.


If you do not specify file names, the directory's complete
content will be backed up. To include subfolders, you must
select the option Include sub-directories .
You can use the wildcard characters * and ? in the file
name. * is a placeholder for any number of characters (0 n) and ? represents exactly one character. This allows you
to select files with a certain name and ending.
Examples for Windows:
C:\temp\test.txt
C:\temp\*.txt
C:\temp\ oder C:\temp\*
C:\temp\test??.*
The specified directory or files are automatically copied to
the following directory each time before the object runs:
<Backup folder>/<Client>/<Date>/<RunID>/
You define the backup folder in the INI files of the
agents (in the [VARIABLES] section) with the Agent
Variable UC_EX_PATH_BACKUP. By default, the
system uses "..\BACKUP" (Windows) or "../backup"
(Unix) as its backup folder (on the operating system of
the files and folders that should be backed up.
For example:
To be backed up:C:\uc4\source\*.txt
Backup folder:C:\uc4\backup
UNIX: The files are not directly stored in the directory
above but in a TAR archive that uses the RunID as its
name.
Before you run the object, make sure that there is
enough local disk space for the file backup and that the
OS user has all the required rights.
The backup folder's contents are deleted in regular
intervals. You can define how long the files should be
stored and when they should be checked with the
settings BACKUP_RETENTION_CHECK and
BACKUP_RETENTION_LIFETIME. These are
available in the UC4 Variable UC_HOSTCHAR*.
If the task starts in Rollback mode, the files are copied
from the backup folder to the directory that should be
backed up.

338

Chapter3 Objects

Delete before restore

This field affects rollbacks.


If this option is active, the content of the original directory
that was used to create a backup will be deleted before the
backup folder is restored (see the description above of the
Backup field). This ensures that the destination directory
is empty before the files are copied from the backup folder
and avoids potential errors.
Subfolders will only be deleted if the option Include subdirectories is active.

Include subdirectories

Subdirectories and their contents will be included in


backup, deletion and restore processes.

Process Tab
The Process tab is a type-specific tab in which processing instructions are stored in UC4's
scripting language.
Object: FileTransfer
Object class: Executable object
Object type (short name): JOBF

Description

The script is either processed at FileTransfer activation or start. This point in time depends on the
setting "Generate at runtime" which can be defined in the Attributes tab.
A FileTransfer's script cannot contain JCL lines.

Automation Engine

339

See also:
Script Editor
About UC4 Scripts
SampleCollection
Output ScanTab
The Output Scan tab determines the filters that are used to search the report of a task and/or
external file plus the reaction to the provided result.
Output Scan tab actions will be processed before the PostProcess tab actions.
Note that the actions will always be processed regardless of the task's end status.
Login info is required for the Output Scan even if the Windows or UNIX agent's password check
is deactivated (UC_HOSTCHAR - ANONYMOUS_FT/JOB). Either the Login object that is set
in this tab in the section "Override host for FileScan" (if available) or the one that is specified in
the Attributes tab is used.

For example:
The above task refers to two Filter objects. FILTER.OUTPUT searches for the word ERROR in an
external file and FILTER.REPORT searches for a term that should be found in any case in the
report. The report is searched first because the list is processed from bottom to top.
The following table shows the possible results:
The report does not The external file
include the expected includes the word
term
"ERROR"

Return code

Alarm object

340

Chapter3 Objects

The report does not The external file


include the expected includes the word
term
"ERROR"

Return code

Alarm object

ALARM.CALL

ALARM.CALL

Description

The Action area includes a table with filter definitions.


In this table, you can select one or several Filter objects whose conditions should be checked. You
also define here whether a certain conditions must apply or not and the return code that the affected
task should obtain. Optionally, you can also specify an object that should be processed.
Note that the entries will always be processed from bottom to top.
The first entry that applies is decisive for the task's return code. Successive conditions that apply
do not affect the return code. The optional object is executed in each line in which the condition
applies.
Note that filter definitions are checked at runtime. For example, a task obtains the status
FAULT_POST_PROCESSING if the Filter object you indicate searches a report that does not
exist in the task.
Field/Element

Description

Action
Output filter

The Filter object that includes the criteria that should be applied for
searching reports and/or external files.

True/False

You can select whether the criteria that are specified in the Filter object
must apply.
"true" - yes
"false" - no

Set return code

The return code for the task.

Status Text

Any text that is used for the task's remote status when the filter
definition applies.
The remote status of task appears in the corresponding column in
the Activity Window.

Execute

The object that should be processed in reaction to the result that is


supplied by the Filter object (optional).

Pass down to dynamic


children

This option is available in SAP jobs and RemoteTaskManager objects.


It determines whether Filter objects should also apply to child tasks.
"Yes" - The search takes place in the task and its children.
"No" - The search takes place only in the task.
"Only children" - The search takes place only in the child task.

Automation Engine

341

Field/Element

Description

Override host for


Filescan (optional)

By default, this task's agent and Login object are used to access an
external file that has been defined in the Filter object. You can change
one or both entries.
In FileTransfers, the destination agent is used by default.

Host

The name of an OS or a Java agent.

Login

The name of a Login object.

Post-Process Tab
The Post Process tab is an object type-specific tab that is only available in the objects
"FileTransfer", "Job" and "RemoteTaskManager". Processing commands can be stored here in
UC4's script language.

Description

The script commands stored in this tab are processed when the FileTransfer ended or was
canceled.
An ended FileTransfer can still be controlled with post-process commands. For example, the
FileTransfer's return code and status text (the text supplied by the Job messenger in the Trailer) can
subsequently be modified. The script statement :MODIFY_STATE (which was developed for
exclusive use in the Post Process tab) defines the final ending of the FileTransfer.
Reports, for example, can be analyzed with PREP_PROCESS_REPORT. If an error is found, the
status ENDED_NOT_OK could be defined for a FileTransfer although it has already ended normally
from the "technical" point of view and vice versa. Return code "0" is assigned to canceled

342

Chapter3 Objects

FileTransfers because the fact that the FileTransfer has been canceled is irrelevant for further
processing.
With the script statement :RSET, script variables can be transferred between Process and Post
Process tabs. This script statement returns the value that has been assigned to the script variable
in the Process tab.
A FileTransfer's post script cannot contain JCL lines.
Additionally, the following script elements must not be used:
l
l
l

:PUT_ATT - Setting attributes for RemoteTaskManager generation is irrelevant.


:EXIT - Canceling script processing withreturn code > "0" is not allowed.
:STOP - Interrupting script processing is not allowed.

See also:
Script Editor
About UC4 Scripts
SampleCollection
Documentation Tabs
Documentation tabs are user-defined and client-specific tabs that can be assigned to all UC4
objects.

All Documentation tabs that have been defined by the UC4 administrator in the UC4 variable
UC_OBJECT_DOCU are shown. Note that imported objects have their own documentation
tabs.
The Version Management tab displays the stored object versions if this function has been
activated.

Automation Engine

343

Structured Documentation

Each of these tabs can also be displayed in structured form. Structured Documentation can be used
to split complex object information in well-arranged parts. Each documentation element can be used
to store texts, but also to define attributes.
You can also define links (e.g. to files, folders or to documents in the Intranet and Internet etc.) in
structured documentation. Files are then displayed with the associated program, folders are
opened, URLs call the standard browser etc. The particular actions depend on the installed
programs and the user's PC configuration.

New Documentation tabs initially only include the "Content" folder. This is your starting point for
creating a further structure. To create and edit this structure, you can use the following popup-menu
commands :
Command

Description

Add attribute

Creates a new attribute in the highlighted element.

Add node after

Inserts a new element after the highlighted element.

Add node before

Inserts a new element before the highlighted element.

Add node child

Creates a new element one level below the highlighted element.

Duplicate node

Duplicates the highlighted element and its attributes and contents.

Delete node

Deletes the highlighted element irrevocably.

You can create one or more attributes for each individual element. Basically, there are two different
types: text and enumeration. You can add one or more of these attributes to an element. Determine
the attribute's name and then select whether it is a text or an enumeration. In enumerations, you can
specify the entries that should be included.

344

Chapter3 Objects

Names of elements and attributes should comply with the XML naming convention. Letters,
numbers and the characters "-", ".", "_" can be used. Keep the following rules in mind:
l
l
l
l

The first letter of a name must neither be a number, nor ".", nor "-".
The name must not include blanks.
Do not use colons as they are reserved characters.
Names must not begin with "XML", regardless if uppercase or lowercase letters are used.

Structured documentation can be read with specific script elements (XML_*).

Partially Qualified FileTransfer


As opposed to fully qualified FileTransfers, partially qualified FileTransfers can also transfer
several files by using wildcard characters. This document describes how you can define source
and target file filters depending on the particular versions of the source and target agents.
A FileTransfer is partially qualified if one or several wildcard characters are used in order to specify
the source and target file. The option Use wildcards must also be activated.
The FileTransfer protocol is decisive for the way that wildcard characters are used:

Old FileTransfer Protocol

The old FileTransfer protocol is used if the source and/or target agent are of a UC4 version below
9.00A.
Source
To define the source file, you can use the wildcard characters * and/or ?. At least one wildcard
character must be used.
"*" stands for any number of characters (including no character), "?" for exactly one. Fixed file name

Automation Engine

345

parts and wildcard characters form a filter which is used to retrieve the files that should be
transferred.
Wildcard characters are always read from left to right. If the fixed part occurs several times in
between wildcards in the source file, the filter applies as of the position at which the fixed part first
occurs.
For example:
Source: *a*a*.txt
Name of a source file that complies with the filter: abrahamastreet.txt
In z/OS, the wildcard characters "*" and "?" must only be used once and not as the first
character.
Target:
In the target file, the wildcard character "*" must be used exactly once. It represents the source file's
complete variable part starting with its first wildcard character (? or *) and ending with its last
wildcard character (? or *).
For example:
Source: ?C_SERVER_*_01.TXT
File that complies with the filter: UC_SERVER_LOGG_01.TXT
Target: TEST_*_A.TXT
Name of the target file: TEST_UC_SERVER_LOGG_A.TXT
Source: *_SERVER_*_0?.TXT
File that complies with the filter: UC_SERVER_LOGG_01.TXT
Target: TEST_*_A.TXT
Name of the target file: TEST_UC_SERVER_LOGG_01_A.TXT

New FileTransfer Protocol

The source and target agent must be of UC4 version 9.00A or later.
Source
See old FileTransfer protocol.
Target:
To define the target file, you can use the * character as often as you like. It represents the source
file's complete variable part starting with its first wildcard character (? or *) and ending with its last
wildcard character (? or *).
Nine placeholders are additionally available that can be used to specify the target file. They refer to
a particular wildcard character (?,*) in the source file name. These placeholders are composed of the
& character and the numbers 1-9: &1, &2, &3,... &9.
The number specifies the wildcard location in the source that is addressed:
For example: Placeholder &3 is replaced by the source file name's characters that are retrieved by
the third wildcard character in the source file specification.
Starting the FileTransfer results in an error if the source file's filter includes fewer wildcards than are
addressed in the target specification. Each placeholder can be used in the target file as often as
required.
The wildcard character "?" must not be used in target file names.

346

Chapter3 Objects

UC4 recommends using at least as many wildcards in the source and the target as are required
in order to clearly identify the file name. Otherwise, the FileTransfer tries to create several target
files of the same name in the same location. In this case, the action that is defined in the
FileTransfer setting "File exists" is executed (cancel, overwrite, append).

Example 1
The following complex example describes wildcard combinations that can be used in FileTransfers.
Source specification:a?b*c?*?d*

Source files that comply with the filter, and their variable parts:
File name

&1

&2

&3

&4

&5

&6

a1b234c05670d.txt

234

567

.txt

1b234c05670d.txt

a2b345c17891d.txt

345

789

.txt

2b345c17891d.txt

a3b456c20903d.txt

456

090

.txt

3b456c20903d.txt

Target specification:

The following target file names are created:


File name
1

234a1b234c05670d.txtb1c2341b234c05670d.txt0d.txt

345a2b345c17891d.txtb2c3452b345c17891d.txt1d.txt

456a3b456c20903d.txtb3c4563b456c20903d.txt2d.txt

Example 2

Automation Engine

347

The following example reverts the date of the source file name in the target file name.
Source specification:
*????_*.*
Source files that comply with the filter:
File name

&1

&2

&3

&4

&5

&6

&7

20110307_report.txt

2011

report

txt

20110220_overview.doc

2011

overview

doc

20110111_script.txt

2011

script

txt

Target specification:
&6_&4&5&2&3&1.&7
The following target file names are created:
File name
1

report_07032011.txt

overview_20022011.doc

script_11012011.txt

See also:
FileTransfer - Procedure
FileTransfer tab

FileTransfer - Execution

Object-Type specific Features

Exchanging data between different system platforms requires the character sets to be
converted. This is automatically done using CodeTable objects. The transfer can be structured,
thereby enabling the exchange of files with packed and binary fields in heterogeneous system
environments. All network transfers are encoded by default.
For each FileTransfer, a separate connection is established between the agents. agents for the
operating systems OS/400, Windows, Unix, z/OS,and NSK handle FileTransfers through extra
threads. As soon as a FileTransfer has ended, the corresponding connection is automatically
closed. If there are still open and unused connections, they are closed after the period of time that is
defined in the key FT_CONNECTION_TIMEOUT (UC4 Variable: UC_HOSTCHAR_DEFAULT).
The old FileTransfer protocol is used if one or both of the affected agents use UC4 version 8.00A or
earlier. In this case, only one connection is established between the agents for all FileTransfers.
The system checks if a connection has already been established between the two agents before a
FileTransfer starts. If so, this connection is used and no attempt is made to establish a separate
connection. After the FileTransfer has ended, the system ensures that a connection that is still used
is not closed.

348

Chapter3 Objects

No error message is supplied if empty files are transferred (Windows and UNIX).
Note that problems can occur in FileTransfers when the Windows agent starts from a UNC path
because you mapped files (StatusStore) cannot be used (the agent can crash, for example).
UC4 recommends starting the agent either from a local directory or specifying an absolute local
directory in the agent variable UC_EX_PATH_TEMP in the agent's INI file.
FileTransfer optimization: You can specify parameters for the size of the TCP/IP buffer in some
agents. The UC4 administrator can do so in the relevant INI file's [TCP/IP] section.

Transferring Files

Each file transfer is started by establishing a connection between the source and destination
Execution. The file can be transferred as soon as a connection can be established. There are two
methods of transferring files:
1. With a temporary file:
The file that should be transferred obtains a specific name in the destination system. This
name is composed of the letter "T" and a 7-digit alphabetic string (such as TAAFLEFM). The
string is based on the FileTransfer's RunID which ensures that the file name is unique. Also
refer to the documentation about script functions RUNNR2ALPHA and ALPHA2RUNNR.
In the new FT protocol, a separator and a file ID are appended in addition to the string. Doing
so makes a distinction possible because all files are handled via the FileTransfer task's
RunID.
The file obtains the name specified in the FileTransfer object after a successful transfer.
The temporary file is created in the FileTransfer's destination directory.
2. Without a temporary file:
The file that should be transferred obtains the name that is specified in the FileTransfer
object in the the beginning.
The method that should be used depends on the specifications that the the UC4 administrator
has made in the destination agent's INI-file parameter ft_temp_file=.
A temporary file is not created if an existing file is extended or overwritten. Contents are directly
inserted in the relevant files.
The huge advantage of temporary files lies in the simplified handling of further processing because
the files only obtain their specified names after they have successfully been transferred.
If an error occurs, the temporary file is deleted in the destination system. Files that could not
completely be transferred are not removed on UNIX and Windows computers. Therefore, the agent
does not have to newly start the file transfer if the FileTransfer is restarted.

AgentGroups

An AgentGroup can either be used as the source or as the target. This results in two possible ways
of usage:
1. File transfers from a single host to many target hosts.
2. File transfers from many hosts to a single target host.

Automation Engine

349

Pay particular attention to the latter one as the files must not have the same name. Otherwise, the
FileTransfer overwrites the files or it cannot transfer the file if it is being deployed by parallel
processes at that point in time. Insert the following variable in the target file name: &<FT_SRC_
HOST>. The FileTransfer replaces this variable with the name of the file's original host.
For example:
C:\temp\&<FT_SRC_HOST>_test*.txt
Note that AgentGroups cannot be selected in FileTransfers as a source and a target at the same
time!

Compression

Files can also be transferred in compressed form. You can activate this option in the FileTransfer
tab.
If you select the compression type "Default value" in the FileTransfer, the system uses the value
that the UC4 administrator has defined in the UC4 Variable UC_HOSTCHAR_DEFAULT, setting
FT_COMPRESS. The files are transferred in compressed mode if the two agents have different
settings.
Example:
WIN01 = No compression
UNIX01 = Active compression
The files are transferred in compressed form.
The agent uses the LZP+Huffman procedure for the compression.
When using compression, make sure that effort (time required for compression) and benefit (gain of
time because of reduced transfer time) are balanced against each other. An important component
for your decision is the available bandwidth of your network connection. You cannot increase
performance with fast networks (100 Mbit)because the compression process is more timeconsuming than the gain achieved by reducing the network time. With an available bandwidth of
10MBit or less, compression will definitely result in a performance increase.

End Status

Transferring a particular file:


A FileTransfer obtains the status ENDED_NOT_OK if the relevant file is not available.
Use case: AFileTransfer is to transfer a particular file which should then further be processed.
Transferring files using wildcard characters:
A FileTransfer obtains the status ENDED_EMPTY if no file is available which complies with the
filter specifications. It obtains the status ENDED_OK if at least one matching file is found.
Use case:A FileTransfer is to transfer several files whose naming convention follows a particular
pattern . The focus is on file names and not on the number of files.

UNIX and MPE

The UC4 administrator can use the parameter login_check=yes to specify in the INI files of the
UNIX and MPE agents that the Login object's password is checked. For reasons of security

350

Chapter3 Objects

UC4 recommends using this setting. Login_check=no only checks the user name.

VMS

In VMS, each text file requires a delimiter to be appended. The UC4 administrator can define in
the INI-file parameter FileEndDelimiter= whether the VMS agent should append one.

See also
FileTransfer Procedure
FileTransfer - Restarts

Object-Type specific Features

Restarts process FileTransfer scripts only partially but the corresponding task completely.
Windows and UNIX agents are exempted. They set restart points in regular intervals. A
repeated FileTransfer continues at the last restart point. The interval depends on the settings
that the UC4 administrator has defined in the parameter "JOB_CHECKINTERVAL" of the UC4
Variable UC_HOSTCHAR_DEFAULT.
Restart possibilities depend on the particular agent's version (FileTransfer protocol old/new):
Old FileTransfer protocol: Partially qualified can be repeated as a whole if the parent FileTransfer
object is used for a restart. It is also possible to repeat individual child FileTransfers.
New FileTransfer protocol: All files are processed via an activity. If the FileTransfer fails, it can be
continued starting with the last restart position.
Do so by selecting the option From last restart position . Restart points are created in a defined
interval while the files are being transferred. Use the key FT_RESTARTINFO_INTERVAL in the
UC_HOSTCHAR_DEFAULT to determine the required time interval. If the FileTransfer aborts, the
transfer can continue from the file position where the last restart point has been created. Restart
information is stored locally on the agent computer in the form of StatusStore files. A consistency
check is made to ensure that incomplete files have not been changed before the restart was
initiated. All restart information is deleted after the FileTransfer has successfully been completed.
More information is provided in the document that describes the FileTransfer Procedure.
In restarts, it is still possible to transfer all data from the beginning.
Restart options are only available for FileTransfers of the new protocol if the restart has been
called using the statistics and if the object has not been changed.

Automation Engine

351

When all information is transferred again in a restart, the existing files on the target system will
be overwritten even if the option "File exists - abort" is defined in the FileTransfer object. When
you select the option "File exists - append", the information is appended to the target file even if
the information has already been appended in the original run.
Background information: The option "Transfer all new" in the restart dialog has the effect that the
system ignores the StatusStore file of a previous FileTransfer execution and rebuilds the number
of hits. The target file is overwritten because in a restart, the agent cannot recognize whether a
file that already exists on the target file has actually been transferred by the previous original run
or not.
FileTransfer - Statistics/Report
The reports of FileTransfers list details about the file transfer in a particular structure.

Structure

This is how the report of FileTransfers is structured (new FT protocol):


1) Message that informs that the FileTransfer has started including the information about the file
filter that has been used.
U0011124 File search started with filter 'C:\temp\test*.txt' ...
2) List of the files that comply with the file filter. A message is output per file. It includes the absolute
path and the file name.
U0011125 'C:\temp\test.txt'
U0011125 'C:\temp\test2.txt'
3) Information that the file search is complete and the number of files that have been transferred.
U0011126 File search completed, '2' files selected.

352

Chapter3 Objects

4) Transfer status. A message that includes the following information is output for each file that has
been transferred:
l
l
l
l

Transfer was successful / not successful


Number of transferred bytes and records
Path and name of source and target file
Transfer duration in the format HH:MM:SS

U0011133 OK '1394' Bytes, '26' Records for file 'C:\temp\test.txt'->'D:\temp\test\test.txt'


transferred. Duration '00:00:00'.
U0011134 ERROR '0' bytes, incorrect transfer of '0' records for file 'C:\temp\test2.txt'>'D:\temp\test\test2.txt'. Duration '00:00:00'.
5) Information whether the FileTransfer (RunID) has ended successfully or with errors.
U0011408 FileTransfer '76836123' completed.
or
U0011409FileTransfer '76836123' ended abnormally.

For example

Report of a partially qualified (wildcard) FileTransfer that has ended abnormally:


2011-11-21 16:17:10 - U0011124 File search started with filter 'D:\Temp\webhelp_src\*' ...
2011-11-21 16:17:10 - U0011125 'D:\Temp\webhelp_src\uc4.htm' 2011-11-21 16:17:10 - U0011125
'D:\Temp\webhelp_src\uc4.js' 2011-11-21 16:17:10 - U0011125 'D:\Temp\webhelp_
src\uc4.mcwebhelp' 2011-11-21 16:17:10 - U0011125 'D:\Temp\webhelp_src\uc4.xml' 2011-11-21
16:17:10 - U0011125 'D:\Temp\webhelp_src\uc4_CSH.htm' 2011-11-21 16:17:10 - U0011125
'D:\Temp\webhelp_src\uc4_Left.htm' 2011-11-21 16:17:10 - U0011126 File search completed, '6'
files selected. 2011-11-21 16:17:10 - U0011133 OK '1394' Bytes, '26' Records for file
'D:\Temp\webhelp_src\uc4.htm'->'D:\Temp\webhelp_dst\uc4.htm' transferred. Duration '00:00:00'.
2011-11-21 16:17:10 - U0011133 OK '14634' Bytes, '541' Records for file 'D:\Temp\webhelp_
src\uc4.js'->'D:\Temp\webhelp_dst\uc4.js' transferred. Duration '00:00:00'. 2011-11-21 16:17:10 U0011133 OK '336' Bytes, '2' Records for file 'D:\Temp\webhelp_src\uc4.mcwebhelp'>'D:\Temp\webhelp_dst\uc4.mcwebhelp' transferred. Duration '00:00:00'. 2011-11-21 16:17:10 U0011134 FEHLER '0' Bytes, '0' Records for file 'D:\Temp\webhelp_src\uc4.xml'>'D:\Temp\webhelp_dst\uc4.xml' fehlerhaft transferred. Duration '00:00:00' . 2011-11-21 16:17:10 U0063018 FT(76836900): Datei 'D:\Temp\webhelp_dst\uc4.xml' kann nicht geffnet werden, error
code = '5 - Access is denied.'. 2011-11-21 16:17:10 - U0011133 OK '4474' Bytes, '171' Records for
file 'D:\Temp\webhelp_src\uc4_CSH.htm'->'D:\Temp\webhelp_dst\uc4_CSH.htm' transferred.
Duration '00:00:00'. 2011-11-21 16:17:10 - U0011133 OK '1394' Bytes, '26' Records for file
'D:\Temp\webhelp_src\uc4_Left.htm'->'D:\Temp\webhelp_dst\uc4_Left.htm'transferred. Duration
'00:00:00'. 2011-11-21 16:17:10 - U0011409 FileTransfer '76836900' ended abnormally.
The report of the old FileTransfer protocol is not structured coherently. Therefore it is not
described separately.
The reports of FileTransfers can be unloaded to text files by using the utility UC4.DB Archive. More
information about this functionality is provided in the Administrator Manual -> Utilities.
FileTransfer Attributes
The following overview includes the attributes of a FileTransfer object and describes their
functions, allowed values and ways of modification.

Tab

Attribute

Description

Value

Accesses

Automation Engine

353

ARCHIVE_
KEY1

Archive key 1

User-defined,
maximum 60 characters

GET_
ATT,
:PUT_
ATT,
Change
Program,
via script
variable,
predefined
variable

ARCHIVE_
KEY2

Archive key 2

User-defined,
maximum 20 characters

GET_
ATT,
:PUT_
ATT,
Change
Program,
via script
variable,
predefined
variable

ATTR_DLG

Attribute Dialog

"Y" - Attribute Dialog


displayed
"N" - Attribute Dialog not
displayed

GET_ATT

AUTO_DEACT

Deactivate automatically
when finished

"NEVER" - never deactivate


automatically
"ENDED_ERROR_FREE"
- deactivate automatically in
case of error-free execution
"RESTART_ERROR_
FREE" - deactivate
automatically in case of
error-free Restart
"ALWAYS" - always
deactivate automatically

GET_
ATT,
:PUT_
ATT
(Process)

AUTO_DEACT_
DELAY

Deactivate automatically
when finished - AlwaysTime delay

User-defined,
Value between "0" and "99"

GET_
ATT,
:PUT_
ATT
(Process)

AUTO_DEACT_
ERROR_FREE

Deactivate automatically
when finished - After an
error-free restart - Errorfree

Task status
maximum 20 characters

GET_
ATT,
:PUT_
ATT
(Process)

DATE_
CREATED

Created on

Time stamp in the format


"YYYY-MM-DD
HH:MM:SS"
If not available: "0000-00-00
00:00:00"

GET_ATT

354

Chapter3 Objects

DATE_
MODIFIED

Modified on

Time stamp in the format


"YYYY-MM-DD
HH:MM:SS"
If not available: "0000-00-00
00:00:00"

GET_ATT

DCMODUS

Mode UserInterface

"Y" - UserInterface active


"N" - No UserInterface
active

GET_ATT

FSC_HOST

Override host for


FileScan (optionally) Host

Name of an agent,
maximum 32 characters

GET_
ATT,
:PUT_
ATT
(Process),
Change
Program,
predefined
variable

FSC_LOGIN

Override host for


FileScan (optionally) Login

Name of a Login object,


maximum 200 characters

GET_
ATT,
:PUT_
ATT
(Process),
Change
Program,
predefined
variable

FT_COMPRESS

Compress

"NO" - no compression
"NORMAL" - normal
compression
"DEFAULT" - default
settings

GET_
ATT,
:PUT_
ATT
(Process),
Change
Program

FT_DST_
ACCOUNT

Login info
(only BS2000 and MPE)

Account information from


the Login info of Login object
as target of the FileTransfer

GET_
ATT,
predefined
variable

FT_DST_
CLIENT

Login info
(only SAP)

Client from the Login info of


Login object as target of the
FileTransfer

GET_
ATT,
predefined
variable

Automation Engine

355

FT_DST_CODE

To - Code

Name of a CodeTable,
maximum 200 characters

GET_
ATT,
:PUT_
ATT
(Process),
Change
Program,
predefined
variable

FT_DST_
DOMAIN

Login info
(only Windows)

Domain from the Login info


of Login object as target of
the FileTransfer

GET_
ATT,
predefined
variable

FT_DST_FILE

To - File

User-defined,
maximum 512 characters

GET_
ATT,
:PUT_
ATT
(Process),
Change
Program,
via script
variable,
predefined
variable

FT_DST_FILE_
ATTRIBUTES

To - File attributes

User-defined,
maximum 255 characters

GET_
ATT,
:PUT_
ATT
(Process),
via script
variable,
predefined
variable

FT_DST_
GROUPNAME

Login info
(only NSK and MPE)

Logon group from the Login


info of Login object as target
of the FileTransfer

GET_
ATT,
predefined
variable

FT_DST_HOST

To - Host

Name of an agent,
maximum 32 characters

GET_
ATT,
:PUT_
ATT
(Process),
Change
Program,
predefined
variable

356

Chapter3 Objects

FT_DST_LOGIN

To - Login

Name of a Login object,


maximum 200 characters

GET_
ATT,
:PUT_
ATT
(Process),
Change
Program,
predefined
variable

FT_DST_
LOGIN_INFO

Login info

All the Login info of Login


object as target of the
FileTransfer

GET_
ATT,
predefined
variable

FT_DST_
USERID

Login info

User ID from the Login info


of Login object as target of
the FileTransfer

GET_
ATT,
predefined
variable

FT_ERASE_
SRC_FILE

From - Erase source file

"Y" - Yes (GET_ATT


supplies "J"),
"N" - No

GET_
ATT,
:PUT_
ATT
(Process)

FT_EXISTING_
DST_FILE

To - File exists

"A" - abort FileTransfer,


"O" - overwrite file,
"E" - append to file

GET_
ATT,
:PUT_
ATT
(Process)

FT_FILE_TYPE

From - Format

"T" - text file


"B" - binary file

GET_
ATT,
:PUT_
ATT
(Process)

FT_INCLUDE_
SUB_DIR

From - Include sub


directories

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT
(Process)

FT_SRC_
ACCOUNT

Login info
(only BS2000 and MPE)

Account from the Login info


of Login object as source of
the FileTransfer

GET_
ATT,
predefined
variable

FT_SRC_
CLIENT

Login info
(only SAP)

Client from the Login info of


Login object as source of
the FileTransfer

GET_
ATT,
predefined
variable

Automation Engine

357

FT_SRC_CODE

From - Code

Name of a CodeTable,
maximum 200 characters

GET_
ATT,
:PUT_
ATT
(Process),
Change
Program,
predefined
variable

FT_SRC_
DOMAIN

Login info
(only Windows)

Domain from the Login info


of Login object as source of
the FileTransfer

GET_
ATT,
predefined
variable

FT_SRC_FILE

From - File

User-defined,
maximum 512 characters

GET_
ATT,
:PUT_
ATT
(Process),
Change
Program,
via script
variable,
predefined
variable

FT_SRC_FILE_
ATTRIBUTES

From - File attributes

User-defined,
maximum 255 characters

GET_
ATT,
:PUT_
ATT
(Process),
via script
variable,
predefined
variable

FT_SRC_
GROUPNAME

Login info
(only NSK and MPE)

Logon group from the Login


info of Login object as
source of the FileTransfer

GET_
ATT,
predefined
variable

FT_SRC_HOST

From - Host

Name of an agent,
maximum 32 characters

GET_
ATT,
:PUT_
ATT
(Process),
Change
Program,
predefined
variable

358

Chapter3 Objects

FT_SRC_LOGIN

From - Login

Name of a Login object,


maximum 200 characters

GET_
ATT,
:PUT_
ATT
(Process),
Change
Program,
predefined
variable

FT_SRC_
LOGIN_INFO

Login info

Entire Login info of Login


object as source of the
FileTransfer

GET_
ATT,
predefined
variable

FT_SRC_
USERID

Login info

User ID from the Login info


of Login object as source of
the FileTransfer

GET_
ATT,
predefined
variable

FT_
TRANSFER_
FOLDERS

From - Include subdirectories - Transfer


complete folder structure

"Y" - Yes,
"N" - No

GET_
ATT,
:PUT_
ATT
(Process)

FT_
WILDCARDS

From - Use Wildcards

"Y" - Yes,
"N" - No

GET_
ATT,
:PUT_
ATT
(Process)

GEN_AT_
RUNTIME

Generate at runtime

"Y" - Generation at runtime


"N" - Generation at
activation time

GET_ATT

GROUP

Group

Name of a Group,
maximum 200 characters
" " - for immediate start

GET_
ATT,
:PUT_
ATT
(Process),
Change
Program,
predefined
variable

Automation Engine

359

INT_ACCOUNT,
INT_ACC, K

Int. Account

User-defined,
maximum 16 characters

GET_
ATT,
:PUT_
ATT
(Process),
Change
Program,
via script
variable,
predefined
variable

LAST_DATE

Last used on

Time stamp in the format


"YYYY-MM-DD
HH:MM:SS"
If not available: "0000-00-00
00:00:00"

GET_
ATT,
predefined
variable

LAST_USER

Last used by

Name of the User object,


maximum 200 characters

GET_
ATT,
predefined
variable

MAX_
PARALLEL_
ELSE

Parallel running Tasks Else

"WAIT" - FileTransfer waits


until processing is possible
"ABEND" - FileTransfer
interrupted

GET_
ATT,
:PUT_
ATT
(Process)

MAX_
PARALLEL_
TASKS

Parallel running Tasks Max.

User-defined,
Value between "0" and
"99999"

GET_
ATT,
:PUT_
ATT
(Process),
predefined
variable

MAX_
PARALLEL_
TRANSFERS

From - Max. parallel


running transfers

User-defined,
Value between "0" and
"999"

GET_
ATT,
:PUT_
ATT
(Process),
predefined
variable

MAX_
RETCODE

ENDED_OK until
returncode

User-defined,
maximum 11 characters

GET_
ATT,
:PUT_
ATT
(Process)

MODIFY_
COUNT

Modified

Number of object
modifications

GET_ATT

OBJECT_NAME

Object name

User-defined,
maximum 200 characters

Change
Program

360

Chapter3 Objects

OBJECT_TITLE

Title

user-defined,
maximum 255 characters

GET_
ATT,
:PUT_
ATT
(Process),
predefined
variable

PPF_EXECUTE

Action - Execute

Name of an executable
object,
maximum 200 characters

Change
Program

PPF_FILTER

Action - Output filter

Name of a Filter object,


maximum 200 characters

Change
Program

PPF_
INHERITANCE

Inherit to dynamic child


tasks

"Y" - Yes
"N" - No
"C" - Children only

Change
Program

QUEUE

Queue

Name of a Queue,
maximum 200 characters

GET_
ATT,
:PUT_
ATT
(Process)
Change
Program,
predefined
variable

RESOURCE_
CONSUMPTION

Consumption
(Resources)

User-defined,
Value between "0" and
"99999"

GET_
ATT,
:PUT_
ATT
(Process)
Change
Program,
predefined
variable

SCRIPT

String in the script of the FileTransfer which should be


changed

Change
Program

SYNC_OBJECT

Assigned Sync object

Name of a Sync,
maximum 200 characters

Change
Program

TIMEZONE

TimeZone

User-defined
maximum 8 characters

GET_
ATT,
:PUT_
ATT
(Process),
predefined
variable

Automation Engine

361

UC4_PRIORITY

UC4 Priority

User-defined,
Value between "0" and
"255"

GET_
ATT,
:PUT_
ATT
(Process),
predefined
variable

USAGE_
COUNT

Last used

Number of object usages

GET_
ATT,
predefined
variable

USER_
CREATED

Created by

Name of the User object,


maximum 200 characters

GET_
ATT,
predefined
variable

USER_
MODIFIED

Changed by

Name of the User object,


maximum 200 characters

GET_
ATT,
predefined
variable

See also:
FileTransfer
Attributes
:PUT_ATT
GET_ATT function
UC4.DB Change

3.2.13 Filter
Filter
A Filter object can be used to define the criteria to be applied for searching reports of tasks and/or
files.
Object class: Passive object
Object type (short name): FILTER
It is available in the following object types:
l
l
l

FileTransfer
Job
RemoteTaskManager

Each of these object types includes an Output Scan tab in which you can create one or more Filter
objects and define the reaction to the filtering result.
Filter objects created in system client 0000 can be used in user-defined clients.
The UC4 administrator determines the memory size to be used for reading reports. The UC4
Variable UC_SYSTEM_SETTINGS provides the keys DEFAULT_REPORT_SCAN_
MEMORY and MAX_REPORT_SCAN_MEMORY which can be used for this purpose.

362

Chapter3 Objects

Header tab
The Header tab is a general tab which is available in every UC4 object.

Description

Field/Control Description
Title

Define object titles here. This title should contain a short and characteristic
description of the corresponding object as it is displayed in all overviews.

Created

Indicates the user who created this object including the date and time.

Modified

Indicates the user who last modified this object including the date and time. The
number of times the object has been modified is displayed to the right.

Last used

Indicates the user who last used the object including the date and time. The
number of times the object has been used is displayed to the right.
Only displayed if the update function in the UserInterface settings has been
activated.

Archive keys

Two keywords of your choice can be specified here.

Filter Tab
The Filter tab contains the criteria that should be applied in searching the reports of tasks or
files.

Automation Engine

363

Description

All filter definitions can contain the wildcard characters "*" and "?". "*" stands for any characters,
"?" for exactly one character. There is no need to use the * character at the beginning and the
end because the search takes place within the specified term.
For each Filter object, you can specify several different reports or files and you can also check
several terms in each file/report. To insert Filter definitions, you click in a field (such as Report contains) and then you click the "+" button that appears to its right. A new line will automatically be
inserted below the selected entry. To delete lines, you click "-".

Further important notes:


l

The task ends on status FAULT_POST_PROCESSING if the report does not exist or the file
cannot be accessed.

364

Chapter3 Objects
l
l

l
l

A line break is inserted if individual report lines exceed the report's block size.
The search function ignores line breaks. For example, searching for "ERROR*file" means
that the filter definition is met when "ERROR" and "file" are found in one line or in different
lines.
A text search is used for regular reports but also for XML reports.
The CodeTable of the agent that is used in the task is applied.

Field/Element

Description

Operation of the
filter definitions
AND operation

All filter definitions must apply.

OR operation

At least one filter definition must apply.

Filter definitions
Report

Report type
The report must be stored in the UC4 Database. Use the filter
definition "File" if you store reports in the file system.
The selected operation setting is also valid if wildcard characters are
used for the report type.
For example:
The string "ERROR" is to be found in reports of type "S*".
All SAP reports are searched. The filter definition is met if "ERROR" is
found in at least one SAP report (because of the OR operation).
contains
does not
contain

Any string.
The notation of the string is irrelevant because this field is caseinsensitive.
You can determine whether trailing spaces of the string should be
truncated or not in the UC4 Variable UC_SYSTEM_SETTINGS,
setting GET_PROCESS_LINE_RTRIM. By default, these spaces
are automatically removed.

File

File or filter for several files.


The selected operation setting is also valid if wildcard characters are
used in the file name.
For example:
The string "ERROR" is to be found in C:\Temp\*.txt.
The files a.txt and b.txt are available in the directory C:\Temp. An AND
operation has been selected; therefore, the filter definitions are only met if
"ERROR" exists in both files.
contains
does not
contain

Any string
Note that the search for files is case sensitive.

Automation Engine

Field/Element
Registered Job
Output

365

Description
File or filter for several files.
This filter category can be used to check the content of external Job
output files. Filter objects that include definitions of this kind can only be
used in combination with Jobs.
The condition does not apply if the specified file cannot be found.

contains
does not
contain

Any string

Documentation Tabs
Documentation tabs are user-defined and client-specific tabs that can be assigned to all object
types in UC4.

All Documentation tabs that have been defined by the UC4 administrator in the UC4 variable
UC_OBJECT_DOCU are shown. Note that imported objects have their own documentation
tabs.
The Version Management tab displays the stored object versions if this function has been
activated.

366

Chapter3 Objects

Structured Documentation

Each of these tabs can also be displayed in structured form. Structured documentation can be used
to split complex object information in well-arranged parts. Each documentation element can be used
to store texts, but also to define attributes.
You can also define links (e.g. to files, folders or to documents in the intranet and Internet etc.) in
structured documentation. Files are then displayed with the associated program, folders are
opened, URLs call the standard browser etc. The particular actions depend on the installed
programs and the user's PC configuration.

New Documentation tabs initially only include the "Content" folder. This is your starting point for
creating a further structure. To create and edit this structure, you can use the following context
menu commands:
Command

Description

Add attribute

Creates a new attribute in the highlighted element

Add node after

Inserts a new element after the highlighted element

Add node before

Inserts a new element before the highlighted element

Add node child

Creates a new element one level below the highlighted element

Duplicate node

Duplicates the highlighted element and its attributes and contents

Delete node

Deletes the highlighted element irrevocably

You can create one or more attributes for each individual element. Basically, there are two different
types: text and enumeration. You can add one or more of these attributes to an element. Determine
the attribute's name and then select whether it is a text or an enumeration. In enumerations, you can
specify the entries that should be included.

Automation Engine

367

Names of elements and attributes should comply with the XML naming convention. Letters,
numbers and the characters "-", ".", "_" can be used. Keep the following rules in mind:
l
l
l
l

The first letter of a name must neither be a number nor "." nor "-".
The name must not include blanks.
Do not use colons as they are reserved characters.
Names must not begin with "XML", regardless if uppercase or lowercase letters are used.

3.2.14 Group
Group
Groups can be used for the occasional execution of tasks. The particular tasks which should run
in a group obtain the start type "Group". Groups can be activated manually or directly in a
Workflow or Schedule.
Object class: Executable object
Object type (short name): JOBG
Another possible way of using a group is a queue. In this case the group is automatically activated if
the corresponding group's first task is started.
Note that the group is not taken into consideration if a task is activated by a Workflow,
Schedule or as a recurring task.
Creating Groups
Groups are used to manage the parallel execution of tasks as well as serving as queues. Objects
processed via a group show the name of the corresponding group in the Attributes tab(start
type).

368

Chapter3 Objects

Procedure

1. Click the button in the toolbar and a window listing all the available object types opens.
Select the type "Group" (JOBG).
2. Assigns a suitable name and open the Group object. Click the Notification tab
3. First determine the maximum number of tasks that can run parallel. A queue processing one
task after the other is created if more than one task is started which uses this group.
4. The next step serves to determine the activation type of the group. These two options are
available:
l By Call: The group can either be activated manually, via Workflow or Schedule. This
includes those tasks that were started in a group and are displayed in the Activity
Window with the status "Registered". Those tasks are processed as soon as the
group is started with one of the above mentioned options.
l Automatically (queue): When a task with the group being specified as start type is
started, the group is automatically also activated.
5. Use the optional setting of the Runtime tab if the execution of the group should be
monitored.
6. Script elements can be stored in the Process tab.
7. The option Generate at runtime - which is available in the Attributes tab- can be used to
influence the Group's generation time. With this option activated, the script is not processed
at object activation but only when it is started. These two points in time are not necessarily
the same (when the object is executed within the frame of a Workflow, for example).
8. Groups are executable objects.
There are various other settings that can be specified for Group objects. You can find details in
the documentation about the individual tabs.
Header tab
The Header tab is a general tab which is available in every UC4 object.
Object: Group
Object class: Executable object
Object type (short name): JOBG

Automation Engine

369

Description

Field/Control

Description

Header
Title

Define object titles here. This title should contain a short and characteristic
description of the corresponding object as it is displayed in all overviews.

Created

Indicates the user who created this object including the date and time. If the
object was loaded from a Transport Case the system is shown as user.

Modified

Indicates the user who last modified this object including the date and time.
The number of times the object has been modified is displayed to the right.

Last used

Indicates user, date and time regarding the most recent use of the object.
The number of times the object has been used is displayed to the right.
Information is only displayed if the updating function was activated in the
variable UC_SYSTEM_SETTINGS (LAST_USE).

Active

With this option being deactivated, the object will automatically be set to
inactive after its activation and not processed.
Therefore, the tasks obtain the status ENDED_INACTIVE_OBJECT (return
code: 1925).
This setting is available in the Header tab of all executable objects and is set
by default.

Archive keys

Statistical data can be selected using these archive keys. Archive keys are
displayed in the Statistical Overview and can be printed.

Extended Reports Extended reports can be written for all executable objects. They log the
complete script with all Includes, the generated JCL of Jobs or accesses to
UC4 objects.

370

Chapter3 Objects

Use Default (UC_ If you select this option the reports the UC4 administrator defined in the UC4
CLIENT_
Variable UC_CLIENT_SETTINGS with the key "EXT_REPORTS" are
SETTINGS)
generated.
All

All extended reports are written for this object.


This option overwrites possible pre-settings of the client.

None

No extended reports are written for this object.


This option overwrites possible pre-settings of the client.

See also:
Object Classes
Sync Tab
The Sync tab is object-type specific and is available in all executable UC4 objects.
Sync objects synchronize task on the basis of defined conditions. Enter one or several Sync
objects including the actions that should be taken in this tab if you want to make use of this
possibility.

The Sync objects are checked one after the other when the task starts. The UC4 Automation
Engine tries to use the Sync object of the first line by calling the start action. If this is not possible
because this is not allowed by the Sync object's current condition, the task waits, aborts or is
skipped. The type of reaction depends on the Else condition defined in the tab's last column. If
"wait" has been specified, the task waits until it can use the Sync object with the start action. Then
the UC4 Automation Engine checks the Sync object in the next line etc. The task starts as soon all
Sync objects could successfully be used. Depending on the task's end status, either an abend or
end action is processed.
Up to 500 Sync objects can be specified.

Automation Engine

371

All Sync objects must not include a total of more than 5000 rules. Rules are defined actions that
are directly entered in the Sync object.
Task ends are administered by work processes but only the primary work process releases busy
Syncs. Because of this task allocation, it can take several seconds until a Sync is released after
a task has ended. In this case, the report entry shows a time stamp which is later than the task
has ended. Such delays occur when the primary's work load is high or if it is processing lots of
Syncs.
Note that using many Sync objects and rules can reduce task clarity. UC4 recommends
reducing the number of Sync object to a minimum.

Description

Only actions that have been defined in the Sync object can be selected.
Field/Control

Description

Sync object

Selects the Sync object that should be used to synchronize the task.

Start action

Defines the action that should be taken when the task starts. If this is
not possible due to the Sync's status, the Else condition becomes
effective.

Abend action

This action is processed if the task aborts.

End action

This action is processed if the task ends successfully.

Else

You can define here what should happen to the task if the start action
cannot be executed:
l

l
l

The task should wait until the start action can be executed
(WAIT).
The task aborts (ABEND).
The task is skipped (SKIP).

See also:
Sync
Group - Attributes Tab
The Attributes tab is a type-specific tab which is found only in the Group object. It is used to
define the handling of tasks and defining the start specifications of the group.
Object: Group
Object class: Executable object
Object type (short name): JOBG

372

Chapter3 Objects

Description

Field/Control

Description

Attributes
Max. parallel-running
tasks

Specify the maximum number of executable objects which are allowed


to run simultaneously in a Group. 1 to 999 tasks are allowed.

Queue

Selection of a Queue objectin which the Group should be processed.


The Group automatically starts in the Client Queue(object name:
CLIENT_QUEUE) if nothing has been specified in this field.

Children Queue

Queue object which is used for the Group's tasks. The Queue of the
subordinate tasks is replaced by the value specified here if the Group is
being processed. The settings made in the individual tasks are used if
no value has been specified for "Children Queue".

Time zone

Time zone that should be used

Generate at runtime

Select this check box if it should not be generated at the time of


activation but instead at runtime.

The specified settings in this tab can be read and modified at runtime. Attributes of this object will
thereby be accessed with script statements and functions.
Runtime tab
The Runtime tab is an object class-specific tab which is available in every executable object in
UC4. It can be used to specify parameters for a task's runtime behavior.

Automation Engine

The Runtime tab is structured as follows:


l
l
l
l
l
l

Return code handling


Forecast setting
Evaluating the estimated runtime (Runtime Evaluation)
Monitoring the maximum runtime (Runtime Monitoring)
Monitoring the minimum runtime (Runtime Monitoring)
Reaction to runtimes that have been exceeded or not reached (Runtime Monitoring)

Description

Field/Control

Description

Definition for
ENDED_OK
Return code <=

Maximum return code for a task's normal end.


A task ends normally (Status "ENDED_OK") if its return code lies
below or is equal to the specified maximum return code.

Else execute

You can execute an object if the task does not end with a return code
that lies within the ENDED_OK area.
Note that this object will not be processed if the task is terminated
by using the script statement :EXIT.

End status for


forecast
Estimated runtime
(ERT)

Selection list for the end status that this task should return when you
make a Forecast calculation.

373

374

Chapter3 Objects

Current ERT =

Displays the task's next estimated runtime (ERT).


You can enter the estimated runtime here. This value applies until the
ERT calculation is made after the task's next execution.
Format: "hours:minutes:seconds".

Use default (UC_


CLIENT_SETTINGS)

Selecting this option has the effect that the calculation method that the
UC4 administrator specified in the UC4 Variable UC_CLIENT_
SETTINGS using the key "ERT_METHOD" is used to calculate the
estimated runtime.

Fixed value

A fixed value is entered as the estimated runtime.


Format: "seconds"

Dyn. method

Selection list for the dynamic method that is used to calculate the
estimated runtime from the real runtime.
Possible selection: Average, linear regression, maximal value

from the last ... runs

Number of past runs that are considered for the ERT calculation.
Allowed values: 0 to 25.

+ ... %

Value in percent for an upward ERT correction.

Differences > ... % are You can ignore possible huge differences to of actual runtimes.
ignored
Upper limit (in percent) for actual runtimes that should be included in
estimated runtime calculation.
but do use ... runs at
least

Number of past runs that should be considered regardless of


differences. Allowed value: 0 to 25.

Show Chart

Button that can be clicked in order to update the estimated runtime


according to the current settings. A diagram displays in a separate
window; it shows the last 25 ERT/RRT runs. Windows that are already
open are updated.

Reset Values

Button that can be used to delete the real and estimated runtimes.
A security query displays, confirm it and all saved runtimes are cleared.

Maximum runtime
(MRT)
None

The maximum runtime is not monitored.

Fixed value

The maximum runtime is monitored.


The allowed time is entered as a fixed value in the format
"hours:minutes:seconds". An action as an ELSE condition must be
specified which reacts when maximum runtime is exceeded.

ERT

The maximum runtime is monitored.


The valid estimated runtime (ERT) at the time of the task's activation is
used as the maximum runtime. An action as an ELSE condition must
be specified which reacts when maximum runtime is exceeded.

+ ... %

A correction in percent can be specified for ERT for the maximum


runtime. The determined value is added to the estimated runtime.

Automation Engine

Curr. date + day(s)


Time

The maximum runtime is monitored.

TimeZone

Selection of a TimeZone object.

375

A number of days and time of day are set for when the task must be
finished. The starting point for the calculation of the date is the real date
of the task. An action as an ELSE condition must be specified which
reacts when maximum runtime is exceeded.

Minimum runtime
(SRT)
None

The minimum runtime is not monitored.

Fixed value

The minimum runtime is monitored.


The allowed time is entered as a fixed value in the format
"hours:minutes:seconds". You must specify an action (ELSE
condition) that applies if the maximum runtime has been exceeded.

ERT

The minimum runtime is monitored.


The valid estimated runtime at the time of the task's activation is used
as its maximum runtime. You must specify an action (ELSE condition)
that applies if the maximum runtime has been exceeded.

- ... %

When you select the ERT, you can also specify a correction value in
percent for the maximum runtime. The value you determine is added to
the estimated runtime.

Else
Cancel / Quit

If you activate this check box is activated, the task is canceled or quit if
the runtime has been exceeded. Only available if the maximum runtime
is monitored.

Execute

If you activate this check box, you determine that the task is executed.
You can directly select the executable object. If the runtime is
exceeded or not reached, the specified task is executed. Only available
if the runtime is monitored.

Comments

A different type of runtime monitoring can be used for tasks that have been activated in a Workflow
or using the object "Schedule." You can define it in the properties of the relevant object (Runtime
tab). The setting that are defined within the context of a Workflow or Schedule overrule the settings
that have been defined in the task itself.
You can also assume these setting for runtime monitoring in the Workflow or Schedule. This is the
default setting.

See also:
Runtime Evaluation
Runtime Monitoring

376

Chapter3 Objects

Variables & Prompts Tab


The Variables & Prompts tab is object type-specific and is available in almost every
executable object in UC4.
Object: Group
Object class: Executable object
Object type (short name): JOBG
This tab has two tasks:
l
l

It stores object variables.


It assigns PromptSet objects.

Object variables

Object variables include values that belong directly to the object and can be read in the Process
tabs. Variable names and values are determined in the table shown below.
In the Value column, you can also enter predefined variables. Do so using the Variables...
button in the object's toolbar.
The same rules apply for object variable names and for script variables. If you omit the preceding
"&", it is automatically added during the storing process and is available the next time the object
opens.
Object variables and PromptSet variables can be inherited from the superordinate object. For
example, a Schedule's tasks can use the object variables of the Schedule object.
Field/Element

Description

Inherit from parent


All variables (default)

The object obtains all object variables and PromptSet variables of


the superordinate task.

Automation Engine

Only defined variables

377

The object only obtains the object variables of the superordinate


task that have been defined in its Variables & Prompts tab.
PromptSet variables are only inherited if the PromptSet object
complies with these values and the value that should be
overwritten has not been changed in the Variables & Prompts
tab.

No variables

The object obtains all object variables and PromptSet variables of


the superordinate task.

Note that inherited variables overwrite existing object variables if they have the same name. In
contrast, PromptSet variables are never overwritten.
The following procedure can be used if you want to overwrite PromptSet variables with the value
of a parent variable:
Open the task's Workflow or Schedule properties and switch to the Variables & Prompts tab.
Select the PromptSet area and use the Workflow's or Schedule's variable name as the value of
the relevant PromptSet element. If the PromptSet area is not a text field, click the labeling of the
PromptSet element.
PromptSet objects

In the Variables & Prompts tab, you can also select one or several PromptSet objects that should
be called during the activation process. In doing so, you can overwrite the default values of
PromptSet elements. These modifications do not affect the PromptSet object itself.
You can use the "+" and "-" buttons to add or remove PromptSet objects. Several PromptSet
objects are called from top to bottom. Use the arrow buttons if you want to change this order.
To adjust the task's PromptSet values, you directly modify the PromptSet elements.
Click on the blue description that displays next to the elements when you also want to use variables
in the default value. The effect is that the PromptSet elements now appear as a gray text field that
has the name of the related PromptSet variable. In this specific text field, you can either manually

378

Chapter3 Objects

enter the predefined variables, or select them in a dialog that you call using the
button.
Clicking the blue description again deletes your previous entries and the PromptSet element
appears in its original view.
Predefined variables are already deleted when the PromptSet input mask is called. Note that the
values of predefined variables can change during the object's execution (for example, with UC4
Script) but the PromptSet variable still stores the old value.
An error occurs when the object should be stored and an element's value does not fulfill the
limitations of the PromptSet properties (min. value, max. value, max. length, value required etc).
The affected fields are highlighted in yellow.
If the values differ from the reference values, an error only occurs when the object starts and an
attempt is made to send the prompt. Ensure that the data type and other limitations (min. value,
max. value, format) of the reference variable are preserved.
Using the same variable names has the effect that the object variable values are overwritten by
the PromptSet variables. The value of the PromptSet object that has last been called is used if
selected PromptSet objects include identical variable names.
Graphical elements that are removed from the PromptSet object are also removed from the
Variables & Prompts tab. Modifications made in the PromptSet object's default values do not
affect the Variables & Prompts tab. The values of the PromptSet object are only available
when the PromptSet object is newly selected.

See also:
Object Variable
Designer tab
Rollback Tab
The Rollback tab is an object-specific tab that is available in every executable object that can be
included in a workflow.
The Rollback tab can be used to define actions that store the task (= Backup) and restore it (=
Rollback). These settings are only useful when the object runs in a workflow because you can only
start a rollback process within a workflow.
The backup and rollback functions are especially designed to undo erroneous installation and
deployment processes that are defined in the UC4 Deployment Manager but are processed by
using the Automation Engine.
Backup actions will always be processed before the object is processed, and rollback actions can
only be started via workflows. For more information, see the related documentation.

Automation Engine

Field/Element

Description

Enable Rollback

Use this to activate or deactivate the rollback settings.

379

When this option is deactivated, all the fields of this tab are
disabled.
Custom Rollback
Backup

Specify an executable object that is responsible for the


backup process.
If you specify a Backup object, it will always automatically
run before the task runs, regardless of how the object is
activated.
The actions and steps that must be defined in the Backup
object depend on the processes and actions of the related
task. Note that you must define them manually. For
example, if you use an object to update your database, it is
useful to include a database using the Backup object.

Rollback

Specify an executable object that is responsible for the


rollback process.
The definition of the Rollback object depends on the
current object or the Backup object and must be made
manually. The Rollback object's basic task is to undo
modifications in the case of an error in order to ensure that
a previous working status will be restored. For example, if
the Backup object creates a database backup, the
Rollback object should be able to restore this backup.
The Rollback object will be processed when the task
starts in Rollback mode which is only possible in a
Workflow.

380

Chapter3 Objects

Group - Process Tab


The Process tab is a type-specific tab in which processing instructions are stored in UC4's
scripting language.
Object: Group
Object class: Executable object
Object type (short name): JOBG

Description

The script is either processed at Group activation or start. This point in time depends on the setting
"Generate at runtime" which can be defined in the Attributes tab.
A Group's script cannot contain JCL lines.

See also:
Script Editor
About UC4 Scripts
SampleCollection
Documentation Tabs
Documentation tabs are user-defined, client-specific tabs which can be assigned to all object
types in UC4.
Object: Group
Object class: Executable object
Object type (short name): JOBG

Automation Engine

381

All Documentation tabs that have been defined by the UC4 administrator in the UC4 variable
UC_OBJECT_DOCU are shown. Note that imported objects have their own documentation
tabs.
The Version Management tab displays the stored object versions if this function has been
activated.

Structured Documentation

Each of these tabs can also be displayed in structured form. Structured Documentation can be used
to split complex object information in well-arranged parts. Each documentation element can be used
to store texts, but also to define attributes.
You can also define links (e.g. to files, folders or to documents in the Intranet and Internet etc.) in
structured documentation. Files are then displayed with the associated program, folders are
opened, URLs call the standard browser etc. The particular actions depend on the installed
programs and the user's PC configuration.

382

Chapter3 Objects

New Documentation tabs initially only include the "Content" folder. This is your starting point for
creating a further structure. To create and edit this structure, you can use the following popup-menu
commands :
Command

Description

Add attribute

Creates a new attribute in the highlighted element.

Add node after

Inserts a new element after the highlighted element.

Add node before

Inserts a new element before the highlighted element.

Add node child

Creates a new element one level below the highlighted element.

Duplicate node

Duplicates the highlighted element and its attributes and contents.

Delete node

Deletes the highlighted element irrevocably.

You can create one or more attributes for each individual element. Basically, there are two different
types: text and enumeration. You can add one or more of these attributes to an element. Determine
the attribute's name and then select whether it is a text or an enumeration. In enumerations, you can
specify the entries that should be included.

Automation Engine

383

Names of elements and attributes should comply with the XML naming convention. Letters,
numbers and the characters "-", ".", "_" can be used. Keep the following rules in mind:
l
l
l
l

The first letter of a name must neither be a number, nor ".", nor "-".
The name must not include blanks.
Do not use colons as they are reserved characters.
Names must not begin with "XML", regardless if uppercase or lowercase letters are used.

Group - Execution
Object: Group
Object class: Executable object
type (short name): JOBG

Object-type-specific Features

The activation of a group can be carried out manually or as an object in a Workflow or in a


Schedule. Groups can be put in certain positions in a Workflow. When the Workflow reaches the
position that a group has been placed in the group is automatically activated.
The Jobs that are in a "noted" condition in the activities at this time are processed . This also applies
to Jobs which are set after the activation of a Workflow (even up to the time of processing the
groups). Only after the last job of the group is completed is the group itself completed. A group ends
abnormally when a job in the group ends abnormally.
A special type of group, the queue, allows you to take care of sporadic Jobs according to the defined
attributes of the handling of the set tasks (Jobs).
In a queue, the attribute "Generate at runtime" is ignored (if it has been activated) because queues
are always activated at runtime.

384

Chapter3 Objects

Activation of an Application Order


l
l
l
l

Each job containing the group in the start type is recognized as "Registered" after activation.
The state of the selected group is then checked.
If the group is inactive the job remains recognized as "Registered".
If the group is already active the number of simultaneously-running Jobs in the group is
checked.
If the maximum number of Jobs in the group is reached the job remains recognized as
"Registered".
If the maximum number of Jobs in the group is not yet reached the following job is selected
according to priority and FIFO and started in the group.

Activation of Application during a Queue


l
l
l
l

l
l

Jobs for queues are also recognized as "Registered" after activation.


The state of the queue is then checked.
If the queue is inactive the job stays "Registered" and the queue is activated.
If the queue is active (even if it has only been activated by the job itself), the number of
simultaneously-running Jobs in the queue is checked.
If the maximum number of Jobs in the queue is reached, the job remains "Registered".
If the maximum number of Jobs in the queue is not yet reached the following job is selected
according to priority and FIFO and started in the queue.

Stop Execution
An already-activated group or queue can be halted and restarted at any time. If a group or queue is
halted there are no more noted Jobs for the group. The stop condition is not valid for already active
Jobs. They are processed as normal. There is a STOP function which includes all sub-Jobs. Here,
all Jobs of the EVNT and JOBP type are also halted.
Handling
Click the right mouse
button on the task in
the Activity Window

Select the command Stop or GO in the context menu.

Selection of the group


in the Activity Window

Select the command Stop, or GO in the menu File.

Cancel
There are two different ways of canceling a Group. The corresponding commands are available in
the Activity Window's context menu or in the File menu.
l

Cancel:
The Group switches to the status "Canceling" and waits until the active tasks end. The
Group ends when the corresponding tasks have finished. Scheduled tasks do not start and
remain in the Activity Window.
Cancel (recursive):
The Group including all its active tasks are canceled immediately. Tasks with the status
"Registered" remain in the Activity Window showing this waiting condition.

Automation Engine

385

Restart
Object: Group
Object class: Executable object
Object type (short name): JOBG

Object-type-specific Features

You can use a restart to process the Group's script partially. The task itself is always completely
re-executed.
Group - Monitor
During execution the Group monitor is available in which running tasks are displayed. The
graphical representation of the tasks corresponds to the Activity Window.
Object: Group
Object class: Executable object
Object type (short name): JOBG
Via the context menu (right mouse button) various commands can be executed which refer to
individual tasks or the Group. For an individual task you can look at, for example, Details, Statistics
or the Report. You can edit tasks, show a generated Job, or delete a task's entry in the Group.

Right-clicking the context menu without highlighting an object facilitates the export of task states
and display of group attributes. In the Attributes tab, the number of parallel running tasks is
changeable. However, the user must have the authorization "M" (Modify) for Groups.

386

Chapter3 Objects

Calling the Monitor


Right mouse button on
Group in the Activity
Window

Select Monitor in the context menu.

Group selection in the


Activity Window

Select Monitor in the File menu.

See also:
Group
Group Attributes
The following overview lists the attributes that are available for Group objects and describes their
functions, allowed values and ways of modification.

Tab

Attribute

Description

Value

Access
Via:

ARCHIVE_
KEY1

Archive key 1

User-defined,
limited to 60 characters,

GET_
ATT,
:PUT_
ATT,
Change
Program,
via script
variable,
predefined
variable

Automation Engine

387

ARCHIVE_
KEY2

Archive key 2

User-defined,
limited to 20 characters.

GET_
ATT,
:PUT_
ATT,
Change
Program,
via sript
variable,
predefined
variable

CHILD_
QUEUE

Children Queue

The name of the Queue object for the


group's tasks,
limited to 200 characters.

GET_
ATT,
:PUT_
ATT,
Change
Program,
predefined
variable

DATE_
CREATED

Created on

The time stamp in the format "YYYY-MMDD HH:MM:SS"


If not available: "0000-00-00 00:00:00"

GET_ATT

DATE_
MODIFIED

Modified on

The time stamp in the format "YYYY-MMDD HH:MM:SS"


If not available: "0000-00-00 00:00:00"

GET_ATT

DCMODUS

Mode
UserInterface

"Y" - UserInterface active


"N" - No UserInterface active

GET_ATT

GEN_AT_
RUNTIME

Generate at
runtime

"Y" - Generation at runtime


"N" - Generation at activation time

GET_ATT

GR_MAX_
PAR_JOBS

Max. parallelrunning tasks

User-defined,
any value between "0" and "999".

GET_
ATT,
:PUT_
ATT

When reading the attribute, the system


returns a 16-digit value with leading zeros.
LAST_
DATE

Last used on

The time stamp in the format "YYYY-MMDD HH:MM:SS"


If not available: "0000-00-00 00:00:00"

GET_
ATT,
predefined
variable

LAST_
USER

Last used by

The name of the User object,


limited to 200 characters.

GET_
ATT,
predefined
variable

MAX_
RETCODE

ENDED_OK
until return
code

User-defined,
limited to 11 characters.

GET_
ATT,
:PUT_
ATT

MODIFY_
COUNT

Modified

The number of object modifications.

GET_ATT

388

Chapter3 Objects

OBJECT_
NAME

Object name

User-defined,
limited to 200 characters.

Change
Program

OBJECT_
TITLE

Title

User-defined,
limited to 255 characters.

GET_
ATT,
:PUT_
ATT,
predefined
variable

QUEUE

Queue

The name of a queue,


limited to 200 characters.

GET_
ATT,
:PUT_
ATT,
Change
Program,
predefined
variable

SCRIPT

The string in the Process tab of the group should be changed.

Change
Program

SYNC_
OBJECT

Assigned Sync
object

The name of a Sync object,


limited to 200 characters.

Change
Program

TIMEZONE

TimeZone

User-defined
limited to 8 characters.

GET_
ATT,
:PUT_
ATT,
predefined
variable

USAGE_
COUNT

Last used

The number of object usages.

GET_
ATT,
predefined
variable

USER_
CREATED

Created by

The name of the User object,


limited to 200 characters.

GET_
ATT,
predefined
variable

USER_
MODIFIED

Changed by

The name of the User object,


limited to 200 characters.

GET_
ATT,
predefined
variable

See also:
Group
Attributes
:PUT_ATT statement
GET_ATT function
UC4.DB Change

Automation Engine

389

3.2.15 Include
Include
Includes can be used to store often-used and identical script parts which will be recalled for
various tasks.
Object class: Passive object
Object type (short name): JOBI
Often-used and repeating Script Parts are best stored in the Include object. This way, the syntax
corresponds exactly to the script of the object in which the Include object is used. Script variables
can be passed if they have already been defined and supplied in the actual object.
In the object, the Include object is included via :INC statement and inserted at activation time in the
script of the calling object.

See also:
Using Script Components
Header tab
The Header tab is a general tab which is available in every UC4 object.

Description

Field/Control

Description

390

Chapter3 Objects

Title

Define object titles here. This title should contain a short and
characteristic description of the corresponding object as it is displayed
in all overviews.

Created

Indicates the user who created this object including the date and time.

Modified

Indicates the user who last modified this object including the date and
time. The number of times the object has been modified is displayed to
the right.

Last used

Indicates user, date and time regarding the most recent use of the
object. The number of times the object has been used is displayed to
the right.

Process Tab
The Process tab is an object type-specific tab which contains processing instructions in UC4's
scripting language.
Object class: Include
Object class: Passive object
Object type (short name): JOBI

Description

The script is processed in objects which integrate it using the script statement :INCLUDE.
The script of an Include object can contain JCL lines if it is used in Job objects.

See also:

Automation Engine

391

Script Editor
About UC4 Scripts
SampleCollection
Documentation Tabs
Documentation tabs are user-defined and client-specific tabs that can be assigned to all UC4
objects.

All Documentation tabs that have been defined by the UC4 administrator in the UC4 variable
UC_OBJECT_DOCU are shown. Note that imported objects have their own documentation
tabs.
The Version Management tab displays the stored object versions if this function has been
activated.

Structured Documentation

Each of these tabs can also be displayed in structured form. Structured Documentation can be used
to split complex object information in well-arranged parts. Each documentation element can be used
to store texts, but also to define attributes.
You can also define links (e.g. to files, folders or to documents in the Intranet and Internet etc.) in
structured documentation. Files are then displayed with the associated program, folders are
opened, URLs call the standard browser etc. The particular actions depend on the installed
programs and the user's PC configuration.

392

Chapter3 Objects

New Documentation tabs initially only include the "Content" folder. This is your starting point for
creating a further structure. To create and edit this structure, you can use the following popup-menu
commands :
Command

Description

Add attribute

Creates a new attribute in the highlighted element.

Add node after

Inserts a new element after the highlighted element.

Add node before

Inserts a new element before the highlighted element.

Add node child

Creates a new element one level below the highlighted element.

Duplicate node

Duplicates the highlighted element and its attributes and contents.

Delete node

Deletes the highlighted element irrevocably.

You can create one or more attributes for each individual element. Basically, there are two different
types: text and enumeration. You can add one or more of these attributes to an element. Determine
the attribute's name and then select whether it is a text or an enumeration. In enumerations, you can
specify the entries that should be included.

Automation Engine

393

Names of elements and attributes should comply with the XML naming convention. Letters,
numbers and the characters "-", ".", "_" can be used. Keep the following rules in mind:
l
l
l
l

The first letter of a name must neither be a number, nor ".", nor "-".
The name must not include blanks.
Do not use colons as they are reserved characters.
Names must not begin with "XML", regardless if uppercase or lowercase letters are used.

Structured documentation can be read with specific script elements (XML_*).

3.2.16 Job
Job
A job is used to define processing steps in a target system. It can be used independently, in a
Group, or within a Workflow.
Object class: Executable object
Object type (short name): JOBS
The Job objects of RA Solutionsdiffer from the standard Job objects that UC4 supplies. More
detailed information about tabs is provided in the description of the relevant RA Solution.

Creating Jobs - Basics


Job-type objects are probably the most used object types. They can be used for executing
commands on computers or in Enterprise Business Solutions (SAP, PeopleSoft, Oracle
Applications, and Siebel). Individual Job-object templates are available for each of these
platforms because they all differ from each other. Therefore, the first step when you create a job
is to decide upon the operating system or business solution on which it will actually run.

394

Chapter3 Objects

Procedure

1. Click the button in the toolbar. A window opens and lists all the available object types
including the objects for the individual platforms. Select one of them.
2. Assign an appropriate name for the Job object and open it. Click the Notification tab
3. Agents are actually executing the Job. Select the particular agent in the Host tab which runs
on your computer or is connected to the business solution on which the commands should be
processed.
4. The agent requires login information for the execution of the Job. This information is stored in
Login objects. Select the required one in "Login".
5. The various Job objects have their individual Host tabs, each depending on the platform. The
settings that are available for job reports are what they have in common. Select where the job
report should be stored. The particulars applying to the individual operating systems or
Enterprise Business Solutions are described in the document Creating Jobs - Details.
6. The settings in the Runtime tab can be used for monitoring the job while it is being executed.
7. The following tabs are available in Job objects and can be used for storing the processing
statements:
l Pre-Process: Contains the statements which prepare the job for its execution. This
tab is mainly used for setting attributes with :PUT_ATT (such as specifying the
required Agent).
l Process: This tab is the core of the Job object in which the JCL statements can be
written.
l Post-Process: Contains the statements that should be executed when the job has
already ended. For example, the report can be read (PREP_PROCESS_REPORT) or
the Job's return code (MODIFY_STATE) be modified.
l Child Post-Process: This special Process tab is only available in SAP Jobs. The
statements it contains apply to all the Job's children.
8. The order of the Process tabs listed above represents the order in which they are processed.
A detailed overview is found in the document Stages of Workflow execution. You can also
control the generation time of the Pre-Process and Process tabs with the option Generate
at runtime which is available in the Notification tab Activation of this option causes the two
tabs not to be generated at object activation but rather when it is started. job activation and
generation can take place at different points in time - when the object is executed in a
Workflow, for example.
More settings can be specified in Job objects. Detailed descriptions are available in the
documents of the particular tabs.

See also:
Creating Jobs - Details
Creating Jobs - Details
Depending on the particular platform that is used, Host tabs offer various ways of specifying
settings. More detailed information about how individual settings affect jobs and special features
that are available in the different job types are listed below.

BS2000
[BS2000] [GCOS8] [JMX] [MPE] [NSK] [Oracle Application] [z/OS] [OS/400] [PeopleSoft] [SAP] [Siebel]
[SQL] [UNIX] [VMS] [Windows]

All options of this Host tab are optional and can be used as required.

Automation Engine

395

GCOS8
[BS2000] [GCOS8] [JMX] [MPE] [NSK] [Oracle Application] [z/OS] [OS/400] [PeopleSoft] [SAP] [Siebel]
[SQL] [UNIX] [VMS] [Windows]

All options of this Host tab are optional and can be used as required.

JMX
[BS2000] [GCOS8] [JMX] [MPE] [NSK] [Oracle Application] [z/OS] [OS/400] [PeopleSoft] [SAP] [Siebel]
[SQL] [UNIX] [VMS] [Windows]

The connection to the MBean Server can be selected in this Host tab. The following options are
available:
l
l
l

An MBean Server is searched for on the same computer.


The MBean Server is locally available in a SAP J2EE Server.
The connection is established to the MBean Server of the specified URL.

UC4 offers various functions for accessing the individual MBeans. Use the graphical user interface
of the Form tab to create scripts. These processing statements are then automatically stored in the
Process tab.

MPE
[BS2000] [GCOS8] [JMX] [MPE] [NSK] [Oracle Application] [z/OS] [OS/400] [PeopleSoft] [SAP] [Siebel]
[SQL] [UNIX] [VMS] [Windows]

Indicate a job name in the Host tab. All other parameters can optionally be used.

NSK
[BS2000] [GCOS8] [JMX] [MPE] [NSK] [Oracle Application] [z/OS] [OS/400] [PeopleSoft] [SAP] [Siebel]
[SQL] [UNIX] [VMS] [Windows]

Select one of the following types when creating an NSK Job: Job for Guardian, NetBatch or OSS.
The options provided in the Host tab are the same for all types and can be used as required.

Oracle Applications
[BS2000] [GCOS8] [JMX] [MPE] [NSK] [Oracle Application] [z/OS] [OS/400] [PeopleSoft] [SAP] [Siebel]
[SQL] [UNIX] [VMS] [Windows]

Completing the fields Key and App. Short Name is mandatory. UC4 provides several functions for
the processing of statements which are stored in the Process tab.

z/OS
[BS2000] [GCOS8] [JMX] [MPE] [NSK] [Oracle Application] [z/OS] [OS/400] [PeopleSoft] [SAP] [Siebel]
[SQL] [UNIX] [VMS] [Windows]

396

Chapter3 Objects

In z/OS Jobs you can select where the JCL should be stored:
l
l
l

JCL is written to the Pre-Process or Process tab.


JCL is stored in an z/OS file.
JCL and job card are stored on z/OS. With this setting being specified, the runtime options of
the Host tab are not considered during job execution.

OS/400
[BS2000] [GCOS8] [JMX] [MPE] [NSK] [Oracle Application] [z/OS] [OS/400] [PeopleSoft] [SAP] [Siebel]
[SQL] [UNIX] [VMS] [Windows]

The type of processing statements can be specified in OS/400 Jobs. CMD (OS/400 commands),
ILE CL script and REXX script are available. The specifications made in the Host tab are always
optional, regardless of the type that has been selected. Additionally you can define whether the
Job's whole spool content or only the spool content of QPJOBLOG should be written to the report.

PeopleSoft
[BS2000] [GCOS8] [JMX] [MPE] [NSK] [Oracle Application] [z/OS] [OS/400] [PeopleSoft] [SAP] [Siebel]
[SQL] [UNIX] [VMS] [Windows]

UC4 provides several functions which can be used for executing processing statements in
PeopleSoft. Use the graphical user interface of the Form tab to create a script. All processing
statements are automatically stored in the Process tab.

SAP
[BS2000] [GCOS8] [JMX] [MPE] [NSK] [Oracle Application] [z/OS] [OS/400] [PeopleSoft] [SAP] [Siebel]
[SQL] [UNIX] [VMS] [Windows]

The processing statements in SAP Jobs are composed of UC4 functions that can be created using
the Form tab. Numerous optional specifications are available. Note that some specifications can
affect functions. An overview is available in the KnowledgeBase which informs about possible
effects.

Siebel
[BS2000] [GCOS8] [JMX] [MPE] [NSK] [Oracle Application] [z/OS] [OS/400] [PeopleSoft] [SAP] [Siebel]
[SQL] [UNIX] [VMS] [Windows]

In Siebel Jobs, it is mandatory to indicate a Server in the Host tab. The function SI_START_TASK
can be used to set Siebel commands.

SQL
[BS2000] [GCOS8] [JMX] [MPE] [NSK] [Oracle Application] [z/OS] [OS/400] [PeopleSoft] [SAP] [Siebel]
[SQL] [UNIX] [VMS] [Windows]

Specify database-connection information in the Host tab and change the settings if necessary.
Subsequently, you can enter SQL statements in the Form tab or directly in the Process tab.

Automation Engine

397

UNIX
[BS2000] [GCOS8] [JMX] [MPE] [NSK] [Oracle Application] [z/OS] [OS/400] [PeopleSoft] [SAP] [Siebel]
[SQL] [UNIX] [VMS] [Windows]

Two job types are available for UNIX: Shell Script and command. With Shell Script being used,
UC4 transfers the JCL of the Process tab to the target system and then executes it. Type
command, however, ignores the content of the Process tab. The statements made in the Host tab
are processed instead.
Select the particular UNIX Shell in which the job is supposed to run. The Shell selection list of the
Host tab can be extended. The UC4 administrator can do so using the UC4 Variable UC_SHELL_
UNIX which is available in system client 0000.

VMS
[BS2000] [GCOS8] [JMX] [MPE] [NSK] [Oracle Application] [z/OS] [OS/400] [PeopleSoft] [SAP] [Siebel]
[SQL] [UNIX] [VMS] [Windows]

All options of this Host tab are optional and can be used as required.

Windows
[BS2000] [GCOS8] [JMX] [MPE] [NSK] [Oracle Application] [z/OS] [OS/400] [PeopleSoft] [SAP] [Siebel]
[SQL] [UNIX] [VMS] [Windows]

The following types of Windows jobs are distinguished:


l
l
l

Processing statements are executed in the form of batch files.


A particular given program is started.
Processing statements are transferred to an interpreter as a file.

You can also use Job objects if required. A further particularity of Windows Jobs is that job reports
can also be created via script.

See also:
Creating Jobs - Basics
Header tab
The Header tab is a general tab which is available in every UC4 object.

398

Chapter3 Objects

Description

Field/Control

Description

Header
Title

Define object titles here. This title should contain a short and
characteristic description of the corresponding object as it is displayed
in all overviews.

Created

Indicates the user who created this object including the date and time.

Modified

Indicates the user who last modified this object including the date and
time. The number of times the object has been modified is displayed to
the right.

Last used

Indicates user, date and time regarding the most recent use of the
object. The number of times the object has been used is displayed to
the right.

Active

With this option being deactivated, the object will automatically be set
to inactive after its activation and not processed.
Therefore, the tasks obtain the status ENDED_INACTIVE_OBJECT
(return code: 1925).
This setting is available in the Header tab of all executable objects and
is set by default.

Archive keys

Two keywords of your choice can be specified in all executable objects


and the Sync object. These keys are written to the statistical data each
time the object is processed.
Statistical data can be selected using these archive keys. Archive keys
are displayed in the Statistical Overview and can be printed.

Automation Engine

399

Extended Reports

Extended reports can be written for all executable objects. They log the
complete script with all Includes, the generated JCL from Jobs or
accesses to UC4 objects.

Default (UC_
CLIENT_SETTINGS)

If you select this option the reports the UC4 administrator defined in the
UC4 Variable UC_CLIENT_SETTINGS with the key "EXT_
REPORTS" are generated.

All

All extended reports are written for this object.


This option overwrites possible pre-settings of the client.

None

No extended reports are written for this object.


This option overwrites possible pre-settings of the client.

Output Tab
The Output tab is object-specific and is only available in "Job" objects that use the host types
Windows, UNIX, SAP, RA, JMX or SQL. In this tab, you can enter files that are generated by the
Job. After the Job has been executed, you can directly access these files via the UserInterface.

Files that are specified in this tab are registered as external Job outputs. After the Job has been
executed, these files are listed in the Directory tab of the report dialog in which they can be directly
accessed. UC4 recommends only specifying files that are expected through execution of the Job
(such as a text file that the JCL generates in the Process tab).
The files are retrieved directly by the responsible agent and must therefore be accessible to it. An
error occurs if the agent cannot find a file or if the file cannot be accessed.
Standard Job outputs (report, JCL etc.) are automatically registered as outputs.
You can also register output files by using the script element :REGISTER_OUTPUTFILE. This
is only supported for Windows and UNIX Jobs.
Field/Element

Description

400

Chapter3 Objects

Fully qualified file name

Path and name of the file that


should be registered.
Note that you must specify the
path in full. Wildcard
characters are not allowed.
The file extension is irrelevant.

Requires User's Login

When the agent accesses the


output file via the
UserInterface, it logs on to the
computer and transfers the
file. If you check this option,
the Login object that has been
assigned to the particular UC4
user (User tab - default login)
is used. Otherwise, the login
information of the Job's Login
object is used.
With this option activated, a
default login that can be used
to log on to the agent must be
selected in the User object.
Otherwise, an error occurs
when you open the output file.

See also:
Registered Job Output
Sync Tab
The Sync tab is object-type specific and is available in all executable UC4 objects.
Sync objects synchronize task on the basis of defined conditions. Enter one or several Sync
objects including the actions to be included in this tab if you want to make use of this possibility.

Automation Engine

401

The Sync objects are checked one after the other when the task starts. The UC4 Automation
Engine tries to use the Sync object of the first line by calling the start action. If this is not possible
because this is not allowed by the Sync object's current condition, the task waits, aborts or is
skipped. The type of reaction depends on the Else condition defined in the tab's last column. If
"wait" has been specified, the task waits until it can use the Sync object with the start action. Then
the UC4 Automation Engine checks the Sync object in the next line etc. The task starts as soon all
Sync objects could successfully be used. Depending on the task's end status, either an abend or
end action is processed.
Up to 500 Sync objects can be specified.
All Sync objects must not include a total of more than 5000 rules. Rules are defined actions
which are directly entered in the Sync object.
Task ends are administered by work processes but only the primary work process releases busy
Syncs. Due to this task allocation, it can take several seconds until a Sync is released after a
task has ended. In this case, the report entry shows a time stamp which is later than the task
has ended. Such delays occur when the primary's work load is high or if it is processing lots of
Syncs.
Note that using many Sync objects and rules can reduce task clarity. UC4 recommends
reducing the number of Sync object to a minimum.

Description

Only actions which have been defined in the Sync object can be selected.
Field/Control

Description

Sync object

Selects the Sync object to be used for synchronizing the task.

Start action

Defines the action to be taken at task start. If this is not possible due to
the Sync's status, the Else condition becomes effective.

402

Chapter3 Objects

Abend action

This action will be processed if the task aborts.

End action

This action will be processed if the task ends successfully.

Else

Define what should happen to the task if the start action cannot be
executed:
l
l
l

Task should wait until the start action can be executed (WAIT)
Task aborts (ABEND)
Task is skipped (SKIP)

See also:
Sync
Attributes Tab
The Attributes tab is object type-specific and is only available in Job objects. The target system
and all settings that are required in order to execute a job are defined here.
Object: Job
Object class: Executable object
Object type (short name): JOBS

Description

Field/Control

Description

Attributes
Host

You can define the name of the target system (Agent) on which the job
should run here. You can also specify an AgentGroup.

Automation Engine

Code

403

Name of the CodeTable that this job should use.


If no CodeTable has been selected, the default CodeTable of the
agent that uses this job is used.
See: CodeTable - Usage

Group

If the job should be started by a Group, you can select this Group here.
If there is no entry, the job is activated immediately.
Note that the entry specified here is not considered if the job was
started through a Workflow, a Schedule or as a recurring task.

Queue

Selection of a Queue objectin which the job should be processed. The


job automatically starts in the Client Queue(object name: CLIENT_
QUEUE) if nothing has been specified in this field.

Login

Selection of a Login object.


The Login object contains the data that is used by Jobs in order to log
on to operating systems or applications.
The User profile that is specified in the Login object must be
activated on the OS/400 platform if you specify the value "1" as
otherwise, you cannot start Jobs.

Int. Account

Specification of an internal account.


Contents do not affect the UC4 system's internal processing. You can
access the attribute "Int. Account" with script elements and integrate it
in your processes.

Consumption ...
(Resources)

Resources consumed during execution.


Allowed values: 0 to 99999
Default value: 0
Selecting value 0 has the effect that the resource value that the
UC4 administrator has specified in the UC4 Variable UC_
SYSTEM_SETTINGS with the key WORKLOAD_DEFAULT_JOB
is used.

UC4 Priority ... (0-255)

Priority that should be used to execute this job in UC4.


Allowed values: 0 to 255
Default: 0
Selecting value 0 has the effect that the priority that the UC4
administrator has specified in the UC4 Variable UC_CLIENT_
SETTINGS with the key TASK_PRIORITY is used.

TimeZone

TimeZone that should be used.

Attribute Dialog

If this check box is selected, a dialog is displayed at activation.


Attributes for the current execution of the job can be modified here.

Generate at runtime

Select this checkbox if the job should not be generated at activation


time but at its runtime.

Tasks running
parallel

404

Chapter3 Objects

Max ...

Setting that defines the maximum number of parallel executions for


this Job.
Allowed values: 0 to 99999
Default: 0 (no limit on tasks running parallel)
Examples:
Max. 1 - At any time, not more than one job execution must be
available
Max. 2 - At any time, not more then two active job executions must be
available.
.etc.

Else: Wait Abort

Instruction that defines how this job should be handled if the execution
exceeds the specified maximum number of tasks that can run at the
same time.
Wait = The job waits until execution is possible.
Abort = The job is interrupted.

Deactivate autom.
when finished

The workflow's settings for automatic deactivation apply for file


transfers that are processed as part of this workflow. These
settings overrule the settings of subordinate tasks.
When the Activity Window contains many tasks that are not
deactivated automatically or manually when they are finished, this
can negatively affect performance and the Activity refresh cycle.
Note that Jobs that use the option Generate at runtime which end
on the status "FAULT_OTHER - Start impossible" are not
automatically removed from the Activity Window. The settings that
are defined for an automatic deactivation process are ignored in this
case.

No

The job is not automatically deactivated and remains visible in the


Activity Window after it has been executed.

After the first program


run has error-free
ended

The job is automatically deactivated after successful execution.


Interrupted Jobs remain visible in the Activity Window and must be
deactivated manually.
You can also set a status for the error-free execution and a time delay
for de-activation. Do so by specifying the fields Error-free status
and/or Time delay ... Minutes .

After an error-free
restart

The job is automatically deactivated when a restart has been


successfully executed. Previously interrupted Jobs are also
deactivated.
You can also set a status for the error-free execution and a time delay
for de-activation. Do so by specifying the fields Error-free status
and/or Time delay ... Minutes .

Error-free status

Status that confirms a successful job execution. If no status is


selected, the system-return codes 1900 - 1999 (ANY_OK) represent
error-free execution.

Automation Engine

Always

405

The job is always automatically deactivated after it has been executed.


Additionally you can specify a time delay for deactivation in the TimeDelay field.

Time delay ... Minutes

The job is automatically deactivated after a specified number of


minutes. You can also manually deactivate it before this time is over.
The time difference only affects jobs whose execution also results in
automatic deactivation.

Host Attributes Tabs

Host Attributes Tab


The Host Attribute tabs are object type-specific tabs which are only available in the "Job"
object. They serve to define the platform-specific parameters of a Job's execution.
Object: Job
Object class: Executable object
Object type (short name): JOBS
Tab design depends directly on target system type:
l
l
l
l
l
l
l
l
l
l
l
l
l
l
l

BS2000
GCOS8
JMX
MPE
NSK
Oracle Applications
z/OS
OS/400
PeopleSoft
SAP
Siebel
SQL
UNIX
VMS
Windows

Some of the specified settings in these tabs can be read at runtime and modified. The Attributes of
this object are then accessed with script elements. If the check box "Attribute Dialog" in the
Attributes tab is selected, attributes can be influenced by the user first. Subsequently, access is
granted to the attributes in the script.

BS2000
The following document explains the platform-specific settings for a BS2000 job.

406

Chapter3 Objects

Description
Field/Control

Description

SYSOUT
Database

The SYSOUT protocol is handled by UC4. After the job has been
processed, the UC4 Automation Engine takes the SYSOUT protocol
that has been stored on the agent computer and stores it to the UC4
Database.

File

The SYSOUT protocol is handled by UC4. After the job has been
processed, the SYSOUT protocol is available in the target system as a
file.

On error only

If the job is interrupted, the SYSOUT protocol is saved in the UC4


Database and/or in the target system as a file. This field is only
available if "Database" and/or "File" has been selected.

SYSLST
Database

The SYSLST protocol is handled in UC4. After the job has bee
processed, the SYSLST protocol is transferred to the UC4 Database
using a FileTransfer.

File

The SYSLST protocol is handled by UC4. After the job has been
executed, the SYSLST protocol is available in the target system as a
file.

On error only

If the job is interrupted, the SYSLST protocol is saved in the UC4


Database and/or in the target system as a file. This field is only
available if "Database" and/or "File" has been selected.

Runtime options

Automation Engine

407

Priority

Specification of the Job's priority.

max. CPU time

Maximum CPU time (in seconds) that is available for the Job. If the
value that is specified here is exceeded, the OS cancels the job and it
obtains the UC4 status ENDED_VANISHED.

Express

Activate this check box if the job should start immediately, regardless
of the batch limit.

Job class

Specification of the Job's class.

Order name

The order name (PNAME) is specified here.

Enter parameter

You can enter any number of enter parameters here, separate them
using commas. The allowed parameters depend on the BS2000 version
that is used. A detailed description is available in the "BS2000/OSD
Commands" manual under the "/ENTER-JOB" command. For
example: TIME=NTL, RERUN-AFTER-CRASH=YES
Parameters that have already been defined cannot be used again (max.
CPU time, priority, express, job class, order name).

GCOS8
The document shown below explains the platform-specific settings for a GCOS8 job.

Description
Field/Control
Job report

Description

408

Chapter3 Objects

Database

The job report is managed by UC4. When the job has been processed,
the UC4 Automation Engine takes the process protocol which has been
stored on the agent computer and stores it to the UC4 Database.

File

The job report is managed by UC4. After job execution, the process
protocol is available as a file in the target system.

On error only

In case of job interruption, the job report is saved in the UC4 Database
and/or a file in the target system. This function is only available when
"Database" and/or "File" have been selected.

Start parameter
Urgency

Specification of the priority with which the job should be executed. A


value between "0" and "63" can be entered.

SNUMB

Sequence number of the Job


If no particular number has been specified, it is created automatically.
The agent's INI file contains the parameter SNUMB_SUFFIX which
the UC4 administrator can use to define the appended character.

IDENT

Name for the $IDENT statement.

Include Job

Path and name of a file containing a Job. This job is executed just
before the Trailer is processed and must therefore not contain a $
ENDJOB statement!

JMX
The following document explains the platform-specific settings for a JMX job.

Automation Engine

409

Description
Field/Control

Description

Job report
Database

The job report is managed in UC4. When the job has been processed, the UC4
Automation Engine takes the process protocol which has been stored on the
agent computer and stores it to the UC4 Database.

File

The job report is managed in UC4. After the execution of a Job, the process
protocol is available in the target system as a file.

On error only

The job report is stored in the UC4 Database and/or a file in the target system
only if the job has been canceled. This function is only available when
"Database" and/or "File" have been selected.

Optional
reports
Agent log

Activating this checkbox has the effect that a report including the Agent's
messages about the job execution is added to the task.

MBean
Server
Local Java
VM

The MBean Server is on the same computer as the JMX Agent.

Use any
existing
MBean Server

The MBean Server is automatically retrieved.

Create new
instance if not
found

Setting for instance creation

Specify
MBean Server

A given MBean Server is used.

Agent ID

An AgentID can be indicated if a particular agent should be used.

JNDI

The connection is established to a local MBean Server which is located in a


SAP J2EE Server.

Name of the
object

Name of the object to be called

Remote Java
VM

MBean Server can explicitly be indicated

Initial Context
Factory
(optional)

It depends on the vendor of the MBean Server whether this connection


parameter should be indicated.

Server URL

URL to the computer on which the MBean Server is found

Important notes for creating jobs


Oracle WebLogic:

410

Chapter3 Objects
l
l
l

Select "Remote Java VM" in the Job object's JMX tab.


Enter the term "weblogic" in the field Initial Context Factory .
Specify the Weblogic server for the server URL in the format shown below:
t3://name of the Weblogic server:port of the Weblogic server

IBM WebSphere:
Using the RMI connector:
l
l
l

"Remote Java VM" must be selected in the Job object's JMX tab.
Enter the term "websphere" in the field Initial Context Factory.
Specify the Server URL in the following format:
Host name of the WebSphere:port of BOOTSTRAP_ADDRESS

Using the SOAP connector (Websphere with activated administrative security):

The agent now uses the SOAP connector. Select "Remote Java VM" in the Job object's
JMX tab.
Enter "websphere" in the field Initial Context Factory .

Note that when the INI-file section [WEBSPHERE] does not include any settings
(which is an option as of Websphere version 7), you must enter the value "webspere soap" in
the Initial Context Factory field.
Specify the Server URL in the following format:

Host name of the WebSphere:SOAP port


l

Retrieve the port number as follows: Log on to the administrator console. Click on
Servers -> "Application server", then on your Server. Select "Transfers" -> "Ports". Use the
port number shown here in the URL. The SOAP port's default value is 8880.
Three passwords separated by commas must be specified in the Job's Login object.
l The 1st password is the user password.
l The 2nd password is the keystore password.
l The 3rd password is the truststore password.

The Soap Connector must be activated. Its port is in most cases 8880.
JBoss:
l
l
l

Select the option Local Java VM in the Job object's JMX tab.
Activate the sub-menu "Use existing MB Server".
It is not necessary to select the option "Generate new instance...".

Oracle Containers for J2EE:


l
l
l

"Remote Java VM" must be selected in the Job object's JMX tab.
Enter the term "oc4j" in the field Initial Context Factory.
Specify the Server URL in the following format:
service:jmx:rmi://Host name of the Oracle J2EE server:port/oc4j

SAP Netweaver:
l

Select "JNDI" in the JMX tab of the Job object. Enter the object name "jmx".

The JMX agent runs outside of an application server:


l
l

Select the option Local Java VM in the Job object's JMX tab.
Activate the sub-items "Use existing MBean Server" and "Create new instance...".

Automation Engine

411

MPE
The document shown below explains the platform-specific settings for a MPE job.

Description
Field/Control

Description

Job report
Database

The job report is managed by UC4. When the job has been processed,
the UC4 Automation Engine takes the process protocol which has been
stored on the agent computer and stores it to the UC4 Database.

File

The job report is managed by UC4. After the job execution, the process
protocol is available as a file in the target system.

On error only

In case of job interruption, the job report is saved in the UC4 Database
and/or a file in the target system. This is only available when
"Database" and/or "File" have been selected.

Runtime options

The host attributes defined here are assigned to the command "JOB"
as a parameter. They form the job card of the MPE Job.

Job name

Specification of a name under which the job should be executed.


A maximum of 8 alphanumeric characters are allowed. The first must
be a letter.

412

Chapter3 Objects

Queue

Selection list for the queue in which the job should run which
determines the execution's priority. "BS" stands for the highest, "ES"
for lowest priority. The default value is "DS".
The UC4 administrator administers the queue in the UC4 Variable
UC_MPE_QUEUE. A maximum of 8 characters is allowed for userdefined queues.

Input priority

Specification of the input priority (INPRI). This value is used for the
logon of the Job.
A value between "1" and "13" can be use for Input Priority. The default
value is "8".
Jobs must be prioritized so that they are above the current job fence set
by the system operator. If a value is specified which is less than or
equal to this, access is denied.

HIPRI

Check box for activating HIPRI.


HIPRI can be used to overwrite the job fence or the limit for Jobs set to
be executed. The authorizations System Manager (SM) or System
Operator (OM) are required.

Other

Additional parameters for the "JOB" command.


A maximum of 256 characters are possible. The parameters must be
specified according to the syntax..

NSK
The document shown below explains the platform-specific settings for a NSK job.

Automation Engine

413

Description
Field/Control

Description

Job report
Database

UC4 administers job reports. When the job has been processed, the
UC4 Automation Engine takes the process protocol which has been
stored on the agent computer and stores it to the UC4 Database.

File

UC4 administers job reports. After job execution, the process protocol
is available in the target system as a file.

On error only

If an error occurs, job reports are stored in the UC4 Database and/or in
the form of a file in the target system. "On error only" is only available if
"Database" and/or "File" have been selected.

Job type

3 types of NSK jobs are available:


l
l
l

Guardian - TACL commands


OSS - UNIX commands (osh Shell)
NetBatch - NBEXEC scripts

Start parameter
Priority

Specification of the Job's priority. Values between 1 and 199 are


possible.

CPU

Number of the CPU on which the job should run. Values between -1 and
15 can be selected. With value -1 being used, the system selects a
CPU.

Virtual Terminal

HP NonStop Server name comprising of a maximum of 26


alphanumeric characters and the separators \ $. # and -. Inputs and
outputs can be made on this device. Therefore, it is not possible to
specify a disk file because this might cause error messages. Physical
or virtual terminals or the corresponding processes (e.g. subtype 30
processes) can be used instead.
Use the keyword "none" to suppress the values defined in the INI file.

Note
Job reports are stored on the HP NonStop Server as odd unstructured files. These files only contain
texts and line breaks. They can be transferred to a PC using a binary (!) file transfer for evaluation
and then be read and edited with any text program. Use the HP tool CTOEDIT (operating system standard package) to convert this text file as only then it can be processed on the HP NonStop
Server.

See also:
Automated handling of prompts

Oracle Applications
The document shown below explains the platform-specific settings for an Oracle Applications
job.

414

Chapter3 Objects

Description
Field/Control

Description

Job report
Database

The job report is managed under UC4. After the Job's execution,
information on concurrent request in Oracle Applications is written to
the UC4 Database.

File

The job report is managed by UC4. After job execution it is available in


the target system as a file.

On error only

In case of job interruption, the job report is saved in the UC4 Database
and/or a file in the target system. This is only available when
"Database" and/or "File" have been selected.

Responsibility
Key

Profile option for the Oracle user: Key denoting responsibility.

Application Short
Name

Profile option for the Oracle user: Short name of the application.

OS/400
The document shown below explains the platform-specific settings of an OS/400 job.

Automation Engine

415

Description
Field/Control

Description

Job report
Database

UC4 administers the job report. When the job has been processed, the
UC4 Automation Engine takes the job report which has been stored on
the agent computer and stores it in the UC4 Database.

File

UC4 administers the job report. When the job has been processed, the
job report is available as a member in the target system.

On error only

The job report is only stored in the UC4 Database and/or as a file in the
target system if the job has been canceled. Only available when
"Database" and/or "File" have been selected.

Spool
QPJOBLOG

Only the spool contents of QPJOBLOG are stored in the UC4 Database
and/or are available as a member in the target system.

*ALL

The Job's complete spool contents are stored in the UC4 Database
and/or are available as a member in the target system.

Type
CMD

The job consists of OS/400 commands. If an error occurs in one of


these commands, the job ends abnormally. The severity code is set as
the Job's return code.

ILE CL

The job consists of an ILE CL script and is compiled by the agent before
it is processed. The compiled CL program processed subsequently.
The Job's return code can be set using the CL command "CHGVAR
VAR(&RETCODE) VALUE('0')".

416

Chapter3 Objects

REXX

The job consists of a REXX script and is passed on to the interpreter.


The Job's return code can be set using the REXX statement "retcode =
6".

Runtime options
Job name

Indicates the name which the system assigns to the job for processing.
If this attribute does not include a value, the agent creates a name in the
form "J" + RunID (minimum: 7 digits, maximum: 10 digits) + 2-figure
client number (e.g.: J0421121504).

Priority

Indicates the priority to be used for processing this Job.


The priority is a value between 1 (highest priority) to 99 (lowest priority).
This value represents the Job's importance when compared to other
Jobs in their struggle for system resources. If a value has been
specified and a successful SBMJOB has been made, the agent
executes a CHGJOB with this priority.

Job description

Indicates the name of this Job's description in the form Library/Job


description (Library can be omitted). Default value: *USRPRF

Job queue

Indicates the name of the job queue in which the job is queued in the
form Library/Job queue (Library can be omitted). Default value: *JOBD

Rooting data

Indicates the rooting data used to initiate the Job's first rooting step.
This rooting data determines the root entry which marks the program
the job executes. Default value: *JOBD

PeopleSoft
The document shown below explains the platform-specific settings for a PeopleSoft job.

Automation Engine

417

Description
Field/Control

Description

Job report
Database

The job report is managed by UC4. After job execution the information
on the PeopleSoft process (start and end times, status, session ID,
return code etc.) is stored in the UC4 Database.
The PeopleSoft process log can also be retrieved from the PeopleSoft
Process Scheduler Batch Server and added to the UC4 report.

File

The job report is managed by UC4. After the job execution it is available
in the target system as a file.

On error only

In case of job interruption, the job report is saved in the UC4 Database
and/or a file in the target system. This is only available when
"Database" and/or "File" have been selected.

Runtime options
Delete process
request after
execution

If this check box is activated, the process requirement will be deleted


after execution in PeopleSoft.

RA
The RA tab content is the same in all RA (Rapid Automation) Jobs.

418

Chapter3 Objects

Description
Field/Control

Description

Report
Database

The job report is administered in UC4. When the Job has been
processed, the UC4 Automation Engine takes the process
protocol that is stored on the agent computer and stores it to
the UC4 Database.

File

The job report is administered in UC4. The process log is


available as a file in the target system after the job run.

On error only

When the job is canceled, the corresponding report is stored in


the UC4 Database and/or a file in the target system. This field
is only available when you have selected "Database" and/or
"File".

Optional reports
Agent log
Runtime options

When this checkbox is active, a report that contains the


Agent's messages about the job run will be added to the task.

Automation Engine

Request task parameters

419

With this option being set, a dialog opens during the Job's
activation process in which you can change the specific RA
attributes / parameters (you find them in the specific RA tab).
Any modification will only affect the specific run and the object
definition itself remains unchanged.
Specifically, a PromptSet dialog opens before the Job is being
generated which is similar to other PromptSet dialogs. If one
or several PromptSet objects are assigned to the Job
("Variables & Prompts" tab), they will be displayed in a
common dialog together with the RA parameters during the
Job's runtime.
Note that the settings PROMPT_REPSONSETIME and
PROMPT_TIMEOUT(UC4 Variable UC_CLIENT_
SETTINGS) also affect the RA parameter dialog.
To have the RA parameter dialog also displayed for
Workflow tasks, you must specify the settings "Task
Prompts" in the properties (General tab) accordingly.

See also:
Rapid Automation

SAP
This document explains the platform-specific settings of an SAP job.
The SAPtab's content depends on the selected SAP job type (such as ABAP and JAVA).

420

Chapter3 Objects

Description
Field/Control

Description

Report
Database

The job report is maintained by UC4.


job reports consist of:
l
l
l

the actual job report (LIST0SO)


the specification of the created spool file
the cover page with the selected parameters (if required)

File

The job report is maintained by UC4. When the job has been executed,
the corresponding log is available in the target system as a file.

On error only

If the job is canceled, the corresponding report is stored in the UC4


database and/or a file in the target system. This field is only available if
"Database" and/or "File" have been selected.

Optional reports

Reportsretrieved from the SAP system:


l
l
l
l
l

Agent log
Application logs
Spool directory
Step lists
Statistics

These reports are available for the SAP job but not for its children.
Start parameter
Language

Language used in SAP.


The particular as language code is automatically passed on to SAP in
uppercase letters. Keep this in mind when you set the language using
script (attribute: SAP_LANG, script element :PUT_ATT).

Job name

Job name in SAP.


Max. 32 characters
The following format is used if no job name has been specified:
UC_JOB_RUN#

Job class

List for specifying the priority that should be used for handling jobs in
SAP.

Automation Engine

Target system

421

No specification or target system in SAP.


Up to SAP Basis Release 4.0:
This is the name of the host on which the job should be executed. An
SAP instance with work processes for batch processing must run on
this host.
SAP Basis Release 4.5 and later:
This is the name of an SAP Server in the form "<host name>_<system
ID>_<system no>". For example: "host31_T40_00". This SAP Server
must contain work processes for batch processing.
SAP recommends not using these parameters because they
invalidate "Workload Balance" for batch processes.

Delete job after


completion in CCMS.

Click this box if the job should be deleted in SAP after its execution.

but not on error

The job is not deleted if an error occurs in SAP.

Start mode

In the UC4 Interface, the option "as soon as possible" is used. If you
use the XBP interface you can select from two settings.

Deletion takes place in the CCMS (Computing Center Management


System) which is a special application area for administrators.

The UC4 administrator can define the interface that should be used
in the SAP agent's INI file.
As soon as possible

The system attempts to start the job as soon as possible.


If there is no SAP background task available, the job is scheduled in the
SAP system.

Immediately

The system attempts to start the job immediately.


The job aborts if there is no SAP background task (Type BTC)
available.

Spool list recipient


Recipient

Receiver

Address Type

Type of address

Report send status

Returns the transmission status. The sender is informed whether the


addressee has received the message.
If the option Default is selected, it depends on the value that is
specified in the SAP system whether a receipt is sent.

Report status by mail

Returns the transmission status by email.


If the option Default is selected, it depends on the value that is
specified in the SAP system whether a receipt is sent.

Copy

The recipient obtains a copy for information.

Blind Copy

The recipient obtains a blind copy that cannot be read by any other
person.

Express

Express sending. A dialog window opens in which you can switch to


the inbox.

No forwarding

The recipient is not allowed to forward the document to other users.

422

Chapter3 Objects

No printing

Printing the document is not allowed.

The following SAP support packages are required for using the options No printing, Report
send status and Report status by mail:
l
l
l
l

for 4.6C: SAPKB46C52


for 6.20: SAPKB62059
for 6.40: SAPKB64017
for 7.00: SAPKB70008

See also:
Consideration of Job Attributes

Siebel
The document shown below explains the platform-specific settings for a Siebel job.

Description
Field/Control

Description

Job report
Database

The job report is managed by UC4. When the job has been processed,
the UC4 Automation Engine takes the process protocol which has been
stored on the agent computer and stores it to the UC4 Database.

File

The job report is managed by UC4. After job execution, the process
protocol is available as a file in the target system.

Automation Engine

423

On error only

In case of job interruption, the job report is saved in the UC4 Database
and/or a file in the target system. This function is only available when
"Database" and/or "File" have been selected.

Start parameter

Always indicate the parameters "Gateway Server" and "Enterprise


Server".

Gateway Server

Network address of the Siebel Gateway computer

Enterprise Server

Name of the Enterprise Server

Siebel Servers

Name of the Siebel Server

Language

Login language

Compression
Encryption

Setting whether data should be transferred compressed and/or


encrypted.

See also:
Starting and Monitoring Tasks in Siebel

SQL
The document shown below explains the platform-specific settings for an SQL hob.

Description
Field/Control

Description

424

Chapter3 Objects

Job Report
Database

The job report is maintained in UC4. When the Job has been
processed, the UC4 Automation Engine takes the process protocol
which has been stored on the agent computer and stores it to the UC4
Database.

File

The job report is maintained in UC4. The process log is available in the
form of a file in the target system after job execution.

Only in the case of


error

The job report is only stored in the UC4 Database and/or in the form of a
file in the target system if the job is canceled. This checkbox is only
available when "Database" and/or "File" have/has been checked.

Optional reports
Agent log

Activating this checkbox has the effect that a report including the
Agent's messages about the job execution is added to the task.

Connection
Connection object

The DB Connection object that is used for the connection to the


database.
When you specify a Connection object, this object's connection data is
used and the definition that have been made in the Job object (in the
text fields "Server" and "Database") will be ignored.
When a Login object is defined in the job's Attributes tab, this object's
loin information will be used. When no Login object is defined, the login
information will be retrieved from the Connection object.
The job will abort when there is neither a Login object nor a Connection
object definition.
The job will also fail when the database types of the agent and the
Connection object do not match.

Server

Name of the computer on which the database has been installed


Format: Server name:Port
Example: PC01:2281
The standard ports are:
l
l
l
l

MSSQLServer:1433
Oracle: 1521
DB2:50000
MySQL: 3306

It is not required to fill in this field if the Job should be processed in


an Oracle database in RAC.
Informix requires the port to be specified.
Database

Name of the database


Informix requires the name of the Informix Server and the database
name to be separated by a slash.
Example: ol_ids_1110_1/ang

File name

Path and file name of the MS Access database

Automation Engine

425

Settings
Show headlines in
tables

Setting for the display of table headlines

Show NULL as empty


string

This option displays a field with the content NULL in the form of an
empty string "".

Remove line breaks

This setting removes all line breaks used in a column.

Column separator

Character used to separate columns in the results of SELECT


statements.

Substitute character

If the character specified as column separator is used within a


database field, the substitute character specified here is used.

Max. number of lines


in tables

If the result of an SQL statement contains more lines than specified


here, these are truncated.
This limitation applies to each SQL statement.
The number of lines is not limited if value "0" is specified.

Max. number of
characters in a table
column

The content of a database field is truncated if it comprises of more


characters than specified here.
Database fields whose contents were specified as numbers or time
stamps are not truncated.
Note that there are limitations to the script function PREP_
PROCESS_REPORT when the report is read column by column.

UNIX
The document shown below explains the platform-specific settings for a UNIX job.

426

Chapter3 Objects

Description
Field/Control

Description

Job report
Database

The job report is maintained in UC4. When the job has been processed,
the UC4 Automation Engine takes the process log which is available on
the agent computer and stores it to the UC4 Database.

File

The job report is maintained in UC4. When the job has been processed,
the UNIX process log is available in the target system in the form of a
file.

On error only

When the job has been canceled, its report is saved in the UC4
Database and/or on the target system in the form of a file. Only
available if "Database" and/or "File" have been selected.

Type
Shell Script

A job is generated, transferred to the target system and executed as a


shell script. The JCL for the UNIX job is stored in the Process tab.

Command

The command or command sequence, stored in the Command field, is


passed on to the UNIX command line. The shell which has been
defined in this tab is the one which will be called. The standard shell will
be used if no shell has been defined.
No job is generated and transferred to the target system. JCL
contained in the Process tab will be ignored. The rest will be
processed.

Start parameter

Automation Engine

Shell

427

Unix Shell, under which the job should run.


UC4 uses the standard shell from the password file if no shell has been
selected.
The UC4 administrator maintains the shells in the UC4 Variable
UC_SHELL_UNIX.

Shell options

Specification of shell options. The syntax of the parameters used for


calling the shell depends on the particular Unix Shell.

Command

Individual shell command or sequence of shell commands. Is passed


on to the shell and executed by it. Several commands are separated by
semicolons.

VMS
The document shown below explains the platform-specific settings for a VMS job.

Description
Field/Control

Description

Job report
Database

The job report is managed by UC4. When the job has been processed,
the UC4 Automation Engine takes the process protocol which has been
stored on the agent computer and stores it to the UC4 Database.

File

The job report is managed by UC4. After the job execution, the process
protocol is available as a file in the target system.

428

Chapter3 Objects

On error only

In case of job interruption, the job report is saved in the UC4 Database
and/or a file in the target system. This is only available when
"Database" and/or "File" have been selected.

Start parameter
Priority

Specification of the priority for the Job. A value between "0" and "255"
can be entered.
Priority is currently not analyzed by VMS.

Job name

Specification of the name under which a job should be executed.


Maximum 39 characters allowed.

Queue name

Specification of the queue in which the job should be activated.


Maximum 31 characters allowed.

Windows
The document shown below explains the platform-specific settings of a Windows job.

Description
Field/Control

Description

Job report
Database

The job report is handled by UC4. After a job has been processed, the
UC4 Automation Engine takes the process protocol which has been
stored on the agent computer and stores it to the UC4 Database. Doing
so is only possible if a protocol can be created. It is not possible if a
command has been used.

Automation Engine

429

File

The job report is handled by UC4. After the job execution, the process
protocol is available as a file in the target system. This only works if a
protocol can be created. It is not possible if a command has been used.

On error only

In case of job interruption, the job report is saved in the UC4 Database
and/or a file in the target system. This is only available when
"Database" and/or "File" have been selected.

Is generated by script

Select this check box in order to create an own job report instead of
STDOUT/STERR.

Type
BAT

The script statements and DATA lines that are stored in the script are
executed as MS-DOS batch file.

COM

The program that is stored in the entry field Command is executed.


The complete path and command line can be specified if needed.
The UC4 script elements that are stored in the Job object's Process
tabs are executed. The agent skips all occurring OS commands.

Interpreter

The processing that is stored in the script is transferred to an Interpreter


as a file.
The following parameters must be specified by the UC4
administrator in the agent's INI file: ECPEXE=Interpreter and
ECPEXT=File Extension.

View
Standard

The display is set to normal view.

Minimized

The display is minimized.

Maximized

The display is maximized. The display is enlarged to full screen.

Job object

More information about the job and its sub-jobs is available when the
Window Job object is used. Yet another advantage are the improved
restart options. Note that the UC4 job does not end before all sub-Jobs
are ended. The job reports show whether a particular job used a
Windows Job object.

Default

Whether or not the Windows Job object is used depends on the


configuration settings that are made in the agent's INI file.

Yes

The UC4 job uses the Windows Job object.

No

The UC4 job does not use the Windows Job object.

Start parameter
Working directory

Working directory in which the job should run.

Command

Program that should be executed. The complete path can be specified


if needed. This entry field opens only when type "COM" is selected.

Logon as batch user

The job is executed in batch mode and is not visible to a logged-on


user.

430

Chapter3 Objects

Show job on the


desktop

The job is executed and can be seen by a user who is logged on. The
job can be displayed in Windows while it is being processed in an MS
DOS window.
Note that this function is only available if the Windows agent has
been started manually and not by using a ServiceManager. The job
is displayed at the same desktop as the agent.

z/OS
The following document explains the platform-specific settings for a z/OS job.

Description
All z/OS host attributes are stored in upper-case letters.
UC4 provides various settings for the efficient use of message classes.
Field/Control

Description

SYSOUT

Depending on your particular settings, the SYSOUT protocol consists


of the JES statistics and the job output.

Database

The SYSOUT protocol is managed by UC4. When the job has been
processed, the UC4 Automation Engine takes the SYSOUT protocol
which has been stored on the agent computer and stores it to the UC4
Database.

File

The SYSOUT protocol is managed by UC4. After job execution, the


SYSOUT protocol is available in the target system as a file.

Automation Engine

On error only

431

Only when the job aborts, the SYSOUT protocol will bestored in the
UC4 Database and/or as a file in the target system (only available
when "Database" and/or "File" has been selected).

Type
UC4

The job's JCL is stored in the "Pre-Process" and/or "Process" tab.

z/OS JCL

The job's JCL is available on z/OS.


When you select this option the input field File Name becomes active.
Select the dataset which contains the JCL here.
The job card is generated from the host attributes defined here. The
Pre-Process JCL is added before the first step. The script must be
empty.
Note that the agent ignores the first file line because it expects the
job card there.

JCL incl. z/OS job


card

The complete JCL including the job card is used from the dataset which
has been specified in the input field File Name .
No runtime options are available as the definitions made in the job card
apply.
When generating a job the JCL from the Pre-Process tab is added
before the first step. The script must be empty.

Report Selection

More details are provided in the documentation message classes.

With non-JES output

Complexity of job log


Allowed values: "Default value", "Yes" and "No"
"Default value" - The job-log complexity depends on the configuration
made in the agent's INI file (parameter completeJobout=).
"Yes" - The JES statistics and job output are stored in the job log.
"No" - Only the JES statistics (JESMSGLG, JESJCL and
JESYSMSG) are included.

Obtain the following


message
class/classes

Message classes which should be read and routed


Specify one or several message classes. Examples: "A", "ABC", "X1".
Any order is possible.
The following values are also allowed: "*DEFAULT" and "*ALL",
"*DEFAULT" - The message classes which should be read depend on
the configuration made in the agent's INI file (parameter
getMsgClass=). If this setting is used "*DEFAULT" must also be
specified in the field "Route to message class/classes".
"*ALL" - All classes are read

Report handling on
Host

More details are provided in the documentation about message


classes.

432

Chapter3 Objects

Purge

This deletes the job log in the JES spool.


Allowed values: "Default value", "Yes" and "No"
"Default value" - whether the job log is deleted depends on the
configuration made in the agent's INI file (parameter jobPurge=).
"Yes" - The job log is deleted after it has been read by the agent.
"No" - The job log remains in the JES spool.

Release

The job-log release for printing.


Allowed values: "Default value", "Yes" and "No"
"Default value" - whether the job log is deleted depends on the
configuration made in the agent's INI file (parameter relMsgClass=).
"Yes" - The job log is released when it has been read by the agent.
"No" - The job log is not released for printing.

Route message
class/classes to

Message classes that should be routed.


After it has been transferred to UC4, the job log can be routed to the
specified message classes (e.g. for an Output Management System).
Enter either one or the number of message classes specified in the
field "Obtain the following message class/classes". The order is
significant.
For example:
The following message classes are read: "ABC"
and routed: "DEF"
Class "A" is routed to class "D", "B" to "E" and "C" to "F".
For example:
The following message classes are read: "ABC"
and routed: "D"
Class "A", "B" and "C" are routed to class "D".
The following values can be used instead of message classes:
"*DEFAULT" and "*NO"
"*DEFAULT" - The message classes which should be routed depend
on the configuration made in the agent's INI file (parameter
routeMsgClass=). This setting must be specified if "*DEFAULT" has
also been specified in the field "Read the following message
class/classes".
"*NO" - No routing is made

Runtime options
Job name

The name of the job in the system.

Program name

The programmer's name - it identifies the job owner or its group


(optional). The name is recorded in the job's job card.
A maximum 20 characters is allowed.

Job class

The specification of the job class in which the job should run (optional).

Automation Engine

433

Account

Accounting information about the Job. A maximum of 40 characters is


allowed.

Priority

The specification of the Job's priority (optional). A value between "0"


and "15" can be specified.

MSGCLASS

The assignment of the job log's message class (optional).

MSGLEVEL

The trace option for the job log (optional). Possibly a numerical value for
command and message separated by a comma.
Allowed formats: "Command,Message", ",Message" or "Command"
Allowed values for outputting commands:
"0" - Outputs exclusively commands
"1" - All job commands, JES2 or JES3 control commands, procedure
commands and all IEF653I messages
"2" - All job commands (JCL) and the JES2 or JES3 control commands
Allowed values for outputting messages:
"0" - Only JCL messages. In the case of abortions also JES control
commands and operator messages. For SMS errors also the
corresponding messages.
"1" - All JCL, JES, operator and SMS messages.

Notify

The specification of a notification on z/OS. A maximum of 17


characters is allowed.

Job parameters

The specification of additional job parameters such as "TIME=1440".


Separate several job parameters by commas.

z/OS file name

The name of the dataset or member which contains:


* the JCL of the job (Option "JCL from z/OS") or
* the JCL and the job card of the job (Option "JCL incl. job card from
z/OS").
For example: SYSS.UC4.JCL.JOB1 or SYSS.UC4.JCLLIB
(UC4JOB1)
Jobs can also derive from the source administration system Librarian.
The following syntax applies: *LIBRARIAN(Dataset, Member).
A maximum of 225 characters is allowed.
Dataset name and member name must be put in single quotation
marks as otherwise, the agent will put the name of the user under
which it runs in front.
Example: IBMUSER.SYSS.UC4.JCL.JOB1
The agent ignores the first file line if type "z/OS JCL" is selected
because it expects the job card in it.

434

Chapter3 Objects

Return code

This setting is relevant if the job end should be monitored via SMF
Records. The return codes of the job STEPS are collected in this case.
The setting "Highest" uses the highest return code when the job ends.
"Latest" considers only the return code which has occurred last.
The UC4 administrator can specify whether SMF Records should
be used for monitoring job ends. The relevant parameter is
SMFJob= in the Event Monitor's INI file and the Variable UC_EX_
JOB_MD=UC4START in the agent's INI file.

Runtime tab
The Runtime tab is an object class-specific tab that is available in every executable object in
UC4. It can be used to specify parameters for a task's runtime behavior.

The Runtime tab is structured as follows:


l
l
l
l
l
l

Return code handling


Forecast setting
Evaluation of estimated runtime (runtime evaluation)
Monitoring of maximum runtime (runtime monitoring)
Monitoring of minimum runtime (runtime monitoring)
Reaction if the runtime is longer or shorter than defined (runtime monitoring)

Description

Field/Control
Definition for ENDED_
OK

Description

Automation Engine

Return code <=

435

Maximum return code for the normal end of a task.


A task ends normally (Status ENDED_OK) if its return code lies
below or is equal to the specified maximum return code.
To set the return code, you can also use the script element
:MODIFY_STATE.

Else execute

If the relevant task does not end with a return code that lies within
the ENDED_OK zone, you can define an alternative object that
should be processed.
Note that this object will not be processed if the task is
terminated by using the script statement :EXIT.

End status for Forecast

Selection list for the end status that this task should return if you
make a Forecast calculation.

Estimated runtime (ERT)


Current ERT =

Display of this task's next estimated runtime (ERT).


You can specify an estimated runtime here. This value then applies
until an ERT calculation has been made after the task's next run.
Format: "hours:minutes:seconds".

Use default (UC_


CLIENT_SETTINGS)

Selecting this option has the effect that the calculation method that
the UC4 administrator has specified in the UC4 Variable UC_
CLIENT_SETTINGS using the key ERT_METHOD will be used
for the estimated runtime.

Fixed value

Enter a fixed value as the estimated runtime.


Format: "seconds"

Dyn. method

Selection list for the dynamic method that is used to calculate the
estimated runtime from the actual runtime.
Possible selection: average, linear regression, maximal value

from the last ... runs

Number of past runs that are considered for ERT calculation.


Allowed values: 0 to 25.

+ ... %

Value in percent for an upward ERT correction.

Differences > ... % are


ignored

You can ignore possible huge deviations for the estimated runtime.

but do use ... runs at least

Number of past runs that should be considered regardless of


deviations. Allowed value: 0 to 25.

Show chart

Button for updating the estimated runtime according to the current


settings. A diagram is displayed in a separate window which
represents the last 25 ERT/RRT runs. An already open window will
be updated.

Reset values

Button for deleting the real and estimated runtimes.


After a security query, all stored runtimes will be cleared.

Maximum runtime
(MRT)

Upper limit (in percent) until which the real runtime should be used
to calculate the estimated runtime.

436

Chapter3 Objects

None

The maximum runtime is not monitored.

Fixed value

The maximum runtime is monitored.


The allowed time is entered as a fixed value in the format
"hours:minutes:seconds". An action (ELSE condition) must be
specified which reacts when maximum runtime is exceeded.

ERT

The maximum runtime is monitored.


The valid estimated runtime (ERT) at the time of the task's
activation is used as the maximum runtime. An action (ELSE
condition) must be specified which reacts when maximum runtime
is exceeded.

+ ... %

A correction in percent can be specified for ERT for the maximum


runtime. The determined value is added to the estimated runtime.

Curr. date + day(s)


Time

The maximum runtime is monitored.

TimeZone

Selection of a TimeZone object.

Define a number of days and a particular time until which the task
must be finished. The starting point for the date calculation is the
task's real date. An action (ELSE condition) must be specified
which reacts when maximum runtime has been exceeded.

Minimum runtime (SRT)


None

The minimum runtime is not monitored.

Fixed value

The minimum runtime is monitored.


The minimum runtime is used as a fixed value in the format
"hours:minutes:seconds". An action (ELSE condition) must be
specified which reacts if the runtime falls below the minimum
runtime.

ERT

The minimum runtime is monitored.


The valid estimated runtime at the time of the task's activation is
used as the minimum runtime. An action (ELSE condition) must be
specified which reacts when runtime falls below the minimum
runtime.

- ... %

A correction value in percent can be specified for ERT for the


minimum runtime. The determined value is subtracted from the
estimated runtime.

Else
Cancel / Quit

With this checkbox being activated, the task's end or cancelation


process is initiated if the runtime has been exceeded. Only
available if the maximum runtime is monitored.

Execute

Selecting this checkbox determines a task's execution. You can


directly select an executable object. This task will be activated if
the runtime is above or below the expected value. Only available
when runtime is monitored.

Automation Engine

437

Comments

A different definition of runtime monitoring can be used for tasks that run in a Workflow or are
activated using a Schedule object. You can define this in the properties of the affected objects
(Runtime tab). In doing so, you can implement specific requirements for runtime monitoring that
refer to the special context of Workflows or Schedules. The task settings which are defined in the
Workflow or Schedule override the settings that were made in the task itself.
By default, the settings for runtime monitoring as defined in the task also apply to the Workflow or
Schedule.

Step List for z/OS Jobs

There is a distinctive feature in the Runtime tab of z/OS Jobs. As in other tasks, you can specify a
maximum return code in order to determine whether a job is handled as having ended normally or
has aborted.Additionally, you can evaluate individual steps. These steps must be defined in the
step list.
Return codes are checked when a z/OS job ends:
l

l
l

The first check is made in order to verify whether a system or user abend has occurred. If so,
the job is regarded as aborted and the maximum return code is used (system comes before
the user).
If no step list has been defined, the job's return code is checked and used.
If a step list has been defined, the return codes of the individual steps are compared to the
step list. Only steps whose return codes are not equal to 0 are checked. Return code 0
always signals OK.
If a step is included in the step list, it depends on the definition whether the step is OK or not
OK. The first step that is not OK considers the job to be aborted. This step's return code is
used as the job's return code.
If a step is not included in the step list, its return code must be 0. Otherwise, the job is
considered as aborted.

438

Chapter3 Objects

You can open or close the step list by using the arrow button. A table accepts the step definitions.
Field/Control

Description

Step list
Step name

Name of the step.


The step name is not case-sensitive.
Allowed characters: A to Z, 0 to 9, $, # and @.
Step names can be specified by using wildcard characters (use "*" and
"?"). "*" stands for any character, "?" for exactly one.
If "*" is the first step entry in the step list, all other steps are irrelevant

Return Code

Return code that is assigned to the step.


Several return codes can be specified. Different return codes must be
separated by commas if they are listed (for example 1,2,9); a range of
return codes is specified with a hyphen (for example 10-15). These two
ways to define return codes can be used together.

OK

Indicator for checking steps.


The step's table column is empty (default):
Each match with a specified return code means that the step is not OK.
If there is no match the step is OK.
The table column selection has been made by clicking the mouse or
using a blank (flagged with X):
Each match with a specified return code means that this step is OK. If
there is no match, this step is not OK.

See also:

Automation Engine

439

Runtime Evaluation
Runtime Monitoring
Return codes for OA jobs
Variables & Prompts Tab
The Variables & Prompts tab is object type-specific and is available in almost every
executable object in UC4.
Object: Job
Object class: Executable object
Object type (short name): JOBS
This tab has two tasks:
l
l

It stores object variables.


It assigns PromptSet objects.

Object variables

Object variables include values that belong directly to the object and can be read in the Process
tabs. Variable names and values are determined in the table shown below.
In the Value column, you can also enter predefined variables. Do so using the Variables...
button in the object's toolbar.
The same rules apply for object variable names and for script variables. If you omit the preceding
"&", it is automatically added during the storing process and is available when you open the object
the next time.
Object variables and PromptSet variables can be inherited from the superordinate object. For
example, a Schedule's tasks can use the object variables of the Schedule object.
Field/Element

Description

440

Chapter3 Objects

Inherit from parent


All variables (default)

The object obtains all object variables and PromptSet variables of


the superordinate task.

Only defined variables

The object only obtains the object variables of the superordinate


task that have been defined in its Variables & Prompts tab.
PromptSet variables are only inherited if the PromptSet object
complies with these values and if the value that should be
overwritten has not been changed in the Variables & Prompts
tab.

No variables

The object obtains all object variables and PromptSet variables of


the superordinate task.

Note that inherited variables overwrite existing object variables if they have the same name. In
contrast, PromptSet variables are never overwritten.
The following procedure can be used if you want to overwrite PromptSet variables with the value
of a parent variable:
Open the task's Workflow or Schedule properties and switch to the Variables & Prompts tab.
Select the PromptSet area and use the Workflow's or Schedule's variable name as the value of
the relevant PromptSet element. If the particular PromptSet element is not a text field, click its
labeling.
PromptSet objects

In the Variables & Prompts tab, you can also select one or several PromptSet objects that should
be called during the activation process. In doing so, you can overwrite the default values of
PromptSet elements. These modifications do not affect the PromptSet object itself.
You can use the "+" and "-" buttons to add or remove PromptSet objects. Several PromptSet
objects are called from top to bottom. Use the arrow buttons if you want to change this order.

Automation Engine

441

To adjust the task's PromptSet values, you directly modify the PromptSet elements.
Click on the blue description that displays next to the elements when you also want to use variables
in the default value. The effect is that the PromptSet elements now appear as a gray text field that
has the name of the related PromptSet variable. In this specific text field, you can either manually
enter the predefined variables, or select them in a dialog that you call using the
button.
Clicking the blue description again deletes your previous entries and the PromptSet element
appears in its original view.
Predefined variables are already deleted when the PromptSet input mask is called. Note that the
values of predefined variables can change during the object's execution (for example, with UC4
Script) but the PromptSet variable still stores the old value.
An error occurs if the object should be stored and an element's value does not fulfill the
limitations of the PromptSet properties (min. value, max. value, max. length, value required etc).
The affected fields are highlighted in yellow.
If the values differ from the reference values, an error only occurs when the object starts and an
attempt is made to send the prompt. Ensure that the data type and other limitations (min. value,
max. value, format) of the reference variable are preserved.
Using the same variable names has the effect that the object variable values are overwritten by
the PromptSet variables. The value of the PromptSet object that has last been called is used if
selected PromptSet objects include identical variable names.
Graphical elements that are removed from the PromptSet object are also removed from the
Variables & Prompts tab. Modifications made in the PromptSet object's default values do not
affect the Variables & Prompts tab. The values of the PromptSet object are only available
when the PromptSet object is newly selected.

See also:
Object Variable
Designer tab
Rollback Tab
The Rollback tab is an object-specific tab that is available in every executable object that can be
included in a workflow.
The Rollback tab can be used to define actions that store the task (= Backup) and restore it (=
Rollback). These settings are only useful when the object runs in a workflow because you can only
start a rollback process within a workflow.
The backup and rollback functions are especially designed to undo erroneous installation and
deployment processes that are defined in the UC4 Deployment Manager but are processed by
using the Automation Engine.
Backup actions will always be processed before the object is processed, and rollback actions can
only be started for workflow tasks that have already ended. For more information, see the related
documentation.

442

Chapter3 Objects

Field/Element

Description

Enable Rollback

Use this to activate or deactivate the rollback settings.


When this option is deactivated, all the fields of this tab are
disabled.

Custom Rollback
Backup

Specify an executable object that is responsible for the


backup process.
If you specify a Backup object, it will always automatically
run before the task runs, regardless of how the object is
activated.
The actions and steps that must be defined in the Backup
object depend on the processes and actions of the related
task. Note that you must define them manually. For
example, if you use an object to update your database, it is
useful to include a database using the Backup object.

Automation Engine

Rollback

443

Specify an executable object that is responsible for the


rollback process.
The definition of the Rollback object depends on the
current object or the Backup object and must be made
manually. The Rollback object's basic task is to undo
modifications in the case of an error in order to ensure that
a previous working status will be restored. For example, if
the Backup object creates a database backup, the
Rollback object should be able to restore this backup.
The Rollback object will be processed when the task
starts in Rollback mode which is only possible in a
Workflow.

File Rollback

A file-based rollback is only available for Job and


FileTransfer objects that run on Windows or UNIX. In other
objects, the corresponding fields are disabled.
For a file-based rollback of Jobs, the system uses the
job's Agent, and for a file-base rollback of
FileTransfers, it uses the destination Agent.

444

Chapter3 Objects

Backup

Specify the path or file(s) that should be stored.


If you do not specify file names, the directory's complete
content will be backed up. To include subfolders, you must
select the option Include sub-directories .
You can use the wildcard characters * and ? in the file
name. * is a placeholder for any number of characters (0 n) and ? represents exactly one character. This allows you
to select files with a certain name and ending.
Examples for Windows:
C:\temp\test.txt
C:\temp\*.txt
C:\temp\ oder C:\temp\*
C:\temp\test??.*
The specified directory or files are automatically copied to
the following directory each time before the object runs:
<Backup folder>/<Client>/<Date>/<RunID>/
You define the backup folder in the INI files of the
agents (in the [VARIABLES] section) with the Agent
Variable UC_EX_PATH_BACKUP. By default, the
system uses "..\BACKUP" (Windows) or "../backup"
(Unix) as its backup folder (on the operating system of
the files and folders that should be backed up.
For example:
To be backed up:C:\uc4\source\*.txt
Backup folder:C:\uc4\backup
UNIX: The files are not directly stored in the directory
above but in a TAR archive that uses the RunID as its
name.
Before you run the object, make sure that there is
enough local disk space for the file backup and that the
OS user has all the required rights.
The backup folder's contents are deleted in regular
intervals. You can define how long the files should be
stored and when they should be checked with the
settings BACKUP_RETENTION_CHECK and
BACKUP_RETENTION_LIFETIME. These are
available in the UC4 Variable UC_HOSTCHAR*.
If the task starts in Rollback mode, the files are copied
from the backup folder to the directory that should be
backed up.

Automation Engine

Delete before restore

445

This field affects rollbacks.


If this option is active, the content of the original directory
that was used to create a backup will be deleted before the
backup folder is restored (see the description above of the
Backup field). This ensures that the destination directory
is empty before the files are copied from the backup folder
and avoids potential errors.
Subfolders will only be deleted if the option Include subdirectories is active.

Include subdirectories

Subdirectories and their contents will be included in


backup, deletion and restore processes.

Output ScanTab
The Output Scan tab determines the filters that are used to search the report of a task and/or
external file plus the reaction to the provided result.
Output Scan tab actions will be processed before the PostProcess tab actions.
Note that the actions will always be processed regardless of the task's end status.
Login info is required for the Output Scan even if the Windows or UNIX Agent's password check
is deactivated (UC_HOSTCHAR - ANONYMOUS_FT/JOB). Either the Login object that is set
in this tab in the section "Override host for FileScan" (if available) or the one that is specified in
the Attributes tab is used.

For example:

446

Chapter3 Objects

The above task refers to two Filter objects. FILTER.OUTPUT searches for the word ERROR in an
external file and FILTER.REPORT searches for a term that should be found in any case in the
report. The report is searched first because the list is processed from bottom to top.
The following table shows the possible effects in various situations:
The report does not The external file
include the expected includes the word
term
"ERROR"

Return code

Alarm object

9
5

ALARM.CALL

ALARM.CALL

Description

The Action area includes a table with filter definitions.


In this table, you can select one or several Filter objects whose conditions should be checked. You
also define here whether a certain conditions must apply or not and the return code that the affected
task should obtain. Optionally, you can also specify an object that should be executed.
Note that the entries will always be processed from bottom to top.
The first entry that applies is decisive for the task's return code. Successive conditions that apply
do not affect the return code. The optional object is executed in each line in which the condition
applies.
Note that filter definitions are checked at runtime. For example, a task obtains the status
FAULT_POST_PROCESSING if the Filter object you indicate searches a report that does not
exist in the task.
Field/Element

Description

Action
Output filter

The Filter object that includes the criteria that should be applied for
searching reports and/or external files.

True/False

You can select whether the criteria that are specified in the Filter object
must apply.
"true" - yes
"false" - no

Set return code

The return code for the task.

Status Text

Any text that is used for the task's remote status when the filter
definition applies.
The remote status of task appears in the corresponding column in
the Activity Window.

Execute

The object that should be processed in reaction to the result that is


supplied by the Filter object (optional).

Automation Engine

447

Field/Element

Description

Pass down to dynamic


children

This option is available in SAP jobs and RemoteTaskManager objects.


It determines whether Filter objects should also apply to child tasks.
"Yes" - The search takes place in the task and its children.
"No" - The search takes place only in the task.
"Only children" - The search takes place only in the child task.

Override host for


FileScan (optional)

By default, this task's agent and Login object are used to access an
external file that has been defined in the Filter object. You can change
one or both entries.
In FileTransfers, the destination agent is used by default.

Host

The name of an OS or a Java agent.

Login

The name of a Login object.

Form Tabs

Form tab (JMX)


The Form tabis object type-specific and is only found in JMX, PeopleSoft, SAP, or SQL Jobs.
Script elements can be easily entered through forms.
Object: Job
Object class: Executable object
Object type (short name): JOBS

448

Chapter3 Objects

The window is divided in two parts. The right half shows a tree structure listing all script elements
(JMX JCL) provided by UC4. In order to keep a clear overview, they are sorted according to topics
(e.g. operations). By double-clicking on one of the sub-categories, the appropriate script element is
added to the list in the left half of this tab.

Highlight a script element to call the appropriate form and it will be displayed instead of the tree
structure. Settings made here are automatically written to theProcess tab. The order of the script
elements automatically corresponds to the order shown in the list (compare Form and Process
tab). The order can be changed at any time simply by moving the arrow keys in the upper left half of
the window.

Other symbols for editing the list:


Symbol

Description
Inserts a new line at the current position.

Automation Engine

449

Duplicates the highlighted line.


Inserts a new line at the end.
Removes the current line.
Values can be added and selected via the available forms. Also, data is available from the MBean
Server if a connection has been established. For these cases, the button Browse (next to the
control field) can be used to obtain the existing information in table form (e.g. operations for JMX_
INVOKE).
The MBean Browser displays a maximum of 300 entries. The title line in the Browser window shows
the total number of available MBeans. If there are more than 300, UC4 recommends limiting the
number of displayed entries. Right-click the tree view in the MBean Browser and select the
command "Apply filter". Enter a filter for the MBean object names and confirm with OK, and this will
update the MBean Browser view.

The JMX agent must be selected in the Attributes tab. Otherwise, a connection will not be
established. The traffic light symbol shown on the bottom left edge of the Form tabindicates the
connection status.
Instead of specifying values in Form fields, you can also insert script variables.
See also:
About the JMX JCL

Form Tab (PeopleSoft)


The Form tabis object-type specific which is found only in PeopleSoft, JMX, SAP or SQL Jobs.
Script elements can easily be entered in it through forms.
Object: Job
Object class: Executable object
Object type (short name): JOBS

450

Chapter3 Objects

The window is divided into two parts. The right half shows a tree structure listing all script elements
(PeopleSoft JCL) provided by UC4. In order to keep a clear overview, they are listed according to
topics(e.g. monitor functions). By double-clicking on one of the sub-categories, the appropriate
script element is added to the list in the left half of this tab.

Now highlight a script element to call the appropriate form and it will be shown instead of the tree
structure. Settings made here are automatically written to theProcess tab. The order of the script

Automation Engine

451

elements corresponds to the list. It can be changed at any time simply by moving the arrow keys in
the upper left half of the window.

Further symbols for editing the list:


Symbol

Description
Insert a new line at the current position
Duplicates the highlighted line
Insert a new line at the end
The current line is removed.

In the available forms, you can enter and select values. Additionally, however, particular data is
available from PeopleSoft if a connection has been established to it. For this case, the
symbol
can be found next to the control field through which you can obtain the existing information in tableform (e.g. jobs for PS_RUN_JOB).
In order to establish a connection, a login window opens when you a PeopleSoft job is opened.
Enter the user and password, or decide to work offline.

Select the PeopleSoft agent in the Attributes tab to open this window. Connection data, which is
determined by the agent, are taken from the UC4 Variable "UC_EX_ERP_CONNECT". They are
also shown in the status bar of the tab. Next to it, the connection status is displayed with a trafficlight symbol.

452

Chapter3 Objects

Note that you can select in the Settings of the UserInterface whether to open PeopleSoft Jobs in
online or offline mode. If online mode is your choice, you can specify a Login object containing
the login data. It facilitates the automatic logon to PeopleSoft.
Instead of specifying values in Form fields, you can also insert script variables.
See also:
About UC4 JCL for Applications
About PeopleSoft JCL

Form Tab (SAP)


The Form tab is object-type specific and it is only available in SAP, JMX, PeopleSoft or SQL
Jobs. You can easily enter script elements in it through forms.
Object: Job
Object class: Executable object
Object type (short name): JOBS
No forms are available for certain functions such as R3_MODIFY_JOB or R3_SET_BDC_
DATA.

The window is divided in two parts. The right half shows a tree structure that lists all script elements
(SAP JCL) that are provided by UC4. To keep a clear overview, they are listed according to topics
(such as monitoring). Double-click on one of the sub-categories in order to display the appropriate
script element of the list in the left half of this tab.

Automation Engine

453

Now highlight the script element in order to call the corresponding form which will then display
instead of the tree structure. Settings that you specify here are automatically written to the Process
tab. The order of the script elements in the Process tab corresponds to the order of the list that
displays in the left half of the window. You can change it whenever you want by clicking on one of
the arrow keys in the upper left half of the window.

Further symbols for editing the list:


Symbol

Description
Inserts a new line at the current position.
Duplicates the highlighted line.
Inserts a new line at the end.
The current line is removed.

454

Chapter3 Objects

In the forms you can enter and select values. Additionally, you can use specific data from the SAP
system provided that there is a connection. In this case, the
symbol appears next to the
control field. You use it to obtain the existing information in table form (such as process chains for
BW_ACTIVATE_CHAIN). The following actions are also available:
Symbol

Description
Modification symbol.
Creation symbol.
Display symbol.
Calls the SAPCriteria Manager.
The "SAPCriteria Manager" privilege is required for this function.
Assumes SAP job steps.

Instead of specifying values in Form fields, you can also insert script variables.
You cannot set the checkboxes or radio buttons of the Form tab in a script variable. Entering a
script variable manually for these parameters in the Process tab has the effect that this value
will be overwritten when you store the Form tab.
The connection status is displayed with a traffic-light symbol in the status line.
You can change the client used for the SAP connection using the context menu in the status
line. SAP-system data (such as the variant list in R3_ACTIVATE_REPORT) will be retrieved for
this client.
A connection to the SAP system is established via the SAP agent. The user name, password and
client are taken from the Connection object for "ABAPBasis". The user requires the following
authorizations for using the SAP forms:
1) Authorization object S_RFC
ACTVT: 16
RFC_NAME: BDCH, RFC1, RSAB, RSPC_API, SALX, SDIFRUNTIME, SVAR_RFC, SXBP,
SXMI, SYST, BACV, SYSU
RFC_TYPE: FUGR
2) Authorization object S_XMI_PROD
EXTCOMPANY: *
EXTPRODUCT: UC4
INTERFACE: XAL, XBP, XMB
3) Authorization object S_TABU_DIS
ACTVT: 03
DICBERCLS: SPFL
This authorization is required for the form-switching operating modes, the function group RSAB for
Infopackages and RSPC_API for process-chain forms.

See also:

Automation Engine

455

About UC4 JCL for Applications


About SAP BW JCL
About SAP JCL

Form tab (SQL)


The Form tab is object type-specific and is only available in SQL, JMX, PeopleSoft and SAP
Jobs. You can easily enter SQL statements by using forms.
Object: Job
Object class: Executable object
Object type (short name): JOBS

The window is divided into two parts. The right half shows a tree structure that lists all script
elements (JMX JCL) that are provided by UC4, as well as SQL statements. Double-click one of the
sub-categories in order to add the appropriate script element to the list in the left half of this tab.
An entry form opens if a UC4 script element is concerned. The view is different if you opted for an
SQL statement. A convenient interface helps you to formulate commands. The middle area of the
tab shows a text field in which you can enter the statement. The displayed syntax provides input
assistance. The text field's font type and size depend on the settings that have been made in the
UserInterface. The right column shows the database structure with all the tables and their columns.
The primarykey and the foreign key are flagged with special icons. Table and column names
can be moved to the text field by using the drag and drop function.
Note that the database structure can only be displayed if an agent and a Login object with valid
login data have been selected in the job.
Each SQL statement must be entered in a separate line. The following illustration shows that
SQL_ON_ERROR and SELECT are dealt with in separate lines. Within a statement, you can
use several lines.

456

Chapter3 Objects

Entries that are made in the form or text field are automatically written to the Process tab. The order
of the SQL statements automatically corresponds to the order that is shown in the list (compare
Form and Process tab). The order can be changed at any time simply by moving the arrow keys in
the upper left half of the window.

By default, each statement ends with a semicolon. If this character is used within an SQL
statement, a different separator is defined and the job automatically inserts the statement SQL_
SET_STATEMENT_TERMINATOR in the script.
The Database Agent uses SQL statements exactly as specified in the Job. Statements are not
adjusted before they are passed on to the database. Therefore, UC4 strongly recommends only
using SQL statements the database supports. For example, the MSSQL Server command GO
is adjusted by the Query Analyzer before it is passed on to the database. No such adjustment
takes place within the Database Agent.

Automation Engine

457

Note for MS SQL Server Databases (especially in combination with transactions): SET
IMPLICIT_TRANSACTIONS is set to the default value ON. Further information is available in
the corresponding Microsoft documentation.
Further symbols for editing the list:
Symbol

Description
Inserts a new line at the current position.
Duplicates the highlighted line.
Inserts a new line at the end.
Removes the current line.

The traffic lights symbol shown at the bottom left edge of the Form tab indicates the database's
connection status.
Instead of specifying values in Form fields, you can also insert script variables.

See also:
About the SQL JCL
Script Tabs

Pre Process Tab


The Pre Process tab is an object type-specific tab which is only available in "Job" objects. It can
be used to store processing commands in UC4's scripting language.
Object: Job
Object class: Executable object
Object type (short name): JOBS

458

Chapter3 Objects

Description
The script is either processed when the job is activated or when it starts. The particular point in time
depends on the setting "Generate at runtime" which can be activated in the Attributes tab.
As opposed to the Process tab, the Pre-Process tab's processing commands are processed in the
header. Thus, statements can be used here which are executed before the job messenger becomes
involved.
The Pre Process and Process tabs are processed in one go. This means that it is possible to
set script variables in the Pre-Process tab which can also be accessed in the Process tab.
The script statement :INC_SCRIPT can be used to insert the Pre-Process tab's content
somewhere else.
Particularities for z/OS
In Pre Process, you can define all JCL commands (e.g. JCLLIB, JOBCAT, JOBLIB, OUTPUT etc.
) which must be defined after the job card but before the script's first step.
The Event Monitor only considers Pre-Process tab steps if this tab's first step has the same
name as the UC4 system. Otherwise, canceled Pre-Process job steps do not affect a UC4
Job's end status.
Example:
Name of the UC4 system: UC4PROD
Pre-Process tab:
//JOBLIB DD DISP=SHR,DSN=.....
// DD DISP=SHR,DSN=....
//UC4PROD EXEC PGM=modname
Process:

Automation Engine

459

//STEP01 EXEC PGM=IEFBR14


//STEP01 EXEC PGM=IEBGENER

See also:
Script Editor
About UC4 Scripts
SampleCollection

Process Tab
The Process tab is an object type-specific tab in which the processing commands of UC4's
scripting language are stored.
Object: Job
Object class: Executable object
Object type (short name): JOBS

Description
The script is either processed at job activation or start. This point in time depends on the Generateat-runtime setting which can be defined in the Attributes tab.
Processing commands that should be processed in the header (such as setting specific host
attributes) or executed before the job messenger starts, must be defined in the Pre Process tab.
Processing commands that should be processed after the job has ended are stored in the Post
Process tab. In doing so, you can influence the final end of this Job.

460

Chapter3 Objects

These lines correspond to the particular JCL (Job Control Language) of the target system and are
transferred to the target system exactly as they are. DATA lines can, for example, contain BS2000
commands or MS DOS commands for batch processing.
Particularities for Guardian/NSK
Special functions are provided for the automated handling of input requests.
Particularities for z/OS
The actual JCL is indicated here. Do NOT specify a job card (to be specified through the attributes)
or an end card.
Particularities for SAP
Because there is no JCL in SAP, UC4 supplies a SAP JCL which is interpreted by the SAP agent
and converted to processing statements for the target system.

See also:
Script Editor
About UC4 Scripts
SampleCollection

Post-Process Tab
The Post Process tab is an object type-specific tab that is only available in the objects
"FileTransfer", "Job" and "RemoteTaskManager". Processing commands can here be stored in
UC4's script language.
Object: Job
Object class: Executable object
Object type (short name): JOBS

Automation Engine

461

Description
The script commands stored in this tab are processed after the job has ended. Therefore, the job
must have run in the target system either completely (ended normally) or partially (canceled, lost
etc.).
A Job's end can still be influenced with post-script commands. The Job's return code and status
text (the text supplied by the job messenger in the Trailer) can be modified subsequently, for
example. The script statement :MODIFY_STATE - which was developed exclusively for being used
in the Post Process tab - defines the final ending of the Job.
Reports, for example, can be analyzed with PREP_PROCESS_REPORT. If an error is found, the
status ENDED_NOT_OK could be defined for a job although it has already ended normally from the
"technical" point of view and vice versa. Return code "0" is assigned to canceled Jobs because the
fact that the job has been canceled irrelevant for the further processing.
With the script statement :RSET, script variables can be transferred between the Process and
Post Process tabs. This script statement returns the value which has been assigned to the script
variable in the Process tab.
A Job's post script cannot contain JCL lines.
Additionally, the following script elements must not be used:
l
l
l

:PUT_ATT - Setting attributes for job generation is irrelevant.


:EXIT - Canceling script processing withreturn code > "0" is not allowed.
:STOP - Interrupting script processing is not allowed.

See also:
Script Editor
About UC4 Scripts
SampleCollection

Child Post-Process tab(SAP)


The Child Post Process tab is an object type-specific tab that is only found in SAP jobs and
RemoteTaskManagers.
Object: Job
Object class: Executable object
Object type (short form): JOBS

462

Chapter3 Objects

The script lines shown below are used for the children of the jobs. The following applies:
1. The script is processed for each individual child process.
2. The script is processed immediately after the child process finishes.

See also:
Script Editor
About UC4 Scripts
SampleCollection
Documentation Tabs
Documentation tabs are user-defined and client-specific tabs which can be assigned to all UC4
objects.

Automation Engine

463

All Documentation tabs that have been defined by the UC4 administrator in the UC4 variable
UC_OBJECT_DOCU are shown. Note that imported objects have their own documentation
tabs.
The Version Management tab displays the stored object versions if this function has been
activated.

Structured Documentation

Each of these tabs can also be displayed in structured form. Structured Documentation can be used
to split complex object information in well-arranged parts. Each documentation element can be used
to store texts, but also to define attributes.
You can also define links (e.g. to files, folders or to documents in the Intranet and Internet etc.) in
structured documentation. Files are then displayed with the associated program, folders are
opened, URLs call the standard browser etc. The particular actions depend on the installed
programs and the user's PC configuration.

464

Chapter3 Objects

New Documentation tabs initially only include the "Content" folder. This is your starting point for
creating a further structure. To create and edit this structure, you can use the following popup-menu
commands :
Command

Description

Add attribute

Creates a new attribute in the highlighted element.

Add node after

Inserts a new element after the highlighted element.

Add node before

Inserts a new element before the highlighted element.

Add node child

Creates a new element one level below the highlighted element.

Duplicate node

Duplicates the highlighted element and its attributes and contents.

Delete node

Deletes the highlighted element irrevocably.

You can create one or more attributes for each individual element. Basically, there are two different
types: text and enumeration. You can add one or more of these attributes to an element. Determine
the attribute's name and then select whether it is a text or an enumeration. In enumerations, you can
specify the entries that should be included.

Automation Engine

465

Names of elements and attributes should comply with the XML naming convention. Letters,
numbers and the characters "-", ".", "_" can be used. Keep the following rules in mind:
l
l
l
l

The first letter of a name must neither be a number, nor ".", nor "-".
The name must not include blanks.
Do not use colons as they are reserved characters.
Names must not begin with "XML", regardless if uppercase or lowercase letters are used.

Structured documentation can be read with specific script elements (XML_*).

Job - Execution

Object-Type specific Features

The script is processed in a specific way in the object type "Job". Depending on the JCL (Job
Control Language) and the script elements, an executable job is generated for the respective
target system and transmitted via file transfer.
The UC4 Script (if existing) and the JCL lines are processed and subsequently, the JCL is sent to
the target system. UC4 Script is never sent to the target system.

Database

The Database Agent regularly attempts to establish a connection to the database if its first
attempt was not successful. The UC4 administrator can define this interval in the INI-file
parameter connect=. The job remains in status "Active" during these attempts to establis a
connection.
The job also remains in status "Active" if the agent is not able to establish a connection because the
login data specified in the Login object is incorrect. It must be canceled manually either in the

466

Chapter3 Objects

Activity Window, using the script function CANCEL_UC_OBJECTor directly in the job by
monitoring the maximum runtime.
Keep in mind that it is not possible to end commands the agent has been processing in the
database at the moment job canceling is initiated. The JDBC interface does not provide this
function. Jobs can only be canceled between two commands. Therefore, the agent waits until a
command which is just being processed is finalized and cancels the job afterwards. Use the
functions of your database Server to cancel ongoing commands.

MPE

The UC4 administrator can specify the parameter login_check=yes in the MPE agent's INI file.
The password defined in the Login object is then checked. For reasons of security, UC4
recommends using this setting. Login_check=no only checks the User name.

UNIX

The user specified in the Login object also owns the job and report file. The UC4 administrator
can assign authorizations for both files using the agent's INI-file parameters JobFileMode= and
ReportMode=.
TThe UC4 administrator can specify the parameter login_check=yes in the UNIX agent's INI
file. The password defined in the Login object is then checked. For reasons of security, UC4
recommends using this setting. The setting Login_check=no only checks the User name.
Job - Include
When a job is processed, Includes are read and used to generate the executable job for the target
system. Depending on the job definition, activation data is retrieved, variable settings evaluated,
the attribute dialog facilitated, messages for the target system prepared, the log on/off in the
target system facilitated, the job report requested, etc.
UC4 supplies platform-specific Includes in client 0000. Within Header and Trailer Includes, user
Includes are called using the parameter "NOFOUND=IGNORE" in order to avoid errors if these
Includes do not exist.
In doing so, individual Includes can be created which are responsible for special tasks during the
various stages of job execution. These tasks are then included in UC4 processing.
For running Jobs, you require the right to run Job Includes when you use Job Includes.Note
when you use Job Includes (access method "X" for JOBI objects).
Job

Header Include

Trailer Include

User Includes

BS2000

HEADER.BS2000

TRAILER.BS2000

HEADER.BS2000.USER.PRE
HEADER.BS2000.USER.HEAD
HEADER.BS2000.USER.START
TRAILER.BS2000.USER.END
TRAILER.BS2000.USER.ABEND

GCOS8

HEADER.GCOS8

TRAILER.GCOS8

HEADER.GCOS8.USER.PRE
HEADER.GCOS8.USER.HEAD
TRAILER.GCOS8.USER.END

Automation Engine

467

JMX

HEADER.JMX

TRAILER.JMX

HEADER.JMX.USER.PRE
HEADER.JMX.USER.HEAD
HEADER.JMX.USER.START
TRAILER.JMX.USER.END

MPE

HEADER.MPE

TRAILER.MPE

HEADER.MPE.USER.PRE
HEADER.MPE.USER.HEAD

NSK

HEADER.NSK

TRAILER.NSK

HEADER.NSK.USER.PRE
HEADER.NSK.USER.HEAD
HEADER.NSK.USER.START
TRAILER.NSK.USER.END

Oracle
Application
s

HEADER.OA

TRAILER.OA

HEADER.OA.USER.PRE
HEADER.OA.USER.HEAD
HEADER.OA.USER.START
TRAILER.OA.USER.END

z/OS

HEADER.MVS

TRAILER.MVS

HEADER.MVS.USER.PRE
HEADER.MVS.USER.HEAD
HEADER.MVS.USER.START
TRAILER.MVS.USER.END

OS/400

HEADER.OS400

TRAILER.OS400

HEADER.OS400.USER.PRE
HEADER.OS400.USER.HEAD
TRAILER.OS400.USER.END

PeopleSoft

HEADER.PS

TRAILER.PS

HEADER.PS.USER.PRE
HEADER.PS.USER.HEAD
HEADER.PS.USER.START
TRAILER.PS.USER.END

RA

HEADER.CIT

TRAILER.CIT

HEADER.CIT.USER.PRE
HEADER.CIT.USER.HEAD
HEADER.CIT.USER.START
TRAILER.CIT.USER.END

SAP

HEADER.SAP

TRAILER.SAP

HEADER.SAP.USER.PRE
HEADER.SAP.USER.HEAD
HEADER.SAP.USER.START
TRAILER.SAP.USER.END

SAP BW

HEADER.SAPBW

TRAILER.SAPBW

HEADER.SAPBW.USER.PRE
HEADER.SAPBW.USER.HEAD
HEADER.SAPBW.USER.START
TRAILER.SAPBW.USER.END

Siebel

HEADER.SIEBEL

TRAILER.SIEBEL

HEADER.SIEBEL.USER.PRE
HEADER.SIEBEL.USER.HEAD
HEADER.SIEBEL.USER.START
TRAILER.SIEBEL.USER.END

SQL

HEADER.SQL

TRAILER.SQL

HEADER.SQL.USER.PRE
HEADER.SQL.USER.HEAD
HEADER.SQL.USER.START
TRAILER.SQL.USER.END

468

Chapter3 Objects

UNIX

HEADER.UNIX

TRAILER.UNIX

HEADER.UNIX.USER.PRE
HEADER.UNIX.USER.HEAD
HEADER.UNIX.USER.START
TRAILER.UNIX.USER.END

VMS

HEADER.VMS

TRAILER.VMS

HEADER.VMS.USER.PRE
HEADER.VMS.USER.HEAD
TRAILER.VMS.USER.END

Windows

HEADER.WINDO
WS

TRAILER.WINDO
WS

HEADER.WINDOWS.USER.PRE
HEADER.WINDOWS.USER.HEA
D
HEADER.WINDOWS.USER.STA
RT
TRAILER.WINDOWS.USER.END
TRAILER.WINDOWS.USER.ABE
ND

Due to the program logic, the Include object of the own client is used even if an object of the same
name is available in client 0000.
UC4 recommends using User Includes for special tasks. You can also modify the supplied Header
and Trailer Includes in client 0000 and store them in your own client. This only increases
maintenance work when the supplied Includes were changed with an updated version due to
programming reasons.
There are interdependencies between the individual Includes. Keep this in mind when modifying
Include objects.
If you do not intend to work with user-defined Include objects in general or on particular
platforms, the UC4 administrator can deactivate this function in the UC4 Variable UC_
SYSTEM_SETTINGS using the key "DISABLE_USER_HEADER". In this case, Include
objects are not called and this increases performance.

See also:
Agent's Job Messenger
Generated Jobs
Job generation is an individual stage of job execution which includes particular steps.
After a job has been started, it passes through different execution stages. In its first stage activation - it gets a run number (RunID) with which it can be clearly identified within the UC4
system. Now the job is also displayed in the Activity window of the UserInterface.
The second stage is the generation stage. The contents of the Pre Process and the Process tab are
executed and the final JCL (Job Control Language) is produced. Now you can view the generation
result with the command Open generated Job in the context menu of the Activity Window. A dialog
is called that contains three tabs. The first tab is write-protected.

Automation Engine

469

Attributes
The first tab contains the content of the attributes of the Job object. In it, the destination system and
all the necessary information for executing the object, such as the CodeTable and start type are
shown. The maximum number of simultaneously running tasks and the setting for which cases the
job must be deactivated after execution, can be viewed.
Host Attributes
The content of the middle tab depends on the type of the destination system. A UNIX job gets other
attributes than a SAP job for example. The tab, as well as the attributes of the Job object, is writeprotected and serves as information source.
JCL
The generated JCL is shown in the third tab which is not write-protected. Content modifications are
only considered for the current execution. Here, the job report contains the original JCL and the
modified one. An extra line indicates the user who has changed the content.
Note that the Dialog Generated job can even be called after the end of the job as long as it is in the
Activity window.
Job - Statistics/Report

Object-type-specific Features

External reports are only available in objects of type "Job". External reports, in the form of job
reports for Unix, SAP and Windows as well as SYSOUT and SYSLST in BS2000, will be
transferred to UC4 via a file transfer. Doing so requires the corresponding option being activated
in the Host Attributes tab.
Job reports can be called in the following ways:
Handling

470

Chapter3 Objects

Menu File Command


Last Job Report

In the Menu, File, you can select Last Job Report. A window will open
which displays the job report of the last job execution.

Click the right mouse


button on job in the
UC4 Explorer

Select Last Job Report from the menu.

Click the right mouse


button on the object in
the statistics window

Select Display Job Report in the context menu.


If no job report exists, an error message appears.

Note for the setting "Job report - Database" (seehost-attributes tab):


When a job has been executed on an agent, its corresponding job report will be stored on the
agent computer. As soon as the UC4 Automation Engine has written this data to the database,
the job report will automatically be deleted on the agent computer. If it cannot be deleted due to
an error, the deletion process will NOTbe repeated and an error message will be output.
Job Report - PeopleSoft
After job execution, PeopleSoft process data is available in the Job's report provided that the
checkbox "Database" has been activated in the Host Attributes tab.
By default, job reports contain:
l
l
l
l
l
l

Command line output of the PeopleSoft process


Status
Return code
Session ID
Start and end times
Messages

The process log from the PeopleSoft Process Scheduler Batch Server can also be displayed. This
requires particular prerequisites to be met. See: Installing the agent for PeopleSoft.

PeopleSoft Process Log File


The directory in which the log files are stored is specified in the configuration file psprcs.cfg of the
PeopleSoft Process Scheduler Batch Server (Section [Process Scheduler]). The agent retrieves the
name of the directory and log file from this configuration file. It transfers the log file to the UC4
Automation Engine which stores it in the UC4 Database.
Log/Output Directory=%PS_SERVDIR%\log_output
As an environment variable is used in the example shown above, this environment variable must
also be set in the agent. It contains the complete path specifications of the directory.
PS_SERVDIR="C:\Psoft\HR800\appserv\prcs\PSHR800"
The path of the application servers' configuration file must be indicated by the UC4 administrator.
Otherwise the agent could not access it. The format is: Server name=File.
[PSCONFIG]
PSNT=\\psserv01\appserv\prcs\PSHR800\psprcs.cfg
PSUNX=\\psserv01\appserv\prcs\PSHR800\psprcs.cfg

Automation Engine

471

An individual subdirectory is created in the retrieved directory of each PeopleSoft process. The
name of this subdirectory is specified as follows:
<PID>_<Process name>_<Process request>
<PID>

Process identification (e.g.: SQR).

<Process name>

Name of the process


Corresponds to the parameter PROCESSNAME= of PS_RUN_PROCESS

<Process request> Instance number of the process request.


Accordingly, the directory name for the report shown above is:
C:\Psoft\HR800\appserv\prcs\PSHR800\log_output\SQR_DDDAUDIT_100
The name of the log file is identical to the name of the subdirectory. The log file ends on ".log". The
file name for the log file with all the path specifications for the PeopleSoft process is as follows:
C:\Psoft\HR800\appserv\prcs\PSHR800\log_output\SQR_DDDAUDIT_100\SQR_DDDAUDIT_
100.log
Job Attributes

Job Attributes
The attributes for Job objects mainly refer to the input and setting options that are available in the
Header, Attributes and Runtime tabs.
Because there are Job objects for various platforms, some attributes refer to a particular job:
l
l
l
l
l
l
l
l
l
l
l
l
l
l
l

BS2000
Database
GCOS8
JMX
MPE
NSK
Oracle Applications
z/OS
OS/400
PeopleSoft
SAP
Siebel
UNIX
VMS
Windows

Attributes that are available for all jobs


Some attributes (such as the archive keys of objects) are available in all executable objects. Some
attributes do not depend on the platform for which the job is defined (such as the attributes for the
host, login information or the attribute dialog). The following table provides an overview of the
attributes that are available for all jobs:
Tab

Attribute

Description

Value

Access Via:

472

Chapter3 Objects

ARCHIVE_
KEY1

Archive key 1

User-defined,
limited to 60 characters

GET_ATT,
:PUT_ATT,
Change
Program,
via script
variable,
predefined
variable

ARCHIVE_
KEY2

Archive key 2

User-defined,
limited to 20 characters

GET_ATT,
:PUT_ATT,
Change
Program,
via script
variable,
predefined
variable

ATTR_DLG

Attribute Dialog

"Y" - The attribute dialog


displays.
"N" - The attribute dialog
does not display.

GET_ATT,
:PUT_ATT(PreProcess)

AUTO_DEACT

Deactivate
automatically when
finished.

"NEVER" - Never
deactivate automatically.
"ENDED_ERROR_
FREE" - In the case of
error-free processing,
deactivate automatically.
"RESTART_ERROR_
FREE" - In the case of an
error-free restart,
deactivate automatically.
"ALWAYS" - Always
deactivate automatically.

GET_ATT,
:PUT_ATT

AUTO_DEACT_
DELAY

Deactivate
automatically when
finished - alwaystime delay.

User-defined,
any value between "0" and
"99".

GET_ATT,
:PUT_ATT

AUTO_DEACT_
ERROR_FREE

Deactivate
automatically when
finished - after an
error-free restart error-free.

Task status,
limited to 20 characters

GET_ATT,
:PUT_ATT

CODE

Code

The name of a CodeTable,


limited to 200 characters.

GET_ATT,
:PUT_ATT (PreProcess,
Process),
predefined
variable

Automation Engine

473

CSCRIPT

The string in the


child's PostProcess tab of the
job should be
changed.

Change Program

DATE_
CREATED

Created on

Time stamp in the format


"YYYY-MM-DD
HH:MM:SS"
If not available: "0000-0000 00:00:00"

GET_ATT

DATE_
MODIFIED

Modified on

Time stamp in the format


"YYYY-MM-DD
HH:MM:SS"
If not available: "0000-0000 00:00:00"

GET_ATT

DCMODUS

Mode UserInterface

"Y" - the UserInterface is


active.
"N" - The UserInterface is
not active.

GET_ATT

FILENAME_JOB

File name

The name of the file


(without path) that the
agent creates for the job
that should run.

GET_ATT,
predefined
variable

FILENAME_
SYSLST

File name

The name of the file


(without path) that the
agent creates for the
system output (SYSLST).

GET_ATT,
predefined
variable

FILENAME_
SYSOUT

File name

The name of the file


(without path) that the
agent creates for the
system output (report).

GET_ATT,
predefined
variable

FSC_HOST

Override host for


FileScan (optional) Host

The name of an agent,


limited to 32 characters.

GET_ATT,
:PUT_ATT (PreProcess,
Process),
Change
Program,
predefined
variable

FSC_LOGIN

Override host for


FileScan (optional) Login

The name of a Login


object,
limited to 200 characters

GET_ATT,
:PUT_ATT (PreProcess,
Process),
Change
Program,
predefined
variable

474

Chapter3 Objects

GEN_AT_
RUNTIME

Generate at runtime

"Y" - Generation at
runtime.
"N" - Generation at
activation time.

GET_ATT

GROUP

Group

The name of a group,


limited to 200 characters.
" " - For an immediate start.

GET_ATT,
:PUT_ATT (PreProcess,
Process),
Change
Program,
predefined
variable

HOST

Host

The name of an agent,


limited to 32 characters.

GET_ATT,
:PUT_ATT (PreProcess),
Change
Program,
predefined
variable

INT_ACCOUNT,
INT_ACC, K

Int. Account

User-defined,
limited to 16 characters.

GET_ATT,
:PUT_ATT,
Change
Program,
via script
variable,
predefined
variable

LAST_DATE

Last used on

The time stamp in the


format "YYYY-MM-DD
HH:MM:SS"
If not available: "0000-0000 00:00:00"

GET_ATT,
predefined
variable

LAST_USER

Last used by

The name of the User


object,
limited to 200 characters.

GET_ATT,
predefined
variable

LOGIN

Login

The name of a Login


object,
limited to 200 characters.

GET_ATT,
:PUT_ATT (PreProcess,
Process),
Change
Program,
predefined
variable

LOGIN_INFO

Login info

The Login object's entire


Login information.

GET_ATT,
predefined
variable

Automation Engine

475

MAX_JCL_
LINES

The maximum
number of job lines
that should be
generated.

User-defined,
usually jobs with a
maximum of 1000 job lines
are generated. This value
can be increased for large
jobs.

GET_ATT,
:PUT_ATT (PreProcess,
Process)

MAX_
PARALLEL_
ELSE

Parallel running
Tasks - Else

"WAIT" - Job waits until


processing is possible
"ABEND" - Job is
disrupted

GET_ATT,
:PUT_ATT (PreProcess,
Process)

MAX_
PARALLEL_
TASKS

Parallel running
Tasks - Max.

User-defined,
any value between "0" and
"99999".

GET_ATT,
:PUT_ATT (PreProcess,
Process),
predefined
variable

MAX_
RETCODE

ENDED_OK until
return code

User-defined,
limited to 11 characters.

GET_ATT,
:PUT_ATT (PreProcess,
Process)

MODIFY_
COUNT

Modified

The number of object


modifications.

GET_ATT

OBJECT_NAME

Object name

User-defined,
limited to 200 characters.

Change Program

OBJECT_TITLE

Title

User-defined,
limited to 255 characters.

GET_ATT,
:PUT_ATT (PreProcess,
Process),
predefined
variable

476

Chapter3 Objects

OO

Job report

"J" - Saves the job report in


UC4.
"F" - Saves the job report in
the target system.
"S" - Saves the job report
on error only.
"N" - Does not save the job
report.

GET_ATT,
:PUT_ATT (PreProcess,
Process. For
BS2000: only
Pre-Process)

The following
combinations are possible:
"JF" - Saves the job report
in UC4 and in the target
system.
"JSF" - Saves the job
report in the case of an
error in UC4 and in the
target system.
"JS" - Saves the job report
in the case of an error in
UC4.
"SF" - Saves the job report
in the case of an error in
the target system.
OSCRIPT

A string in the PostProcess tab of the


job should be
changed

Change Program

PPF_EXECUTE

Action - Execute

The name of an executable


object,
limited to 200 characters.

Change Program

PPF_FILTER

Action - Output filter

The name of a Filter object,


limited to 200 characters.

Change Program

PPF_
INHERITANCE

Inherit to dynamic
child tasks

"Y" - Yes
"N" - No
"C" - Children only

Change Program

PSCRIPT

The string in the


Pre-Process tab of
the job should be
changed.

QUEUE

Queue

Change Program

The name of a Queue


object,
limited to 200 characters.

GET_ATT,
:PUT_ATT
Change
Program,
predefined
variable

Automation Engine

RESOURCE_
CONSUMPTION

Consumption
(Resources)

SCRIPT

The string in the


Process tab of the
job should be
changed.

SYNC_OBJECT

Assigned Sync
object

The name of a Sync


object,
a maximum of 20
characters must not be
exceeded.

Change Program

TIMEZONE

TimeZone

User-defined
a maximum of 8 characters
must not be exceeded.

GET_ATT,
:PUT_ATT,
predefined
variable

UC4_PRIORITY

UC4 Priority

User-defined,
any value between "0" and
"255".

GET_ATT,
:PUT_ATT,
predefined
variable

USAGE_
COUNT

Last used

Number of object usages

GET_ATT,
predefined
variable

USER_
CREATED

Created by

The name of the User


object,
limited to 200 characters.

GET_ATT,
predefined
variable

USER_
MODIFIED

Changed by

The name of the User


object,
limited to 200 characters.

GET_ATT,
predefined
variable

USERID

Login info

The User ID from the Login


object's login information.

GET_ATT,
predefined
variable

See also:
Attributes
UC4.DB Change
:PUT_ATT statement
GET_ATT function

User-defined,
any value between "0" and
"99999".

477

GET_ATT,
:PUT_ATT (PreProcess,
Process),
Change
Program,
predefined
variable
Change Program

478

Chapter3 Objects

BS2000
The following overview includes the attributes of a BS2000 Job object and describes their
functions, allowed values and ways of modification.

Attribute

Description

Value

Accesses

ACCOUNT,
BS2_ACC,
BS2_
ACCOUNT,
ACC, A

Login info

Account from Login info of the


Login object

GET_
ATT,
predefined
variable

ENTER_
PARAMS,
ENTER_PAR,
EP

Runtime options - Enter


parameter

User-defined,
maximum 255 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

EXPRESS, E

Runtime options - Express

"Y" - Job starts immediately,


regardless of batch limit
"N" - Job does not start
immediately

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

JOB_CLASS,
JC

Runtime options - Job class

User-defined,
maximum 8 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
predefined
variable

JOB_NAME, JN

Runtime options - Order name

User-defined,
maximum 8 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
predefined
variable

Automation Engine

479

OL

Job report SYSLST

"J" - save log in UC4


"N" - do not save a log in UC4
"F" - save log in the target
system
"JF" - save log in the target
system and in UC4

GET_
ATT,
:PUT_
ATT (PreProcess)

PRIORITY, P

Runtime options - Priority

User-defined,
Value between "0" and "255"

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
predefined
variable

SYSLST_DB

SYSLST - Database

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreScript)

SYSLST_
ERROR_ONLY

SYSLST - On error only

"Y" - SYSLST log only saved if


error occurs
"N" - SYSLST log always
saved

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

SYSLST_FILE

SYSLST - File

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess)

SYSOUT_DB

SYSOUT - Database

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess)

SYSOUT_
ERROR_ONLY

SYSOUT - On error only

"Y" - SYSOUT log only saved


if error occurs
"N" - SYSOUT log always
saved

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

SYSOUT_FILE

SYSOUT - File

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess)

480

Chapter3 Objects

TIME, T

Max. CPU time

User-defined,
When this attribute is read, a
16-figure value with leading
zeros is returned.

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

See also:
Job
Host Attributes Tab
Attributes
:PUT_ATT statement
GET_ATT function
UC4.DB Change

GCOS8
The following overview includes the attributes of a GCOS8 job-object and describes their
functions, allowed values and ways of modification.

Attribute

Description

Value

Accesses

GCOS8_IDENT

Start parameter - IDENT

User-defined,
maximum 63 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
predefined
variable

GCOS8_
JCLJOB

Start parameter - Include Job

User-defined,
maximum 255 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

Automation Engine

481

GCOS8_
SNUMB

Start parameter - SNUMB

User-defined,
maximum 5 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
predefined
variable

GCOS8_
URGENCY

Start parameter - Urgency

User-defined,
Value between "0" and "63"

GET_
ATT,
:PUT_
ATT,
Change
Program

JOBREPORT_
DB

Job report - Database

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
ERROR_ONLY

Job report - On error only

"Y" - Job report only saved if


error occurs
"N" - Job report always saved

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
FILE

Job report - File

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

See also:
Job
Host Attributes Tab
Attributes
:PUT_ATT statement
GET_ATT function
UC4.DB Change

JMX
The following overview includes the attributes of a JMX job and describes their functions,
allowed values and ways of modification.

482

Chapter3 Objects

Attribute

Description

Value

Accesses

AGENT_ID

MBean Server - Agent ID

User-defined,
maximum 20 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

INITIAL_
CONTEXT_
FACTORY

MBean Server - Initial Context


Factory

User-defined,
maximum 100 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

JOBREPORT_
DB

Job report - Database

"Y" - yes, "N" - no

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
ERROR_ONLY

Job report - On error only

"Y" - Job report only saved if


error occurs
"N" - Job report always saved

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
FILE

Job report - File

"Y" - yes, "N" - no

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

Automation Engine

SERVER_URL

MBean Server - Server URL

User-defined,
maximum 100 characters

483

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

See also:
Job
Host Attributes Tab
Attributes
:PUT_ATT Statement
GET_ATT Function
UC4.DB Change

MPE
The following overview includes the attributes of a MPE Job object and describes their functions,
allowed values and ways of modification.

Attribute

Description

Value

Accesses

ACCOUNT,
BS2_ACC,
BS2_
ACCOUNT,
ACC, A

Login info

Account from the Login


object's login info

GET_
ATT,
predefined
variable

GROUPNAME,
MPE_
GROUPNAME

Login info

Logon group from the Login


object's login info

GET_
ATT,
Change
Program,
predefined
variable

484

Chapter3 Objects

JOB_NAME, JN

Runtime options - Order name

User-defined,
maximum 8 characters
The first character must be a
letter.

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

JOBREPORT_
DB

Job report - Database

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
ERROR_ONLY

Job report - On error only

"Y" - Job report is only stored


if an error occurs
"N" - Job report always stored

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
FILE

Job report - File

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

MPE_HIPRI

Runtime options - HIPRI

"ON" - HIPRI used


"OFF" - HIPRI not used

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program

MPE_
INPUTPRIO

Runtime options - Input priority

User-defined,
value between "1" and "13"

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
predefined
variable

Automation Engine

485

MPE_OTHER

Runtime options - Other

User-defined,
maximum 255 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable

MPE_QUEUE

Runtime options - Queue

User-defined,
maximum 8 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program

The queue set with this


attribute must be defined by
the UC4 administrator with the
UC4 Variable UC_MPE_
QUEUE. This is checked with
the statement:PUT_ATT.

See also:
Job
Host Attributes Tab
Attributes
:PUT_ATT statement
GET_ATT function
UC4.DB Change

NSK
The following overview includes the attributes of a NSK Job object and describes their functions,
allowed values and ways of modification.

Attribute

Description

Value

Accesses

CPU

Start parameter - CPU

Value between "-1" and "15"

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

GROUPNAME,
MPE_
GROUPNAME

Login info

Logon group from Login info of


the Login object

GET_
ATT,
Change
Program,
predefined
variable

486

Chapter3 Objects

JOBREPORT_
DB

Job report - Database

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
ERROR_ONLY

Job report - On error only

"Y" - Job report only saved if


error occurs
"N" - Job report always saved

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
FILE

Job report - File

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

PRIORITY, P

Start parameter - Priority

User-defined,
value between "0" and "199"

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
predefined
variable

HOME_
TERMINAL

Start parameter - Virtual


Terminal

User-defined, max. 26
alphanumeric characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

NSK_JOB_
TYPE

Job type

"0" - TACL
"1" - NBEXEC
"2" - OSS

GET_
ATT,
Change
Program,
predefined
variable

See also:
Job
Host Attributes Tab

Automation Engine

487

Attributes
:PUT_ATT statement
GET_ATT function
UC4.DB Change

Oracle Applications
The following overview includes the attributes of an Oracle Applications Job object and
describes their functions, allowed values and ways of modification.

Attribute

Description

Value

Accesses

JOBREPORT_
DB

Job report - Database

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
ERROR_ONLY

Job report - On error only

"Y" - Job report only saved if


error occurs
"N" - Job report always saved

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
FILE

Job report - File

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

OA_APPL_
NAME

Responsibility - App. Short


Name

User-defined,
maximum 50 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
via script
variable,
predefined
variable

OA_RESP_
NAME

Responsibility - Key

User-defined,
maximum 100 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
via script
variable,
predefined
variable

488

Chapter3 Objects

See also:
Job
Host Attributes Tab
Attributes
:PUT_ATT statement
GET_ATT function
UC4.DB Change

z/OS
The following overview includes the attributes of an z/OS Job object and describes their
functions, allowed values and ways of modification.

Attribute

Description

Value

Accesses

JCL_SOURCE

Runtime options - z/OS file


name

Maximum 64 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

JOB_CLASS, JC

Runtime options - Job class

User-defined,
maximum 1 character

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
predefined
variable

JOB_NAME, JN

Runtime options - Job name

User-defined,
maximum 8 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

Automation Engine

489

MVS_ACCOUNT

Runtime options - Account

User-defined,
maximum 40 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
via script
variable,
predefined
variable

MVS_
COMPLETEJOBOUT

Report Selection - With


additional output

" " - INI-file value


"Y" - Yes
"N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program

MVS_DETERMINE_
RETCODE

Runtime options - Return


code

"H" - Highest
"L" - Latest

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program

MVS_
GETMSGCLASSES

Report Selection - Obtain


the following message
class/classes

"*DEFAULT" - INI-file value


"*ALL" - All message
classes
"A" to "Z" and "0" to "9" Specify one or several
message classes

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
predefined
variable

MVS_JOB_PARAMS

Runtime options - Job


Parameters

User-defined,
maximum 255 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

490

Chapter3 Objects

MVS_JOBPURGE

Report handling on Host Purge

" " - INI-file value


"Y" - Yes
"N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program

MVS_JOBTYPE

Type

"UC4" - UC4
"JCL1" - JCL from z/OS
"JCL2" - JCL incl. Job card
from z/OS

GET_
ATT,
predefined
variable

MVS_MSG_LEVEL

Runtime options - Msg level

User-defined,
maximum 3 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
predefined
variable

MVS_MSGCLASS

Runtime options - Msg


class

User-defined,
maximum 1 character

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
predefined
variable

MVS_NOTIFY

Runtime options - Notify

User-defined,
maximum 16 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

Automation Engine

491

MVS_PROG_NAME

Runtime options - Prog.


name

User-defined,
maximum 20 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

MVS_
RELMSGCLASS

Report handling on Host Release

" " - INI-file value


"Y" - Yes
"N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
predefined
variable

MVS_
ROUTEMSGCLASS

Report handling on Host Route message


class/classes to

"*DEFAULT" - INI-file value


"*NO" - No routing
"A" to "Z" and "0" to "9" Specify one or several
message classes

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
predefined
variable

PRIORITY, P

Runtime options - Priority

User-defined,
value between "0" and "15"

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
predefined
variable

JOBREPORT_DB

Job report - Database

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

492

Chapter3 Objects

JOBREPORT_
ERROR_ONLY

Job report - On error only

"Y" - SYSOUT log only


saved if error occurs
"N" - SYSOUT log always
saved

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_FILE

Job report - File

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

See also:
Job
Host Attributes Tab
Attributes
:PUT_ATT statement
GET_ATT function
UC4.DB Change

OS/400
The following overview includes the attributes of an OS/400 Job object and describes their
functions, allowed values and ways of modification.

Attribute

Description

Value

Accesses

JOB_NAME, JN

Runtime options - Job name

User-defined,
maximum 10 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

JOBREPORT_
DB

Job report - Database

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

Automation Engine

493

JOBREPORT_
ERROR_ONLY

Job report - On error only

"Y" - Job reports only saved if


error occurs
"N" - Job report always saved

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
FILE

Job report - File

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

OS400_JOBD

Runtime options - Job


description

User-defined,
maximum 21 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

OS400_
JOBLOG

Spool

"QPJOBLOG" = Only spool


contents from QPJOBLOG
are saved.
"*ALL" = Entire spool contents
of the Job are saved.

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
predefined
variable

OS400_JOBQ

Runtime options - Job queue

User-defined,
maximum 21 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

494

Chapter3 Objects

OS400_
JOBTYPE

Type

"CMD" = Job with OS/400


commands.
"CL" = Job with ILE CL script.
"REXX" = Job with REXX
script.

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
predefined
variable

OS400_
RTGDTA

Runtime options - Rooting


data

User-defined,
maximum 255 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

PRIORITY, P

Runtime options - Priority

User-defined,
Value between "0" and "99"

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
predefined
variable

See also:
Job
Host Attributes Tab
Attributes
:PUT_ATT statement
GET_ATT function
UC4.DB Change

PeopleSoft
The following overview includes the attributes of a PeopleSoft Job object and describes their
functions, allowed values and ways of modification.

Attribute

Description

Value

Accesses

Automation Engine

495

JOBREPORT_
DB

Job report - Database

"Y" - Yes, "N" - No

GET_ATT
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
ERROR_ONLY

Job report - On error only

"Y" - Job report only saved if


error occurs
"N" - Job report always saved

GET_ATT
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
FILE

Job report - File

"Y" - Yes, "N" - No

GET_ATT
:PUT_
ATT (PreProcess,
Process)

PS_JOB_
DELETE

Runtime options - Delete


process request after
execution

"0" - Do not delete process


request
"1" - Delete process request

GET_ATT
:PUT_
ATT (PreProcess,
Process)

See also:
Job
Host Attributes Tab
Attributes
:PUT_ATT statement
GET_ATT function
UC4.DB Change

SAP
The following overview includes the attributes of an SAP Job object and describes their
functions, allowed values and ways of modification.

Attribute

Description

Value

Accesses

JOB_CLASS, JC

Start parameter - Job class

Job priority in SAP


"A", "B" or "C"

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
predefined
variable

496

Chapter3 Objects

JOB_NAME, JN

Start parameter - Job name

User-defined,
maximum 32 character

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

JOBREPORT_
DB

Job report - Database

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
ERROR_ONLY

Job report - On error only

"Y" - Job reports only saved if


error occurs
"N" - Job report always saved

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
FILE

Job report - File

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

SAP_
ADDRESSTYPE

Spoollist recipient - Address


Type

"B" - SAP User


"C" - Shared distribution list
"D" - X.500 address
"F" - Fax number
"G" - Organization object/ID
"H" - Organizational
unit/position
"J" - SAP object
"L" - Telex number
"O" - SAPoffice user
"P" - Private distribution list
"R" - SAP user in another SAP
system
"U" - Internet address
"X" - X.400 address

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
predefined
variable

Automation Engine

497

SAP_
AGENTLOG

Optional reports - Agent log

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program

SAP_APPLLOG

Optional reports - Application


logs

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program

SAP_
BLINDCOPY

Spoollist recipient - Blind


copy

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program

SAP_CLIENT

Login info

Client from Login info of the


Login object

GET_
ATT,
Change
Program,
predefined
variable

SAP_COPY

Spoollist recipient - Copy

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program

SAP_DELIVER

Spoollist recipient - Report


send status

" " - Default


"A" - Always
"E" - Error case
"N" - Never

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
predefined
variable

498

Chapter3 Objects

SAP_DST_
SYSTEM

Start parameter - Target


system

User-defined,
maximum 32 character

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

SAP_EXPRESS

Spoollist recipient - Express

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program

SAP_JOB_
DELETE

Start parameter - Delete job


after completion in CCMS

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

SAP_JOB_DEL_
NOT_ON_
ERROR

Start parameter - but not on


error

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT,
Change
Program

SAP_JOB_TYPE

Job type

"0" - ABAP Engine/Business


Intelligence
"1" - Exchange Infrastructure

GET_
ATT,
predefined
variable

SAP_
JSTATISTICS

Optional reports - Statistics of


Java Scheduler jobs

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT,
Change
Program

Automation Engine

499

SAP_LANG

Start parameter - Language

User-defined,
maximum 2 character

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
predefined
variable

SAP_
NOFORWARD

Spoollist recipient - No
forwarding

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program

SAP_NOPRINT

Spoollist recipient - No
printing

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program

SAP_
RECIPIENT

Spoollist recipient - Recipient

User-defined,
maximum 241 character

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

SAP_
SPOOLDIR

Optional reports - Spool


directory

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program

500

Chapter3 Objects

SAP_
STARTMODE

Start parameter - start mode

"ASAP" - As soon as possible


"IMMEDIATE" - Immediately

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
predefined
variable

SAP_
STATISTICS

Optional reports - Statistics of


ABAP jobs

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT,
Change
Program

SAP_
STATUSBYMAIL

Spoollist recipient - Report


status by mail

" " - Default


"A" - Always
"E" - Error case
"N" - Never

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
predefined
variable

SAP_STEPLIST

Optional reports - Step lists

"Y" - ja, "N" - nein

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
ChangeProgramm

See also:
Job
Host Attributes Tab
Attributes
:PUT_ATT statement
GET_ATT function
UC4.DB Change

Siebel
The following overview includes the attributes of a/an Siebel Job object and describes their
functions, allowed values and ways of modification.

Automation Engine

501

Attribute

Description

Value

Accesses

COMPRESSION

Start parameter Compression

"1" - Yes, "0" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program

ENCRYPTION

Start parameter - Encryption

"1" - Yes, "0" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program

ENTERPRISE_
SERVER

Start parameter - Enterprise


Server

User-defined,
maximum 255 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

GATEWAY_
SERVER

Start parameter - Gateway


Server

User-defined,
maximum 255 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

502

Chapter3 Objects

LANGUAGE

Start parameter - Language

User-defined,
maximum 3 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
predefined
variable

SIEBEL_
SERVERS

Start parameter - Siebel


Servers

User-defined,
maximum 255 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

JOBREPORT_
DB

Job report - Database

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
ERROR_ONLY

Job report - On error only

"Y" - Job report only saved if


error occurs
"N" - Job report always saved

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
FILE

Job report - File

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

See also:
Job
Host Attributes Tab
Attributes
:PUT_ATT statement
GET_ATT function
UC4.DB Change

Automation Engine

503

SQL
The following overview includes the attributes of a SQL Job object and describes their functions,
allowed values and ways of modification.

Attribute

Description

Value

Accesses

DATABASE_
NAME

Connection - database

User-defined,
maximum 100 characters

GET_ATT
:PUT_
ATT (PreProcess,
Process)
Change
Program,
predefined
variable

DATA_
SOURCE

Connection - file name

User-defined,
maximum 255 characters

GET_ATT
:PUT_
ATT (PreProcess,
Process)
Change
Program,
predefined
variable

JOBREPORT_
DB

Job report - database

"Y" - yes, "N" - no

GET_ATT
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
ERROR_ONLY

Job report - on error only

"Y" - Job report only saved if


error occurs
"N" - Job report always saved

GET_ATT
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
FILE

Job report - file

"Y" - yes, "N" - no

GET_ATT
:PUT_
ATT (PreProcess,
Process)

SERVER_
NAME

Connection - server

User-defined,
maximum 100 characters

GET_ATT
:PUT_
ATT (PreProcess,
Process)
Change
Program,
predefined
variable

504

Chapter3 Objects

SQL_
AGENTLOG

Optional reports - Agent log

"Y" - yes, "N" - no

GET_ATT
:PUT_
ATT (PreProcess,
Process)

SQL_
CAPTIONS

Settings - show headlines in


tables

"Y" - yes, "N" - no

GET_ATT
:PUT_
ATT (PreProcess,
Process)

SQL_
COLUMN_
SEPERATOR

Settings - column separator

User-defined,
maximum 1 character

GET_ATT
:PUT_
ATT (PreProcess,
Process)

SQL_MAX_
CHARACTERS

Settings - max. number of


characters in a table column

User-defined,
value between "1" and "9999"

GET_ATT
:PUT_
ATT (PreProcess,
Process)

SQL_MAX_
ROWS

Settings - max. number of


lines in tables

User-defined,
value between "1" and "9999"

GET_ATT
:PUT_
ATT (PreProcess,
Process)

SQL_
REMOVE_
CRLF

Settings - remove line breaks

"Y" - yes, "N" - no

GET_ATT
:PUT_
ATT (PreProcess,
Process)

SQL_SHOW_
NULL

Settings - show NULL as


empty string

"Y" - yes, "N" - no

GET_ATT
:PUT_
ATT (PreProcess,
Process)

SQL_SUBST_
CHARACTER

Settings - substitute character

User-defined,
maximum 1 character

GET_ATT
:PUT_
ATT (PreProcess,
Process)

Keep in mind that :PUT_ATTmay be used to set a database plus server (DATABASE_NAME,
SERVER_NAME) or a Microsoft Access database. It is not possible to assign values to all
three attributes because the access to the database would not be unique.

See also:
Job
Host Attributes Tab
Attributes
:PUT_ATT Statement

Automation Engine

505

GET_ATT Function
UC4.DB Change

UNIX
The following overview includes the attributes of a UNIX Job object and describes their
functions, allowed values and ways of modification.

Attribute

Description

Value

Accesses

JOBREPORT_
DB

Job report - Database

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
ERROR_ONLY

Job report - On error only

"Y" - Job report is only stored


if a error occurs
"N" - Job report is always
stored

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
FILE

Job report - File

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

UNIX_CMD

Start parameter - Command

User-defined,
maximum 255 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
via ScriptVariable,
predefined
variable

UNIX_SHELL

Start parameter - Shell

User-defined,
maximum 3 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
predefined
variable

The Unix Shell set with this


attribute must be defined by
the UC4 administrator in the
UC4 Variable UC_SHELL_
UNIX. This is checked with
the statement :PUT_ATT.

506

Chapter3 Objects

UNIX_SHELL_
OPTIONS

Start parameter - Shell options

User-defined,
maximum 16 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via ScriptVariable,
predefined
variable

UNIX_TYPE

Type

"SHELL_SCRIPT" - Job is
generated, transferred to the
target system and executed
as the shell script.
"COMMAND" - Command or
command sequence is sent to
the shell and executed there.

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
predefined
variable

See also:
Job
Host Attributes Tab
Attributes
:PUT_ATT statement
GET_ATT function
UC4.DB Change

VMS
The following overview includes the attributes of a VMS Job object and describes their functions,
allowed values and ways of modification.

Attribute

Description

Value

Accesses

JOB_NAME, JN

Start parameter - Job name

User-defined,
maximum 39 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

Automation Engine

507

JOBREPORT_
DB

Job report - Database

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
ERROR_ONLY

Job report - On error only

"Y" - Job report only saved if


error occurs
"N" - Job report always saved

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
FILE

Job report - File

"Y" - Yes, "N" - No

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

PRIORITY, P

Start parameter - Priority

User-defined,
Value between "0" and "999"

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
predefined
variable

VMS_QUEUE_
NAME

Start parameter - Queue name

User-defined,
maximum 31 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

See also:
Job
Host Attributes Tab
Attributes
:PUT_ATT statement
GET_ATT function
UC4.DB Change

508

Chapter3 Objects

Windows
The following overview includes the attributes of a Windows Job object and describes their
functions, allowed values and ways of modification.

Attribute

Description

Value

Accesses

DOMAIN, WIN_
DOMAIN

Login info

Domain from Login info of the


Login object

GET_
ATT,
Change
Program,
predefined
variable

JOB_OBJECT

Job object

"Y" - yes, "N" - no, " " - Default

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program

JOBREPORT_
DB

Job report - Database

"Y" - yes, "N" - no

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
ERROR_ONLY

Job report - On error only

"Y" - Job report only saved if


error occurs
"N" - Job report always saved

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

JOBREPORT_
FILE

Job report - File

"Y" - yes, "N" - no

GET_
ATT,
:PUT_
ATT (PreProcess,
Process)

Automation Engine

509

WIN_CMD

Start parameter - Command

User-defined,
maximum 255 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

WIN_LOGON_
AS_BATCH

Start parameter - Log on as


batch user

"Y" - yes, "N" - no

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program

WIN_REPORT_ Job report - Is generated by


BY_SCRIPT
script

"Y" - yes, "N" - no

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program

WIN_SHOW_
AT_DESKTOP

Start parameter - Show job at


the desktop

"Y" - yes, "N" - no

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program

WIN_TYP

Type

"BAT" - batch processing,


"KDO" - command,
"EXTCOMPROC" - Interpreter

GET_
ATT,
Change
Program,
predefined
variable

WIN_VIEW

View

"NORM" - window,
"MAX" - full screen,
"MIN" - symbol

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program

510

Chapter3 Objects

WIN_WORK_
DIR

Start parameter - Working


directory

User-defined,
maximum 255 characters

GET_
ATT,
:PUT_
ATT (PreProcess,
Process),
Change
Program,
via script
variable,
predefined
variable

See also:
Job
Host Attributes Tab
Attributes
:PUT_ATT statement
GET_ATT function
UC4.DB Change

3.2.17 Login
Login
The "Login" object stores login data for hosts. Jobs and FileTransfers use it in order to access
operating systems and applications.
Object class: System object
Object type (code designation): LOGIN
The agent passes the login information and password on to the OS or application whenever a job or
FileTransfer should be processed. This information is checked and the OS rejects the execution if
any of the provided data is incorrect.
If the information is correct, the task is processed under the ID which has been stored in the Login
object. This ID is not a UC4 user ID but an OS ID.
Some operating systems allow a deactivation of the login check. Therefore, the UC4
administrator can specify in the agent's INI file whether login data should be checked.
In addition to handling Logins manually in the UC4 Explorer, you can also use the following
script elements:
l
l
l

CREATE_OBJECT - Creates a new Login object


MODIFY_OBJECT - Changes the attributes of a Login object
REMOVE_OBJECT - Deletes a Login object

Creating Login Objects


Login objects serve to store login data for hosts.

Automation Engine

511

Procedure

1. Click the button in the toolbar and a window opens which lists all the available object
types. Select type "Login" (LOGIN).
2. Assign a suitable name and open the Login object. Then click the Login tab.
3. Enter the login data to be used by the agents to log on to the host. Login data can be
specified for one particular agent or for all agents of a particular platform. If you select an
agent name in the first column, the second column specifying the platform is automatically
completed. If you select the wildcard character *, the platform must be manually specified in
the second column. The specification of Login data is required in any case.
4. For reasons of security, UC4 recommends splitting your login data to several Login objects
and to assign the relevant authorizations accordingly. The availability of different Login
objects also helps to keep a clear overview.
5. Login objects are system objects.

Various other settings are available for Login objects. Details are provided in the documentation
about the individual tabs.
Header tab
The Header tab is a general tab which is available in every UC4 object.

Description

Field/Control Description
Title

Define object titles here. This title should contain a short and characteristic
description of the corresponding object as it is displayed in all overviews.

Created

Indicates the user who created this object including the date and time.

512

Chapter3 Objects

Modified

Indicates the user who last modified this object including the date and time. The
number of times the object has been modified is displayed to the right.

Last used

Indicates user, date and time regarding the most recent use of the object. The
number of times the object has been used is displayed to the right.
Only displayed if the update function in the UserInterface settings has been
activated.

Archive Keys

Two keywords of your choice can be specified in all executable objects and the
Sync object. These keys are written to the statistical data each time the object
is processed.
Statistical data can be selected using these archive keys. Archive keys are
displayed in the Statistical Overview and can be printed.

Login Tab
The Login tab is object type-specific and is only found in the "Login" object. You can define login
data that is required by jobs and file transfers for logging on to operating systems and
applications here.
Object: Login
Object class: System object
Object type (code designation): LOGIN

Description

Field/Control Description

Automation Engine

Name

513

The name of the agent or the backend system.


You can select the agent from a dropdown list. The list includes all the installed
agents of the UC4 system.
You can also directly enter a value in this field. This is required for specifying the
name of a backend system (such as a Version Management system). Then you
select the related system type in the "Type" column. It is the administrator who
defines the system types (UC4 Variable UC_LOGIN_TYPES).
When you select "*", the selection is not limited to the name. In this case, you
must always specify the type. The Login information of this line then applies to all
the agents / systems of the selected type.
Lines that include a unique name are given preference to "*".

Type

The platform of the agent or type of the backend system.


The host type will automatically be set and cannot be changed when you select a
particular agent.
Specific host types: ILM (only selectable in system client 0000)
"MAIL" - used for e-mail connections via SMTP
"DB" - for partitioning with
RA agents: Note that you must select the name of the solution.
The administrator can define additional types for Login objects in the UC4
Variable UC_LOGIN_TYPES. These types can be selected in the column
when you either define "*" or any value for the name.

Login info

Login information to be used for logging on is specified here.


Login information must be defined in the format which is suitable for the particular
operating system or application.
Note that there can be platform-specific peculiarities.

Password

Login password shown with hidden characters.


Maximum 20 characters
MPE is an exception. 3 passwords can be specified. The password plus
separators must not exceed 62 characters.
Passwords must not include commas, regardless of the platform you use.

Comments

Login information can be read using the script function GET_ATT and the corresponding job
attributes.

Login Information Format

Operating system / Application

Format

Conversion to capital
letters

BS2000

user ID, account

entire field

514

Chapter3 Objects

Database

user name

none

GCOS8

user ID

entire field

JMX

user name

none

MPE

user ID.account[,group
name]

entire field

NSK

Group name.user ID

none

Oracle Applications

user name

none

z/OS

user ID

entire field

OS/400

user ID

entire field

PeopleSoft

Operator ID

none

SAP (ABAP Engine/Business


Intelligence)

Client, user ID

none

SAP (Exchange Infrastructure)

XI user ID

none

UNIX

user ID

none

VMS

user ID

entire field

Windows

domains\user ID

domains only

Platform-specific Features

J2EE/JMX
Usually, it is only required to specify one password. Three passwords must be indicated (separated
by commas) if WebSphere version 6 with the activated administrative security is used:
l
l
l

The 1st password is the user password.


The 2nd password is the keystore password.
The 3rd password is the truststore password.

Oracle Applications
In Login objects, an internal OA user must be specified who should be used for processing jobs. By
contract, a valid OA database user must be specified in the object ERP_LOGIN.
Windows
"*OWN" can be specified as domain when logging on for Windows. The Windows job is then
processed with a local login authorization.
Note that Windows agents require particular rights to process Jobs. These must be assigned to
the user who starts the agent.
Documentation Tabs
Documentation tabs are user-defined and client-specific tabs which can be assigned to all
object types in UC4.
Object: Login
Object class: System object
Object type (code designation): LOGIN

Automation Engine

515

All Documentation tabs that have been defined by the UC4 administrator in the UC4 variable
UC_OBJECT_DOCU are shown. Note that imported objects have their own documentation
tabs.
The Version Management tab displays the stored object versions if this function has been
activated.

Structured Documentation

Each of these tabs can also be displayed in structured form. Structured Documentation can be used
to split complex object information in well-arranged parts. Each documentation element can be used
to store texts, but also to define attributes.
You can also define links (e.g. to files, folders or to documents in the Intranet and Internet etc.) in
structured documentation. Files are then displayed with the associated program, folders are
opened, URLs call the standard browser etc. The particular actions depend on the installed
programs and the user's PC configuration.

516

Chapter3 Objects

New Documentation tabs initially only include the "Content" folder. This is your starting point for
creating a further structure. To create and edit this structure, you can use the following popup-menu
commands :
Command

Description

Add attribute

Creates a new attribute in the highlighted element.

Add node after

Inserts a new element after the highlighted element.

Add node before

Inserts a new element before the highlighted element.

Add node child

Creates a new element one level below the highlighted element.

Duplicate node

Duplicates the highlighted element and its attributes and contents.

Delete node

Deletes the highlighted element irrevocably.

You can create one or more attributes for each individual element. Basically, there are two different
types: text and enumeration. You can add one or more of these attributes to an element. Determine
the attribute's name and then select whether it is a text or an enumeration. In enumerations, you can
specify the entries that should be included.

Automation Engine

517

Names of elements and attributes should comply with the XML naming convention. Letters,
numbers and the characters "-", ".", "_" can be used. Keep the following rules in mind:
l
l
l
l

The first letter of a name must neither be a number, nor ".", nor "-".
The name must not include blanks.
Do not use colons as they are reserved characters.
Names must not begin with "XML", regardless if uppercase or lowercase letters are used.

3.2.18 Notification
Notification
A Notification is an object that can be used to inform UC4 Users of task statuses or other
changes via email, SNMP trap or through the UserInterface with the Notification Monitor. Some
Notification types include options to escalate to another Notification based on wait time and/or
User rejection of the Notification from the Notification Monitor.
Object class: Executable object
Object type (short name): CALL
The Attributes tabincludes an option that specifies the Notification type. The type you select
determines whether emails are sent, SNMP traps are created, messages are sent to the UC4
Notification Monitor, and how messages are escalated. Available options for each type are listed in
the table below:

518

Chapter3 Objects

Type

Email

SNMP Trap

Notific
ation
Monito
r
Messa
ge

Escal
ation

Email

Sent

Not available

Not
applica
ble

Not
applic
able

Message

Optionally sent

Optionally created

Must
be
accept
ed

Not
applic
able

Request

Optionally sent

Optionally created

Can be
accept
ed or
rejecte
d

Time
based

Alert

Optionally sent

Optionally created

Can be
accept
ed or
rejecte
d

Time
based
or by
User
rejecti
on

To send Emails using Notification objects, you must correctly set up the E-mail connection.

Notification Monitor

The Notification monitor is a window that displays Notification messages in the UserInterface. The
particular User sees it either immediately or when s/he logs on the next time. For more information
on the Notification Monitor, see Notification - Monitor.
Creating Notifications
Notification objects send messages to email addresses, individual users, or even user groups in
a UC4 system's client. Before creating your Notification, you should know what template to use
and which tabs you will want to respond to.

Selecting a Template

UC4 ships following Notification templates: CALL.ALARM, CALL.STANDARD and


CALL.MAIL.HTML.
The CALL.ALARM template has:
l
l

Alert set as its type on the Notification tab


&UC_CAUSE_NR entered in the Attach reports from Task (RunID) field on the
Notification tab.
A predefined sample code on the Process tab.

Automation Engine

519

CALL.ALARM is a helpful template for using UC4's scripting language for your notification
messages and when you want to start with example code that you can configure to fit your needs.
For more information, see Notification - Object Type ALARM.
The CALL.MAIL.HTML template shows the following peculiarities:
l
l

Email is set as its type on the Attributes tab.


Notification tab: It includes a predefined notification text in HTML format.
&UC_CAUSE_NR is entered in the Attach reports from Task (RunID field.
A sample script that reads the values of the causing object and writes them to the notification
text on the Process tab.

The CALL.STANDARD template has:


l
l

Request set as its type on the Notification tab


Nothing defined on the Notification or Process tabs.

CALL.STANDARD is helpful template for using the Notification tab in order to define your
Notification messages. The Notification tab allows you to define messages without the complexity
or powerful benefits of UC4's scripting language.

Which Tabs to Use

When you define a Notification, you have to consider how you want to send messages, what you
want to send, and who you want to send them to. The tabs you will use to create a Notification will
depend on the answers to those questions.
To Consider:

Use:

How you want to send


messages

The Type and other settings on the Attributes tab, and optionally the
settings on theHeader, Variables & Prompts, Documentation, Sync
and Runtime tabs.

What you want to


send

The Notification and/or Process tabs.


From the Notification tab you can specify a subject and message
body. These fields allow for text and Variable objects, but if you want to
create anything more complex (like returning the calling objects name
or putting in a line break), you will want to use the Process tab instead.
The Process tab is a type-specific tab where processing instructions
are stored in UC4's scripting language. If you use the Process tab, text
entered for the subject and message on the Notification tab will be
ignored.
Another thing you can define on the Notification tab is how you attach
files. The file attachment settings from the Notification tab can still be
used even if you are using the Process tab to specify a subject and
message body.

Who you want to send


them to

The Recipients tab to specify users, user groups, and email


addresses. If a Calendar keyword is additionally specified, the
receivers will only be notified if the relevant date lies within the
Calendar's specified period of time. All the specified users are informed
if otherwise - due to the specified Calendar conditions - none of the
users would be informed.

520

Chapter3 Objects

Procedure

1. Click the button in the toolbar. A window listing all the available object types
opens. Select a Notification template. To create a Notification with predefined code
on the Process tab, select CALL.ALARM.
2. Assign an adequate name and open the Notification object. Then click on the
Notification tab
3. Select a Notification type and respond to any of the other fields on the Process tab.
More detailed information about all the possible impacts is provided in the Notification
Monitor description. Define your subject, message, and attachments using the
Notification and/or Process tabs.
4. Specify recipients on the Recipients tab.
5. Optionally specify settings on the Header, Variables & Prompts,
Documentation, Sync and Runtime tabs.
Header tab
The Header tab is a general tab that is available in every UC4 object.

Description

Field/Control

Description

Header
Title

You define object titles here. This title should contain a short and
characteristic description of the related object because it appears in all
overviews.

Automation Engine

521

Created

This indicates the user who has created this object including the date
and time.

Modified

This indicates the user who has last modified this object including the
date and time. The number of times that the object has been modified is
displayed to the right.

Last used

This indicates user, date and time regarding the most recent object
usage. The number of times that the object has been used is displayed
to the right.

Active

With this option being deactivated, the object will automatically be set
to inactive after its activation and not processed.
Therefore, the tasks obtain the status ENDED_INACTIVE_OBJECT
(return code: 1925).
This setting is available in the Header tab of all executable objects and
is set by default.

Archive keys

You can specify two keywords of your choice in all executable objects
and in Sync objects. These keys are written to the statistical data each
time the object is processed.
Statistical data can be selected using these archive keys. Archive keys
are displayed in the Statistical Overview and can be printed.

Extended Reports

Extended reports can be written for all executable objects. They log the
complete script with all Includes, the generated JCL of Jobs or
accesses to UC4 objects.

Default (UC_
CLIENT_SETTINGS)

When you select this option, the reports that the UC4 administrator has
defined in the UC4 Variable UC_CLIENT_SETTINGS with the key
EXT_REPORTS will be generated.

All

All extended reports are written for this object.


This option overwrites possible pre-settings of the client.

None

No extended reports are written for this object.


This option overwrites possible pre-settings of the client.

Sync Tab
The Sync tab is object-type specific and is available in all executable UC4 objects.
Sync objects synchronize tasks on the basis of defined conditions. To use this function, you enter
one or several Sync objects including the actions that should be included in this tab.

522

Chapter3 Objects

When the task starts, the Sync objects are checked one after the other. The UC4 Automation
Engine tries to use the Sync object in the first line by calling the start action. If this is not possible
because of the Sync object's current condition, the task waits, aborts or is skipped. The type of
reaction depends on the Else condition that is defined in the tab's last column. If "wait" is specified,
the task waits until it can use the Sync object with the start action. The UC4 Automation Engine
checks the Sync object in the next line etc. The task starts as soon all Sync objects are
successfully used. Depending on the task's end status, either an abend or end action is processed.
You can specify up to 500 Sync objects.
Sync objects must not include more than 5000 rules. Rules are defined actions that are directly
entered in the Sync object.
Task ends are administered by work processes but only the primary work process releases busy
Syncs. Because of this task allocation, it can take several seconds until a Sync is released after
a task has ended. In this case, the report entry shows a time stamp that is later than the task
has ended. Such delays occur when the primary's work load is high or if it is processing lots of
Syncs.
Note that using many Sync objects and rules can reduce task clarity. Therefore UC4
recommends keeping the number of Sync objects to a minimum.

Description

You can only select actions that have been defined in the Sync object.
Field/Control

Description

Sync object

This selects the Sync object that should be used for synchronizing a
task.

Start action

This defines the action that should be taken when a task starts. If this
is not possible because of the Sync's status, the Else condition
becomes effective.

Abend action

This action will be processed when the task aborts.

Automation Engine

End action

This action will be processed when the task ends successfully.

Else

This defines what should happen to the task when the start action
cannot be executed:
l

l
l

the task should wait until the start action can be executed
(WAIT)
the task aborts (ABEND)
the task is skipped (SKIP)

See also:
Sync
Attributes Tab
The Attributes tab is object type-specific and is only available in Notification objects.
Object: Notification
Object class: Executable object
Object type (short name): CALL
It contains the specifications for the type of Notification.

Description

Field/Control
Attributes

Description

523

524

Chapter3 Objects

Group

When the Notification should be started through a Group, you can


define the particular Group here. No entry means that the Notification is
activated immediately.
Note that the entry in this field will not be considered if the Notification
is started through a Workflow, a Schedule or as a recurring task.

Queue

Selection of a Queue object in which the FileTransfer should be


processed. The FileTransfer automatically starts in the Client Queue
(object name: CLIENT_QUEUE) if nothing has been specified in this
field.

Int. Account

The specification of an internal account.


Contents do not affect the UC4 system's internal processing. You can
access the attribute "Int. Account" with script elements and integrate it
in your processes.

Priority

You can assign different grades of importance for Notifications: normal,


low or high. This priority is displayed in emails and in the notified
operator's message window and the color of the icon in the edge of the
Notification monitor changes according to the selected priority:
l
l
l

low - green
normal - yellow
high - red

This priority only serves to visualize a Notification's importance but


has no other effects.
Type

There are four type that affect how messages are sent to the
Notification monitor and what kinds of escalations are available:
Message: Message will be sent to the Notification Monitor. No
escalation is available.
Request: Messages will be sent to the Notification Monitor. Users
can accept or reject the message, but their selection will not escalate
the message to another Notification. However, the Notification can be
escalated based on the time settings in the "Escalation" box.
Alert and Messages will be sent to the Notification Monitor. Users can
accept or reject the message. The Notification will be escalated if a
user rejects the message or based on the time settings in the
Escalation box.
Email is the Notification type: Message will not be sent to the
Notification monitor and no escalation is available.
The type defines expected reactions from the operator who should be
notified.

SNMPconnection

Activate this check box if an SNMP Trap should also be created when
a Notification starts.

Send email

If this check box is activated for Message, Request, or Alert types,


emails are also sent to the responsible recipients at Notification start.
You can specify two email addresses in User objects. Emails are then
sent to both addresses.

Automation Engine

525

Escalation

Only available for the types "Request" and "Alert".

After ... Min. without


response

Time limit (in minutes) in which the controlling recipient has to respond.

quit automatically

If the check box "quit automatically" is activated, an escalated


Notification automatically closes its predecessor with the status
ENDED_ESCALATED.

Notification

An additional Notification which will be activated whenthe controlling


recipient does not respond, or when a user rejects an "Alert" message
in the Notification Monitor, or when a user rejects an "Alert" message in
the Notification Monitor.

Runtime parameters
UC4 Priority ... (0-255)

The priority that should be used for this job's execution in UC4.
Allowed values: 0 to 255
Default: 0
The priority that the UC4 administrator has specified in the UC4
Variable UC_CLIENT_SETTINGS with the key "TASK_
PRIORITY" is used when you select the value "0".

TimeZone

The TimeZone that should be used.

Generate at runtime

You select this check box if the Notification should not be generated at
activation time but at runtime.

Tasks running
parallel
Max. number

The setting that defines the maximum number of parallel executions for
this Notification.
Allowed values: 0 to 99999
Default: 0 (no limit on tasks running parallel)
Examples:
Max. "1" - At all times, there must only be one active Notification.
Max. "2" - At all times, the maximum of two active Notifications must
not be exceeded.
etc.

Else: Wait Abort

The instructions that define how this Notification should be handled if


its execution exceeds the maximum number of tasks that are set to run
parallel.

Notification tab
The Notification tabis an object type-specific tab that is only available in the Notification object.
It includes a subject, the message body and attachment settings. The subject and the message
body will be ignored when you use the Process tab.
Object: Notification
Object class: Executable object
Object type (short name): CALL

526

Chapter3 Objects

Description

Field/Control

Description

Subject

The title for the message or the subject field of e-mails.


This field allows text and Variable objects. This setting will be ignored
when you use the Process tab. An e-mail subject will automatically be
created when you do not specify it. An automatic subject is composed
of the Notification object's name, its running number (RunID) and the
client.
For example: Notification: 'DAYSHIFT' RunID:'0001569030'
client:'0011'

Text field for the


message

Attachments

Max. 8000 characters. This field allows text and Variable objects, but if
you want to create anything more complex (like returning the calling
objects name or putting in a line break), you will want to use the
Process tab instead. This setting is ignored if you use the Process tab.

Automation Engine

Attach reports from


task (RunID)

527

The RunID of the task whose reports should be attached to the e-mail.
A file is sent for each report type. The file names are composed as
follows:
RunID.report type.txt
For example: "002523059.LOG.txt"
You can also include external Job output files.

Source:
This option is only available when the Type is set to E-mail or the Email box is checked on the Notification tab
This option indicates the reports and files that should be attached and is
only relevant for Jobs.
l

Database - Only the Job's default reports that are stored in the
UC4 Database are attached. This also applies to the Job report
if it has been stored in the UC4 Database.
External files - Files that are stored on the agent computer. This
also applies to the Job report (if it has been stored as a file) and,
if available, registered Job output files.
All - Reports in the database and files on the agent computer. If
the same report is available in the database and as a file, it is
only sent once.Two e-mails are sent if data is available on the
agent (one from the AutomationEngine and one from the Agent).

To send external output files, the user requires the authorization "P"
for external reports (EXTREP) and Jobs. Otherwise, the files are
not attached and an error message is written to the Notification's
report. The agent on which the Job has been executed must be
active and the files must exist.
Attach a file

The path and the name of the file that should be attached.
The file must be stored in a directory that can be accessed by the Email connection.

Recipients tab
The Recipients tabis object type-specific and is only available in Notification objects. It contains
the specifications for the receivers of a Notification.
Object: Notification
Object class: Executable object
Object type (short name): CALL

528

Chapter3 Objects

Description

Field/Control

Description

Calendar

The Calendar that includes the schedule of the responsible recipient.

Keyword

The time period for which a recipient is responsible.


This time period corresponds to a defined calendar keyword.
When a Calendar is specified, the recipient will only be notified when
the current date lies within the defined Calendar keyword.

Recipients

You can either select a particular User, or a UserGroup, or an email


address as the responsible recipient who should be notified. When two
email addresses are specified in User objects, emails are sent to both
addresses. Selecting a UserGroup means that all its members will be
notified. You can also specify an email address. Make sure you select
at least one User or UserGroup for Message, Request, or Alert
Notification types to assure that messages will be written to the
Notification Monitor.
You can add or delete users and user groups at runtime by using the
script elements:ADD_ATTand:REMOVE_ATT.
All the specified users are informed if no user is available because
of Calendar conditions.
Predefined variables can only be used in the Recipients column,
and only when they represent an email address.

Automation Engine

529

Runtime tab
The Runtime tab is an object-specific tab that is available in every executable object in UC4. It
can be used to specify parameters for a task's runtime behavior.

The Runtime tab is structured as follows:


l
l
l
l
l
l

Return code handling


Forecast setting
Evaluating the estimated runtime (Runtime Evaluation)
Monitoring the maximum runtime (Runtime Monitoring)
Monitoring minimum runtime (Runtime Monitoring)
Reaction to runtimes that have been exceeded or not reached (Runtime Monitoring)

Description

Field/Control

Description

Definition for
ENDED_OK
Return Code <=

The maximum return code for a task's normal end.


A task ends normally (Status "ENDED_OK") if its return code lies
below or is equal to the specified maximum return code.

Else execute

You can run an object when the task does not end with a return code
that lies within the ENDED_OK area.
Note that this object will not be processed if the task is terminated
by using the script statement :EXIT.

530

Chapter3 Objects

End status for


Forecast

The selection list for the end status that this task should return when
you make a forecast calculation.

Estimated runtime
(ERT)
Current ERT =

This displays the task's next estimated runtime (ERT).


You can enter the estimated runtime here. This value applies until the
ERT calculation is made after the task's next execution.
Format: "hours:minutes:seconds".

Use default (UC_


CLIENT_SETTINGS)

Selecting this option has the effect that the calculation method that the
UC4 administrator specified in the UC4 Variable UC_CLIENT_
SETTINGS using the key "ERT_METHOD" is used to calculate the
estimated runtime.

Fixed value

A fixed value is entered as the estimated runtime.


Format: "seconds"

Dyn. Method

The selection list for the dynamic method that is used to calculate the
estimated runtime from the real runtime.
Possible selection: Average, linear regression, maximal value

from the last ... runs

The number of past runs that are considered for the ERT calculation.
Allowed values: 0 to 25.

+ ... %

A value in percent for an upward correction of the ERT.

Differences > ... % are You can ignore possible huge differences to of actual runtimes.
ignored
The upper limit (in percent) for actual runtimes that should be included
in estimated runtime calculation.
but do use ... runs at
least

The number of past runs that should be considered regardless of


differences. Allowed value: 0 to 25.

Show Chart

A button that you can click in order to update the estimated runtime
according to the current settings. A diagram displays in a separate
window; it shows the last 25 ERT/RRT runs. Windows that are already
open are updated.

Reset Values

A button that you can use to delete the real and estimated runtimes.
A security query displays, confirm it and all saved runtimes are cleared.

Maximum runtime
(MRT)
None

The maximum runtime is not monitored.

Fixed value

The maximum runtime is monitored.


The allowed time is entered as a fixed value in the format
"hours:minutes:seconds". You must specify an action (ELSE
condition) that applies if the maximum runtime has been exceeded.

ERT

The maximum runtime is monitored.


The valid estimated runtime (ERT) at the time of the task's activation is
used as its maximum runtime. You must specify an action (ELSE
condition) that applies if the maximum runtime has been exceeded.

Automation Engine

531

+ ... %

When you select the ERT, you can also specify a correction value in
percent for the maximum runtime. The value you determine is added to
the estimated runtime.

Curr. date + day(s)


Time

The maximum runtime is monitored.

TimeZone

Selection of a TimeZone object.

A number of days and a time is determined until which the task must be
finished. The starting point for the date calculation is the task's real
date. You must specify an action (ELSE condition) that applies if the
maximum runtime has been exceeded.

Minimum runtime
(SRT)
None

The minimum runtime is not monitored.

Fixed value

The minimum runtime is monitored.


The minimum runtime is used as a fixed value in the format
"hours:minutes:seconds". You must specify an action (ELSE
condition) that applies if the runtime falls below the minimum runtime.

ERT

The minimum runtime is monitored.


The valid estimated runtime at the time of the task's activation is used
as the minimum runtime. You must specify an action (ELSE condition)
that applies if the runtime falls below the minimum runtime.

- ... %

A correction value in percent can be specified for ERT for the minimum
runtime. The determined value is subtracted from the estimated
runtime.

Else
Cancel / Quit

If you activate this check box is activated, the task is canceled or quit if
the runtime has been exceeded. Only available if the maximum runtime
is monitored.

Execute

If you activate this check box, you determine that the task is executed.
You can directly select the executable object. If the runtime is
exceeded or not reached, the specified task is executed. Only available
if the runtime is monitored.

Comments

A different type of runtime monitoring can be used for tasks that have been activ