Automation Engine 9
Knowledge Base
Version: 9.12.0
Date: 2015-03
Automic Software GmbH
ii Copyright
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 Time
1.0.1 General Time Terms
2 Agent's Job Messenger
2.0.1 General Start Parameters
1
1
3
3
3 UC4 and NAT
5
4 External Error Codes
6
4.1 COBOL - File Error Codes
Original Text From Compiler Description
4.2 COBOL - Runtime Error Codes
Original Text from the Compiler Description
6
6
8
8
4.3 TCP/IP - Error Messages of the TCP/IP-Stack
26
4.4 UNIX - Error Codes
28
4.4.1 Error Codes in Log Messages of Agents
Notes
4.4.2 DEC OSF
Error Codes Alpha - DEC-OSF/1 - Digital UNIX 4.0
4.4.3 HP-UX
28
29
29
29
32
Error Codes HP Workstation (9000), HP-UX 9
32
Error Codes HP Workstation(9000), HP-UX 10
34
4.4.4 IBM AIX
Error Codes Power PC - AIX 4.1
4.4.5 SCO
Error Codes Intel - SCO-UNIX ODT 5.*
4.4.6 Sun OS (Solaris)
37
37
40
40
44
Error Codes Sparc, Solaris 1 Version 4.1 and Later
44
Error Codes Sparc, Solaris 2 Version 5.5 and Later
46
Error Codes Intel, Solaris 2.4 and Later
49
4.5 Windows - Error Codes
52
4.5.1 Win32 - Error Codes (0 - 999)
52
4.5.2 Win32 - Error Codes (1000 - 1999)
63
4.5.3 Win32 - Error Codes (2000 - 5999)
91
4.5.4 Win32 - Error Codes (6000 - 11999)
108
iv
Contents
5 SNMP Support
131
5.1 About SNMP
131
5.2 UC4 and SNMP
131
Masteragent Mode On
5.3 Agent Mode on UNIX
132
133
Masteragent (recommended)
133
Subagent
134
HP-UX
134
5.4 UC4 SNMP Subagent's FAQ and Glossary
135
Keywords:
135
Frequently asked questions:
135
5.5 Installation
5.5.1 Installing the UC4 SNMP Subagent (UNIX)
138
138
Requirements
138
Supplied files
138
Installation
138
5.5.2 UC4 SNMP Subagent for UNIX
140
Structure of the file ucsnmp1.ini
140
INI-file example
141
5.5.3 Installing the UC4 SNMP Subagent (Windows)
142
Requirements
142
Supplied Files
142
Installation
142
5.5.4 UC4 SNMP Subagent for Windows
143
Structure of the file ucsnmp1.ini
143
INI-file example
145
5.5.5 Windows SNMP Service Configuration
145
Requirement
145
Procedure
145
5.6 MIB
147
5.6.1 Structure of the MIB
147
5.6.2 Agent Data Group
148
5.6.3 Agent Control Group
149
5.6.4 Agent Work Group
149
Automation Engine
v
5.6.5 System Group
151
5.6.6 Client Group
153
5.6.7 Server Group
154
5.6.8 Agent Group
157
5.6.9 Blocking Points Group
161
5.6.10 Notification Group
163
5.6.11 Generated SNMP Traps
165
Overview of Traps
165
Description of Traps
165
5.7 Net-SNMP License
170
6 UC4 and Target Systems
174
6.1 UC4 and BS2000
6.1.1 BS2000 Text Archive
174
174
Initial Situation
174
The Solution: BS2000 Text Archive
174
Integration into BS2 TOOLS
174
Program BS2 TAR
174
UC4 Installation CD
175
6.1.2 UC4 Automation Engine/Agent - BCIN for Connection Set Up
175
6.1.3 BS2000 Agent - FileTransfer Support
176
File Attributes for Destination
Example
Library Elements As Source and Destination
Examples
176
176
176
176
Keeping the original attributes
177
Limitations to FileTransfers with PAM Files
177
6.1.4 Utility for RFC Tasks
177
6.1.5 Agent - Freely Defined Port Numbers
178
6.1.6 BS2000 Console Command
178
6.1.7 BS2000 Operating System Command
182
6.2 UC4 and Databases
186
6.2.1 Database Agent
186
6.2.2 Connection to Oracle Databases
187
Single instance Oracle connections
187
vi
Contents
Oracle RAC connections
187
6.2.3 Stored Procedures in Sybase
187
6.2.4 Stored Procedures in MS SQL Server
188
RETURN
188
PRINT
188
RAISE ERROR
188
6.2.5 ILM - Partition Key Turnaround
188
General Information
189
Partition Change
189
Partition Key Turnaround Mode
189
Oracle
189
SQL Server
191
6.3 UC4 and GCOS 8
6.3.1 GCOS8 Agent - FileTransfer Support
GFRC File Format
193
193
193
Syntax
193
Example
194
UFF sequential File Format
194
Syntax
194
Example
194
UFF relative File Format
194
Syntax
195
Example
195
UFF indicated File Format
195
Syntax
195
Example
196
6.3.2 Monitoring Abnormal Job-Messenger Ends
Procedure
6.4 UC4 and Java EE/JMX
196
197
198
6.4.1 Java EE/JMX Agent
198
6.4.2 Generating MBeans from Web Services
200
General
200
Installation
200
Usage
203
Automation Engine
vii
6.4.3 Java EE/JMX Agent and IBM WebSphere
205
6.4.4 Sending an SOAP Message with an MBean
205
6.5 UC4 and Micro Focus JES
6.5.1 Jobs in Micro Focus JES
208
208
Creating a Job
208
Architecture
209
Agent Variables in Micro Focus JES
210
Example for a JES-Exit trace file
211
6.6 UC4 and MPE
6.6.1 Agent - Interaction between UC4 and MPE
Job Processing
212
212
213
213
Executing FileTransfers
213
Event Handling
213
6.7 UC4 and NSK
6.7.1 Architecture of the UC4 Agent for the HP NonStop Server
Description of Internal Procedures:
214
214
214
1. Job Start
214
2. Job Run
215
3. Job End
215
Notes:
215
6.7.2 Executing Jobs on NSK
216
6.7.3 Automated Handling of Input Prompts
216
Usage
217
Examples
217
6.7.4 Agent - Interaction between UC4 and NSK
218
Processing Jobs
218
Execution of FileTransfers
219
Call Interface
221
6.7.5 EMS Template File
221
6.7.6 Configuration of NSK-specific Parameters
222
6.8 UC4 and Oracle Applications
6.8.1 UC4 and Oracle Applications
Terms for Oracle
222
222
223
viii
Contents
Terms for Oracle Applications
6.8.2 Return Codes for OA Jobs
6.9 UC4 and OS/400
6.9.1 Agent - Interaction between UC4 and OS/400
223
224
224
224
Job Processing
224
Executing FileTransfers
226
Event Handling
226
CallAPI
226
6.9.2 OS/400 Agent - FileTransfer Support
226
File Specification
227
Attributes
228
6.9.3 Agent - Commands
230
Starting the Agent
230
Ending the Agent
230
Generating the message library
231
6.10 UC4 and PeopleSoft
6.10.1 Testing the PeopleSoft Connection
Procedure
231
231
231
6.10.2 Using Bind Variables
234
6.10.3 Changes in Run Controls
234
Use
234
Examples
234
Risks and limitations
236
6.11 UC4 and SAP
236
6.11.1 SAP Solutions and Job Scheduling with UC4
236
6.11.2 SAP NetWeaver
237
UC4 Automation Platform and SAP NetWeaver
237
People Integration
239
Integration in SAP Enterprise Portal (iViews)
239
Introduction
239
Starting Tasks
239
Monitoring Activities
241
Information Integration
Scheduling Data-Loading Processes
242
242
Automation Engine
6.11.3 UC4-JCL for SAP
Scheduling Process Chains
6.11.4 UC4 JCL for SAP
Scheduling Queries in Batch Mode
Process Integration
Monitoring SAP XI Communication Channels
ix
242
242
243
244
245
245
6.11.5 UC4 JCL for XI
246
Application Platform
246
ABAP
Job Management
6 Executing Jobs in ABAP Stack (CCMS)
6.11.1 UC4 JCL for SAP
6 Child Processes (JOBD)
6.11.1 UC4 JCL for SAP
6 Intercepted Jobs
6.11.1 UC4 JCL for SAP
6 Evaluating the Application Return Code of SAP Steps
246
246
247
248
249
250
251
251
252
6.11.1 Via a script element
252
6.11.2 Via the step list report
252
6.11.3 Via the report
252
Variant Management
6.11.4 UC4 JCL for SAP
BDC Management
6.11.5 UC4 JCL for SAP
Spool Management
6.11.6 UC4 JCL for SAP
Event Management
253
253
254
254
254
255
255
6.11.7 SAP Event
256
6.11.8 UC4 support
256
6.11.9 UC4 JCL for SAP
257
Criteria Manager
6.11.10 UC4 JCL for SAP
257
258
Transferring SAP Jobs
258
Assuming SAP Calendar Definitions
259
x
Contents
JAVA
261
Java EE/JMX Agent for SAP NetWeaver
261
JMX in SAP NetWeaver
262
6.11.11 Monitoring the Java EE Engine
262
6.11.12 Starting and stopping a service
263
Executing Jobs in Java Stack (JXBP)
265
6.11.13 Report for Java statistics
266
6.11.14 Installation
266
6.11.15 Special cases
266
6.11.16 Return codes
267
Lifecycle Management
Monitoring SAP NetWeavers
Monitoring Monitors
6.11.17 UC4 JCL for SAP
Monitoring SAP Events
267
267
267
268
268
6.11.18 Procedure
269
6.11.19 Notes
269
SAP Adaptive Computing Controller
269
UC4 Supports SAP ACC
269
Using the MBean ACC
270
6.11.20 Procedure
271
6.11.21 Examples
271
6.11.22 Return codes
272
Analyzing System and Application Logs
6.11.23 UC4 JCL for SAP
Integrating UC4 with the SAP Solution Manager
273
273
273
6.11.24 Monitoring
273
6.11.25 Operations monitoring
274
6.11.26 Business process monitoring
275
6.11.27 Process management
275
Registering to System Landscape Directory
275
Switching Operation Modes
276
6.11.28 UC4 JCL for SAP
276
6.11.29 SAP Banking
277
Automation Engine
UC4 Process Management and SAP for Banking
xi
277
Processes in SAP for Banking
277
Application return code and application log
277
Starting process networks and processes
278
Requirements for UC4
278
UC4 functional description
278
UC4 JCL for SAP
279
6.11.30 SAP Financial Closing Cockpit
Integrating UC4 in SAP Closing Cockpit
279
279
Requirements:
279
Supplied files
279
Installation
280
Activating UC4 Objects with SAP Closing Cockpit
284
Configuration
284
Execution
287
6.11.31 SAP Solution Manager
SAP Solution Manager Integration
287
287
Configuration
287
Functionality
288
Setting up the UserInterface Integration
290
Supplied Files
290
Procedure
290
6.11.32 Custom Solutions
Archiving Data in SAP Systems
292
292
Controlling with UC4
292
Requirements in the SAP system
293
UC4 objects
293
Procedure
294
Conclusion
294
Mass Processing
294
Definition
295
Technique
295
SAP R/3 Client Copies
Client copies in SAP R/3
295
296
xii
Contents
Problem definition
296
R/3 Client copies with UC4
296
SAP Dialog for UC4
297
Automated SystemCopy for SAP
297
6.11.33 Technical Connection
298
UC4 and SAP
298
Multiple SAP Systems
298
Other SAP Agents
298
SAP Security Objects
299
Consideration of Job Attributes
303
Interfaces
303
Interfaces
303
General information
303
Functional Differences
304
6.11.34 Script Elements and Corresponding Interfaces
Transporting the UC4 Interface
General
File Names
6.11.35 Importing Function Modules in SAP
304
306
306
307
307
Requirements:
307
Procedure:
307
Testing the UC4 Interface with ABAP Workbench
309
Agent for SAP BW
312
General
312
Status check
313
Archive Parameters with R3_ACTIVATE_REPORT
315
ERROR/ERRORLEVEL with R3_ACTIVATE_SESSIONS
315
ERROR
315
ERROR=IGNORE
316
ERROR=ABEND
316
ERRORLEVEL
316
Troubleshooting
317
Checking Errors
317
Job report
317
Automation Engine
xiii
Attributes of Executable Objects
317
CPIC User
317
Helpful Transactions
317
Log Files
317
SAP's System Log
317
Traces
318
Problems by Importing Function Modules
Program tp does Not Terminate
318
318
6.11.36 Symptom
318
6.11.37 Cause
318
6.11.38 Solution
318
SAP Jobs End with ARCHIVE_INFO_NOT_FOUND
319
6.11.39 Symptom
319
6.11.40 Cause
319
6.11.41 Solution
319
Stability problems with SAP instances occurred if many SAP Agents (RFC connection)
were used on one Server
319
6.11.42 Symptom
319
6.11.43 Reason
320
6.11.44 Solution
320
Problem with Password Assignment to SAP
After updating to SAP NetWeaver 2004s and later, CPIC user could no longer log on
320
320
6.11.45 Symptom
320
6.11.46 Reason
320
6.11.47 Solution
321
6.11.48 Certificates
323
Overview
6.12 UC4 and Siebel
6.12.1 Starting and Monitoring Tasks
6.13 UC4 and UNIX
324
325
325
326
6.13.1 Authentication of Login Data
326
6.13.2 Shell and Shell Options
327
Determining the Shell Path
327
Determining Shell Options
327
xiv
Contents
6.13.3 User ID for the UNIX Agent
327
6.13.4 UNIX Agent - FileTransfer Support
328
6.13.5 Rights for Deleting Source Files in FileTransfers
328
6.13.6 Querying the Unix File System
329
6.13.7 PREP_PROCESS - Querying the UNIX File System
334
Comments
335
Examples
336
6.13.8 AIX Process Abort Due To Lack of Memory
336
6.13.9 Enlarging Core Files
336
6.13.10 Return Codes for UNIX Jobs
337
6.13.11 Activating Job Messenger Traces
338
6.13.12 Solaris: Separating Jobs from Agent Processes
340
6.13.13 Resource Limitation by using ulimit
341
6.14 UC4 and VMS
341
6.14.1 VMS Agent - FileTransfer Support
341
6.14.2 Return Codes of VMS Jobs
344
6.15 UC4 and WebSphere MQ
6.15.1 UC4 Connector for WebSphere MQ Queue Manager
344
344
XML Request Message
345
Example of Request
346
XML Reply Message
347
6.16 UC4 and Windows
6.16.1 Starting Programs Under Windows
Attributes
348
348
348
Domain
348
User Name
348
Password
348
BATCH (login type)
348
DESKTOP
348
Attention
348
System Dependencies
349
Strategy for Jobs under Windows
349
6.16.2 Test Programs for the Windows Agent
Purpose
350
350
Automation Engine
xv
Files
350
Operating the Test Programs
350
Example
350
6.16.3 Windows Job Object
Example:
6.16.4 Reports of Windows Jobs
Generating Job Reports through Script
351
351
352
352
353
Windows Job Object
6.16.5 User Account Control in Windows 2008 and Vista
Comment
353
353
354
6.16.6 Retrieving the CPU Number
354
6.16.7 Libraries in Windows 7
354
6.16.8 Windows Agent - FileTransfer Support
355
Windows File Attributes
355
Additional Options
355
6.17 UC4 and z/OS
6.17.1 Agent - Interaction between UC4 and z/OS
356
356
Job Processing
356
Executing FileTransfers
356
Event Handling
357
CallAPI
357
6.17.2 z/OS Agent - FileTransfer Support
357
Language Environment Format
357
Examples
357
Allocate Format
358
6.17.3 Message Classes
358
Using an Output Management System
6.17.4 Event Monitor
359
360
Event Monitor as independent task (Started Task)
360
Ending the Event Monitor
361
SMF Exit
361
6.17.5 External Job Monitor
Function of the external Job Monitor (EJM)
362
362
xvi
Contents
SMF Exit
364
Filter file
364
6.17.6 SMF Exit
366
General
366
Configuration
367
Starting the Event Monitor
368
Ending the Event Monitor
368
Warm start
368
Exceptions
368
Scenario
369
6.17.7 Automatic File-System Events
370
Procedure
370
File name as filter
371
Several filter criteria
371
6.17.8 GDG Support
Configuration
373
374
6.17.9 Recognizing and Assessing Job Ends
374
6.17.10 Return Codes of z/OS Jobs
375
6.17.11 JCL Exit
375
Configuration
376
6.17.12 Include MVS.JOBMD_DEFINITIONS
376
7 Terminology - Computer, Programs and Files
377
7.1 Naming Conventions
377
7.1.1 General
377
7.1.2 Syntax in General
377
7.1.3 UC4 Server Syntax
377
7.1.4 Agent Syntax
377
7.2 Program and File Overview
379
7.2.1 Programs
379
7.2.2 Files
380
7.2.3 SAP Development Objects of the UC4 Interface
380
7.2.4 Return Codes of Agents running on Windows
380
Glossary
383
Automation Engine
1
1 Time
This document serves to introduce the basic terms regarding time in general and time in connection with
UC4.
1.0.1 General Time Terms
Time is made up of a given date and a given time. The indicated time refers to the local time. It is thereby
dependent on the pertinent time zone and the use (or non-use) of Daylight Savings Time.
Los Angeles (PST)
New York (EST)
UTC
Frankfurt (CEST)
Tokyo (TYST)
Friday 3rd May,
2002
04:13:02
Friday 3rd May,
2002
07:13:02
Friday 3rd May,
2002
12:13:02
Friday 3rd May,
2002
13:13:02
Friday 3rd May,
2002
21:13:02
Date
The term "date" always refers to the local date. This date is therefore dependent on the respective time
zone and use (or non-use) of Daylight Savings Time.
Time
The term "time" always refers to the local time. The time is therefore dependent on the respective time
zone and use (or non-use) of Daylight Savings Time.
UTC - Coordinated Universal Time UTC is the international time standard and basis for all time calculations in UC4. UTC is based on the
division of the day into 24 hours. Therefore, afternoon times are specified, for example, as 16:00 UTC
(sixteen hours, zero minutes). There is no daylight savings in UTC. This way the time and date
specification is always precise.
GMT - Greenwich Mean Time
Time zones are based upon Greenwich Time as the meridian (0º longitude) passes through Greenwich.
Greenwich Mean Time serves as the basis for calculating time differences to other time zones.
TZ - Time Zone
The areas with time differences to UTC are called time zones. This difference must not necessarily denote
one full hour (60 minutes). The time zones generally run along the longitudes. Within the political borders of
individual countries, however, the time zones can deviate from the general longitudinal definition.
2
Chapter 1 Time
Date Line
The date line lies along the 180° line of longitude. Standard Time
Standard time is the local time assigned to the pertinent time zone. Standard time is also occasionally
identified as winter time.
DST - Daylight Savings Time
For daylight savings, the standard time is adjusted forward by a certain amount of time. Each individual
country has its own rules on whether or not Daylight Savings Time is used, the point in time for the
changeover and the time difference to standard time. Likewise, the chronological year itself determines if
and when daylight savings is implemented. Some countries are currently in the process of making
changes or preparing to decide upon a Daylight Savings Time arrangement.
The time change from Daylight Savings Time to standard time and vice versa is most commonly 1 hour (60
minutes). Some countries, however, use a difference of more or less than one hour. Furthermore, time
change in the northern hemisphere is directly opposite to that in the southern hemisphere. When in the
northern hemisphere the changeover to Daylight Saving Time is made, the southern hemisphere
simultaneously switches back to standard time. The switch to Daylight Saving Time in the northern
hemisphere is made in the springtime, in the southern hemisphere in the fall (autumn).
See also:
Using TimeZones in UC4
Automation Engine
2 Agent's Job Messenger
All OS Agents have a job messenger that can be used to run and monitor jobs. You call it in the HEADER
and TRAILER of Include objects. These specific Job Includes are available in the system client 0000.
A sample excerpt of the Include object HEADER.MVS:
//JMLDS EXEC PGM=&UC_JOBMD,
// PARM='JNR=&UC_REALNR MNR=&UC_CLIENT PNR=&UC_IP_PORT IPA=&UC_IP_ADR
//
TYP=S TXT="
Job started" 2>&1'
A sample excerpt of the Include object TRAILER.MVS:
//JMLDE
EXEC PGM=&UC_JOBMD,COND=EVEN,
// PARM='JNR=&UC_REALNR MNR=&UC_CLIENT PNR=&UC_IP_PORT IPA=&UC_IP_ADR
//
TYP=E STP=&UC_REPORT_STEPS RET=&RETCODE 2>&1'
Note that PARM statements must not exceed 100 characters.
2.0.1 General Start Parameters
There are several parameters that can be assigned to the job messenger. The following table shows the
parameters that apply to all job messengers.
Parameter Description
IPA
The IP address.
JNR
The RunID of the job.
MNR
Client
PNR
The port number.
RET
The return code.
TYP
The type ("S" - start job messenger, "E" - end job messenger)
For the GCOS8 job messenger, the following additional rules apply: "R" - restart, "A" abnormal end, "X" - job messenger stop and "J" - job report from the RSM system.
TXT
This text is subsequently output at the beginning of the job report and in the status text's
detail window.
Note that the parameter TXT= is limited to 32 characters. Use blanks for the first 8
digits because they are reserved for the UC4 Automation Engine. All other digits can be
used for your individual text.
Some job messengers have additional start parameters:
Operating system
Parameter
Description
GCOS8
RFN
The job report's file name.
SNM
The job's sequential number.
SW
The status of the job messenger.
3
4
Chapter 2 Agent's Job Messenger
z/OS
TIMEOUT
The period in seconds after which a timeout occurs for
the connection between the Agent and the job
messenger (default value: 60).
STP
The logging of step return codes.
"0" - No logging (default value) is made.
"1" - The job messenger records return codes.
OS/400
RETRY
The number of connection attempts (default value: 4).
WAIT
The time interval between the individual connection
attempts (default value: 30 seconds).
OUT
The job messenger's message logging.
"0" - No logging (default) is made.
"1" - The Job report also includes Job messenger
messages.
UNIX and VMS
RETRY
The number of connection attempts.
Default value: 3 for UNIX and VMS
TIMEOUT
The period in seconds after which a timeout occurs for
the connection between the Agent and the job
messenger (default value: 60).
WAIT
The time interval between the individual connection
attempts.
Default value: 120 seconds for UNIX and VMS 120.
UNIX and Windows
CMD
The command that should be processed on the agent's
computer.
Within this command, you can also use passwords
that have been encrypted by using a PromptSet object.
To do so, you must specify the PromptSet variable that
includes the value of the encrypted PromptSet text
field. The Job Messenger automatically identifies and
decrypts the passwords.
Note that the Job Messenger does NOT decrypt
passwords that have been encrypted by using
UCYBCRYP.EXE.
You use the message call in the Process tab of the
jobs.
An example for Windows:
&UC_JOBMD CMD="ping localhost"
See also:
Job Includes
Automation Engine
5
3 UC4 and NAT
NATing (Network Address Translation) is a device (e.g, a router) which converts an IP address into a
different one.
There are also NPTs and NAPTs whose ports or addresses and ports can be modified. The following rules
apply:
Connection from an Agent or UC4 client to the UC4 Automation Engine:
1. Every type of IP address can be used without creating a conflict with NAT, NPT or NAPT.
2. The CP selection is more complex because, by default, the IP address and port number of the first
CP are used for the other CPs.
3. It is possible to specify any host name in the parameter "hostname" of the UC4 Automation
Engine's INI file. Thus, NAT is no problem here; NPT and NAPT are not supported.
Connection from an Agent to another one:
1. The UC4 Automation Engine communicates the IP address and port number from one Agent to the
other one (Ex1 to Ex2) or vice versa (Ex2 to Ex1) if it is not possible to establish a connection.
2. Possible NAT problems can be solved via the HOST section of the Agent's INI file. The Agent's
UC4 name is the relevant parameter. Any IP address or DNS name can be specified as the value.
3. NPT and NAPT with port number modifications are also not supported.
6
Chapter 4 External Error Codes
4 External Error Codes
4.1 COBOL - File Error Codes
Original Text From Compiler Description
RT001 Insufficient buffer space. On OS/2, could indicate that the SWAPPATH has not been set
correctly or the SWAPPATH drive is full. Could also indicate an out of memory situation.
RT002 File not open when access tried.
RT003 Serial mode error.
RT004 Illegal file name.
RT005 Illegal device specification.
RT006 Attempt to write to a file opened for input.
RT007 Disk space exhausted.
RT008 Attempt to input from a file opened for output.
RT009 No room in directory (also, directory does not exist).
RT010 File name not supplied.
RT012 Attempt to open a file which is already open.
RT013 File not found.
RT014 Too many files open simultaneously.
RT015 Too many indexed files open.
RT016 Too many device files open.
RT017 Record error: probably zero length.
RT018 Read part record error: EOF before EOR or file open in wrong mode.
RT019 Rewrite error: open mode or access mode wrong.
RT020 Device or resource busy.
RT021 File is a directory.
RT022 Illegal or impossible access mode for OPEN.
RT023 Illegal or impossible access mode for CLOSE.
RT024 Disk I/O error.
RT025 Operating system data error.
RT026 Block I/O error.
RT027 Device not available.
RT028 No space on device.
RT029 Attempt to delete open file.
RT030 File system is read only.
RT031 Not owner of file.
RT032 Too many indexed files, or no such process.
Automation Engine
RT033 Physical I/O error.
RT034 Incorrect mode or file descriptor.
RT035 Attempt to access a file with incorrect permission.
RT036 File already exists.
RT037 File access denied.
RT038 Disk not compatible.
RT039 File not compatible.
RT040 Language initialization not set up correctly.
RT041 Corrupt index file.
RT042 Attempt to write on broken pipe.
RT043 File information missing for indexed file.
RT045 Attempt to open an NLS file using an incompatible program.
RT047 Indexed structure overflow. (Could indicate that you have reached the maximum number of
duplicate keys.)
RT065
File locked.
RT066 Attempt to add duplicate record key to indexed file.
RT067 Indexed file not open.
RT068 Record locked.
RT069 Illegal argument to ISAM module.
RT070 Too many indexed files open.
RT071 Bad indexed file format.
RT072 End of indexed file.
RT073 No record found in indexed file.
RT074 No current record in indexed file.
RT075 Indexed data file name too long.
RT077 Internal ISAM module failure.
RT078 Illegal key description in indexed file.
RT081 Key already exists in indexed file.
RT100 Invalid file operation.
RT101 Illegal operation on an indexed file.
RT102 Sequential file with non-integral number of records.
RT104 Null file name used in a file operation.
RT105 Memory allocation error.
RT129 Attempt to access record zero of relative file.
RT135 File must not exist.
RT138 File closed with lock - cannot be opened.
RT139 Record length or key data inconsistency.
RT141 File already open - cannot be opened.
7
8
Chapter 4 External Error Codes
RT142 File not open - cannot be closed.
RT143 REWRITE/DELETE in sequential mode not preceded by successful READ.
RT146 No current record defined for sequential read.
RT147 Wrong open mode or access mode for READ/START.
RT148 Wrong open mode or access mode for WRITE.
RT149 Wrong open mode or access mode for REWRITE/ DELETE.
RT150 Program abandoned at user request.
RT151 Random read on sequential file.
RT152 REWRITE on file not opened I-O.
RT158 Attempt to REWRITE to a line-sequential file.
RT159 Malformed line sequential-file.
RT161 File header not found.
RT173 Called program not found.
RT180 End-of-file marker error.
RT182 Console input or console output open in wrong direction.
RT183 Attempt to open line sequential file for I-O.
RT188 File name too large.
RT193 Error in variable length count.
RT194 File size too large.
RT195 DELETE/REWRITE not preceded by a READ.
RT196 Record number too large in relative or indexed file.
RT210 File is closed with lock.
RT213 Too many locks.
RT218 Malformed MULTIPLE REEL/UNIT file.
RT219 Operating system shared file limit exceeded.
4.2 COBOL - Runtime Error Codes
Original Text from the Compiler Description
001
Insufficient buffer space (Recoverable) -You have tried to open a file directly or indirectly and,
although you have not exceeded your system's file limit, something in your system is unable
to allocate enough memory space for this operation. -Although you can trap this error you
must do STOP RUN as soon as it is reported.
002
File not open when access attempted (Recoverable) -You have tried to access a file without
opening it first. -Open the file with the open mode that you need and try the operation again. As
this error implies that your program logic contains a mistake, you might want to terminate the
run and recode your program.
Automation Engine
003
Serial mode error (Recoverable) -You have tried to open a device as a relative or indexed file.
You are trying to execute a device, not a program. -Open the device in the correct mode or
close any open files, do STOP RUN and recode your program. The name of your program is
recognized by the operating system as a valid device. Rename your program.
004
Illegal file name (Recoverable) -A filename contains an illegal character. This could be any
character that is not part of the allowed character set or it could be the system-dependent
delimiter, which on most systems is the space. -Try the file operation again using the correct
filename.
005
Illegal device specification (Recoverable) -Devices to which your COBOL program can write
are defined by the operating system. You have tried to write to a device that is not defined by
your system. -Try the operation again using a device name that your system recognizes.
006
Attempt to write to a file opened for INPUT (Recoverable) -You have tried to WRITE to a file
that is open for input only. -Close the file and open it with a mode such as I-O, which allows
you to write to the file. As this error implies that your program logic contains a mistake, you
might want to terminate the run and recode your program.
007
Disk space exhausted (Fatal) -The disk is full. -This error can be trapped, but once it has been
reported you must do a STOP RUN immediately to terminate your program's run. When your
program has terminated, delete any files that you no longer need. Alternately, if your operating
system supports this, put a new disk in a floppy disk drive and redirect your program's file
operations to this.
008
Attempt to input from a file opened for OUTPUT (Recoverable) -You have tried to read from a
file that is open for output only. -Close the file and open it with a mode such as I-O, which
allows you to read from the file. As this error implies that your program logic contains a
mistake, you might want to terminate the run and recode your program.
009
No room in directory (Recoverable) -The system cannot write to the specified directory for one
of the following reasons: -The directory does not exist -The directory is full -Your program
cannot find the directory -Create the directory if it doesn't exist. If the directory is full, either
delete any files that you no longer need or, if your operating system supports this, put a new
disk in a floppy disk drive and redirect your program's file operations to it. Alternately, specify
a different drive or directory for your file operations.
010
File name not supplied (Recoverable) -You have tried to open a file that you have declared as
an external file, but have not named. -Specify the external filename.
012
Attempt to open a file which is already open (Recoverable) -You have tried to open a file which
is already open and so cannot be opened again. -Cancel your second attempt to open the file.
If the fact that the file is already open is acceptable to you, continue to run your program.
013
File not found (Recoverable) -The operating system has been unable to find a file which you
have tried to access in your program. -Ensure that you are in the correct directory or that a
path to the file concerned exists. You can then try the file operation again. If the error is the
result of a spelling mistake then ask for the correct file and try the file operation again.
014
Too many files open simultaneously (Recoverable) -You have tried to exceed the maximum
number of files which you can have open at any one time. This can be a software or an
operating system constraint, but you must not violate it. -Close some of the open files which
you are not currently accessing, and then try to open the relevant file again. You should then
be able to continue to run your program. Depending on your operating system, you might be
able to increase the maximum number of files you are allowed to have open. For example, on
DOS, add the line FILES=128 to your config.sys file. On Novell, add the lines CACHE
Buffers=0 File Handles=128 to your shell.cfg file. See also:/F RTS switch
9
10
Chapter 4 External Error Codes
015
Too many indexed files open (Recoverable) -You have tried to exceed the maximum number
of indexed files which you can have open at any one time. This can be a software or an
operating system restraint, but you must not violate it. -Close some of the open indexed files
which you are not currently accessing, and then try to open the relevant file again. You should
then be able to continue to run your program. (Indexed files count as two files, one for data and
one for the index.)
016
Too many device files open (Recoverable) -You have tried to exceed the maximum number of
device files which you can have open at any one time. This can be a software or an operating
system constraint, but you must not violate it. -Close some of the open device files which you
are not currently accessing, and then try to open the relevant file again. You should then be
able to continue to run your program.
017
Record error: probably zero length (Recoverable) -You have probably tried to access a record
that has had no value moved into it. -Although this error is recoverable in the sense that it can
be trapped, once it has been reported you must execute a STOP RUN statement immediately
and then recode your program to ensure that the COBOL record length is not zero.
018
Read part record error: EOF before EOR or file open in wrong mode (Recoverable) -A part
record has been found at the end of a file. Consequently your run-time system treats the data
file as a record, and not finding a full record, reports this error. -Ensure that the record size you
give when you read from or WRITE to a file is consistent.
019
Rewrite error: open mode or access mode wrong (Recoverable) -You are trying to do a
REWRITE to a file that has not been opened with the correct access mode for this operation. Close the file and reopen it in a mode such as I-O, which allows you to do REWRITE
operations on that file. As this error implies that your program logic contains a mistake, you
might want to close any open files and then execute a STOP RUN. You can then recode your
program to eliminate the logic error.
020
Device or resource busy (Recoverable) -You have tried to open a file that is assigned to a
device or resource (for example, a line printer) that is not available at this time. -You can trap
the error status returned by open and retry the open at regular intervals until it succeeds.
021
File is a directory (Fatal) -You have tried to WRITE to a directory instead of to a file.
Alternately, the attributes are not set up correctly to allow you to access a file. That is, it is
marked as read-only or you don't have sufficient rights to open it. -Recode your program so
that it writes to a file and not to a directory. You need to either change your file access
attributes or recode your program so that it does not violate the existing attributes.
022
Illegal or impossible access mode for OPEN (Recoverable) -The mode in which you are trying
to open a file violates the General Rule of COBOL for that type of file; for example you might
have opened a line sequential file in the I-O mode. -Open the file with a mode that is
compatible with that type of file.
023
Illegal or impossible access mode for CLOSE (Recoverable) -The mode in which you are
trying to close a file is not possible for that type of file. -Close the file with a new access mode
which is compatible with that type of file, or execute a STOP RUN statement and recode your
program.
024
Disk input-output error (Recoverable) -You might have performed a read after a WRITE, or
there might be either a verification failure or a parity error. -In some circumstances this error is
fatal, but if it occurs during a read you can trap it and then do a close on the file before
executing a STOP RUN statement.
025
Operating system data error (Fatal) -You are trying to set up terminal characteristics for a
device which is not a terminal. -Recode your program.
Automation Engine
11
026
Block I-O error (Fatal) -An error has occurred while you are trying to access a disk. This could
be the result of a corrupt disk. -If you have a corrupt disk try to run your program again using
your backup copy.
027
Device not available (Recoverable) -You are trying to access a device which either is not
attached to your machine or if attached is not on-line. -Attach the device to your machine and
ensure that it is on-line. Repeat the file operation.
028
No space on device (Fatal) -You have tried a file operation such as WRITE for which
insufficient space is available on your disk. -When your program has terminated you should
delete some of the files or directories on your current logged in disk. Ensure that you delete
sufficient files on your disk so that you have enough room to carry out successful file
operations.
029
Attempt to delete open file (Recoverable) -You have tried to perform a DELETE FD operation
on an open file. -Close the file before performing the DELETE FD operation.
030
File system is read-only (Recoverable) -The file system which you are using is read-only,
which effectively means that it is write-protected. You have tried to change a file in some way,
for example you might have tried to WRITE to a file or to DELETE information in it. -You
should abandon your attempt to alter the file unless you can make your own personal copy of
it. You should then be able to alter the contents of your copy, but not of the original source.
031
Not owner of file (Recoverable) -You are trying an operation on a file but the file's owner has
not given you the necessary permission for that operation. You could for example be trying to
alter the access modes for a file, which only the file's owner can do. -You should abandon
your tried file operation unless the file's owner gives you the permission necessary to do the
operation you want to carry out.
032
Too many indexed files, or no such process (Recoverable) -You have tried to open an indexed
file but the number of files that you currently have open is the system limit. Alternately, you
could be trying to use a process id which does not exist, or which your operating system no
longer recognizes. -You should close some of the indexed files which you are no longer
accessing, and you should then be able to open the file you require. In this case you must
rewrite your code so that it uses a process id which your system recognizes.
033
Physical I-O error (Fatal) -You have a hardware error of some type. Perhaps you have not put
a disk in the relevant drive or you might have tried to WRITE to a disk but the processor
detected hardware interface has failed.
-You should try to correct the fault in your hardware; for example put a disk in the necessary
drive.
034
Incorrect mode or file descriptor (Recoverable) -You are either trying to write to a file which is
open for read purposes only, or read a file which is open for write purposes only. -You should
close the file and reopen using the correct access mode. As this error implies that your
program logic contains a mistake, you might want to close any open files, execute a STOP
RUN statement and then recode your program to eliminate the logic error. Shareable files
opened INPUT (read-only) by the COBOL system still require write-permission (from the
operating system) to enable temporary locking to take place.
035
Attempt to access a file with incorrect permission (Recoverable) -You are trying a file
operation which you do not have sufficient permission to achieve. For example you could be
trying to write data to a file which has been set up with the read attribute only. -If you are the
owner of the file you can alter the attributes of the file so that you have the permission needed
to effect the particular file operation you were trying. If you are not the owner of the file you
cannot to carry out that operation successfully unless you copy the file and make the changes
to the copy only. You cannot alter the source file.
12
Chapter 4 External Error Codes
036
File already exists (Recoverable) -You are trying an inappropriate operation on an already
existing file. -As this error implies that your program logic contains a mistake, you might like to
recode your program to eliminate this mistake.
037
File access denied (Fatal) -Your attempt to access a file has been denied by the operating
system. You might have tried to write to a write-protected file or you could have tried to read
from an output device. -Alter the access permission on the relevant file. Access can be readonly, if you just want to read the contents of the file without making any changes, or it can be
read and write in which case you can alter its contents.
038
Disk not compatible (Fatal) -You have tried to access a disk that is incompatible with the
current version of your operating system. This could be because it was created under a
previous version of the system or it could have been created under a completely different
operating system. You would also receive this error if you tried to load a disk with a name that
clashed with a disk that was already loaded. -If the error is a result of a clash of names you
can rename one of the disks and then you can load both disks together if this is what you
want.
039
File not compatible (Fatal) -You have tried to access a file that is not compatible with the
structure of files under the current release of your software. This could be because the file
was created either under a different operating system or under a previous version of your
current system. -You should create a new copy of the file which has the correct structure.
040
National Language initialization not set up correctly (Fatal) -You have tried to use the
additional language variants, but the environment or side file that is required to set up the
language either has not been set up correctly, or does not exist, or is invalid. This might be
because you have the LANG environment variable set for use by another system in a format
not recognized by this COBOL system. -Set up the required environment or side file before
you try to run the program again. Use the COBLANG environment variable to set the locale
information for the COBOL system. See the chapter NLS Support in your Programmer's
Guide to Writing Programs.
041
Corrupt index file (Recoverable) -Your run-time system does not recognize the control
information for an indexed file and as the index has been corrupted in some way the data in the
file is no longer accessible by your system. This error is recoverable in the sense that it can be
trapped but should you receive it, you can do little except to close any open files and stop your
program's run. -You should rerun your program using the backup copy of that file. If you have
added a great deal of information to the file since you last took a backup you might like to
rebuild the file using the Rebuild utility, which reads the data (if this has not been corrupted)
and builds a new index for it.
042
Attempt to write on broken pipe (Recoverable) -One of the following has occurred: -Your
program has created a process as a result of a DD_ logical filename mapping assignment (for
example, the process might be a line printer spooler). The process was not created properly,
or has ended prematurely. This error occurs when your program tries to write to the process. Your application has terminated abnormally or prematurely, thus breaking the pipe. -You can
trap the error status returned by the write operation, then open the file again.
043
File information missing for indexed file (Fatal) -The system has crashed on your program's
previous run, while the file was open. Information was probably added to the end of the file,
but the directory information was not updated and so that data cannot be accessed by your
system. Alternately, you have copied the indexed file from one disk to another but have
copied either only the data part of the file or only the index. -If the error is the result of a crash
then whether you can access the necessary data or not is entirely system dependent. If,
however, it is the result of a faulty copy you should be able to restore the missing part of the
file from the.dat or .idx file.
Automation Engine
13
044
Attempt to OPEN an NLS file in a non-NLS program (Fatal)
-The logical filename is preceded by "%NLS%", but the program which OPENS the file has
been compiled without the NLS directive set: the OPEN fails.
045
Attempt to OPEN an NLS file using incompatible language definition (Fatal) -The NLS control
information for a file in your program does not match the same NLS control information in the
header of your index file. Alternately, your index file has become corrupted. -Rebuild your
index file, or rerun your program using the backup copy of that file. If you have added a great
deal of information since you last took a backup, you might want to rebuild the file using a
utility that is able to read the data, if it is not corrupt, and build a new index for it.
046
NLS support module not found (Fatal) -Your system could not find the National Language
Support module COBNLSMG. Alternately, your system cannot find cobnls.dll (OS/2),
cobnls.dle (DOS), or cobnls.dlw (Windows). -Ensure that cobnlsmg.gnt is present in either
utils.lbr or in a directory on COBDIR, or, if your program is linked, ensure that cobnlsmg.obj is
linked in to it. Ensure that cobnls.dle is present in utils.lbr , or that cobnls.dlw is present in a
directory specified in COBDIR, or that cobnls.dll is present on the LIBPATH.
047
Indexed structure overflow (Fatal) -The structure of your indexed file contains a fault. You
have probably tried to put another entry in the index when there is no room for it. Alternately,
you have tried to access an old format indexed file, created perhaps using CIS COBOL. -If
your index has no room for further entries you should reorganize your file. If you have tried to
access an old format indexed file, you can run the Rebuild utility to check the consistency of
this indexed file, and to construct a new indexed file if the old one was found to be corrupt.
See your Programmer's Guide to File Handling for details of the Rebuild utility.
048
Attempt to divide by zero (Fatal) -You are executing a program that is trying to perform a fixedpoint divide by zero. Alternately, if you have COBFSTAT environment variable set to
HOSTSTAT, this could be mainframe file status code "90". -Either recode your program so
that you can trap the error with an ON SIZE ERROR clause, or run your program without the
RTS O switch set, or recompile your program without the CHECKDIV"OSVS" directive set.
048-057 Host file status, not an RTS message -If you have COBFSTAT environment variable set to
HOSTSTAT, this is a mainframe file status code "9x", where x is given by subtracting 48 from
the error number.
055
Routine table overflow (Fatal) -You have tried to load too many programs simultaneously.
Alternately, if you have COBFSTAT environment variable set to HOSTSTAT, this could be
mainframe file status code "97". -Cancel any programs that you are no longer using, or use
fewer separate programs.
065
File locked (Recoverable) -You have tried to open a file which has already been locked, or
opened for output by another user. Alternately, you have tried to lock or open for output a file
which another user already has open. -Your program can inform the system operator (if there
is one) that it is unable to access this file and should wait until the other user has finished
using the file and closes it. You should then be able to continue to run your program.
066
Attempt to add duplicate record key to indexed file (Fatal) -You have tried to add a duplicate
key for a key which you have not defined as being able to have duplicates. -As this error
implies that your program logic contains a mistake, you probably should recode.
067
Indexed file not open (Recoverable) -You are trying to access an indexed file which you have
not opened. -Open the file in the relevant access mode and then retry the unsuccessful file
operation.
14
Chapter 4 External Error Codes
068
Record locked (Recoverable) -You have tried to access a record which is currently locked by
another user. -Your program can inform the system operator (if there is one) that the record is
currently locked, and you should then wait until the other user has released the lock on that
record. You should then be able to access the relevant record. You should not continually retry
to gain access to the record without operator intervention, as this could result in your
application hanging.
069
Illegal argument to isam module (Fatal) -This is the result of an internal system error. -Contact
Technical Support who will help you find the cause of your error and how it can be rectified.
070
Too many indexed files open (Recoverable) -You are trying to open an indexed file but you
have already exhausted the system limit which specifies how many of these files can be
opened at any one time. -Close some of the open indexed files which you are not currently
accessing. You should then be able to open the indexed file which you require and to continue
the program run.
071
Bad indexed file format (Fatal) -You are either using a file which has been corrupted, or there is
an internal system error. -If the disk you are using is corrupt, rerun your program using your
backup copy of the disk. If this is not the cause of the error then you should contact Technical
Support who will help you find the cause of your error and how it can be rectified.
072
End of indexed file (Fatal) -This is the result of an internal system error. -Contact Technical
Support who will help you find the cause of your error and how it can be rectified.
073
No record found in indexed file (Fatal) -This is the result of an internal system error. -Contact
Technical Support who will help you find the cause of the error and how it can be rectified.
074
No current record in indexed file (Fatal) -This is the result of an internal system error. -Contact
Technical Support who will help you find the cause of the error and how it can be rectified.
075
Indexed data file name too long (Fatal) -When creating indexed files, the extension .idx is
added to the user-defined filename, and so your filename must not exceed x-4 characters in
length, where x is the maximum length of filename. See your Programmer's Guide to File
Handling for details. -Rename the file with a shorter filename, that is, one that is less than 10
characters in length.
076
Can't create lock file in /isam directory (Fatal) -For some reason your system is unable to
create a lock file in the /isam directory. One reason for this could be that in its previous run
your program terminated abnormally (perhaps due to a power failure) leaving some files
locked. -You should manually remove all of the files that are still locked from the /isam
directory before you can successfully run your program.
077
Internal ISAM module error (Fatal) -This is the result of an internal system error. -Contact
Technical Support who will help you find the cause of your error and how it can be rectified.
078
Illegal key description in indexed file (Fatal) -This is the result of an internal system error. Contact Technical Support who will help you find the cause of your error and how it can be
rectified.
079
COBCONFIG syntax error (Fatal) -An error exists in the run-time configuration sidefile
accessed via the environment variable COBCONFIG. -Check your syntax against your
Object COBOL User Guide. You might have used incorrect syntax, or syntax that is not
compatible with the type of RTS tuneable you are configuring (this could include assigning an
illegal value to the RTS tuneable).
081
Key already exists in indexed file (Fatal) -This is the result of an internal system error. Contact Technical Support who will help you find the cause of your error and how it can be
rectified.
082
CALL convention not supported (Fatal) -The CALL convention you have specified is not
supported. -See your Object COBOL User Guide for a list of supported CALL conventions.
Automation Engine
15
086
Remote file system failure (Fatal)
099
Illegal operation in SORT/MERGE module (Fatal) -A SORT or MERGE module has received
a RELEASE operation outside the Input procedure, or a RETURN operation either outside the
Output procedure, or before the Input procedure has terminated correctly. -Recode your
program so that RELEASE and RETURN operations are issued by the appropriate
procedures.
100
Invalid file operation (Fatal) -You have tried a file operation which violates a general rule of
COBOL in some way. The most likely cause of this error is that you have tried a rewrite on a
sequential file opened I-O, or on a relative file with access mode sequential also opened I-O,
without preceding it with a successful read NEXT. -Recode your program to ensure that the
REWRITE statement in error is preceded by a read NEXT.
101
Illegal operation on an indexed file (Fatal) -This is the result of an internal system error. Contact Technical Support who will help you find the cause of your error and how it can be
rectified.
102
Sequential file with non-integral number of records (Fatal) -You have either specified an
incorrect record length for a sequential file, or the sequential file you are trying to access is
corrupt in some way, or the file which you have specified is not a sequential file. -Recode your
program so that it specifies the correct type of file, or if the error is the result of a corrupt file,
try to run the program again using a backup copy of that file.
103
Parameter cannot be passed BY VALUE (Fatal)
104
Null file name used in a file operation (Fatal) -You specified a data-name for a filename instead
of a literal, and the data item contained only spaces when you tried to open the file. -Recode
your program specifying the correct filename.
105
Memory allocation error (Fatal) -The run-time system is unable to allocate sufficient memory
space to successfully carry out the tried operation, probably because of insufficient memory
space on your system. -You should obtain more memory in which to run your program. Refer
to your operating system documentation for details of how you can obtain more memory, if
this is possible.
106
Dictionary error (Fatal) -This could be the result of a read or write error to file or disk, but it is
more likely to be the result of an internal system error. Alternately, your application might have
called many programs without canceling them afterward, so that memory becomes exhausted
during Animation. -Contact Technical Support who will help you to find the cause of your error
and how it can be rectified. Ensure that as much memory as possible is available during
Animation by canceling any program you do not currently need to access.
107
Operation not implemented in this run-time system (Fatal) -You are trying to perform a file
operation which your run-time system does not support. -You should recode your program so
that it does not try such operations, or you should acquire a version of your system that does
support this facility.
108
Failure to initialize data division (Fatal) -The run-time system cannot load your program
properly because the data needed to correctly initialize the Data Division has become
corrupted. -You should compile your program again to try to obtain good intermediate code.
109
Invalid checksum in run-time system (Recoverable) -The internal information in the run-time
system has been altered. The run-time system might have become corrupted, or you might
have illegally tried to change the internal run-time system information.
110
Generated code not supported by this RTS (Fatal) -Contact Technical Support who will help
you to find the cause of the error and how it can be rectified.
16
Chapter 4 External Error Codes
111
Incompatible Class Library and Run-time Environment versions (Fatal) -The version numbers
for these components do not match. -Check that you have fully installed both the Class
Library and the Run-time Environment from the same version of Object COBOL. If you have
more than one version installed, check that your PATH, LIBPATH, and COBDIR environment
variables specify an appropriate path for the version you are using.
112
Unable to locate/access the required security key (Recoverable) -The run-time system cannot
locate or cannot access the coded security key (dongle) that is required to execute this
application. -Connect the security key that was supplied with your COBOL system to the
parallel port of your computer, then re-run the application.
114
Attempt to access item beyond bounds of memory (Fatal) -Memory access violation has been
detected by your operating system.
115
Unexpected signal (Fatal) -A signal the run-time system was not expecting has been caught.
116
Cannot allocate memory (Fatal) -For some reason a part of your run-time system is unable to
allocate you sufficient memory to enable you to execute your code. -You should try to reduce
memory usage by canceling programs that are not in use, then try the operation that caused
this message again.
117
Bad collating sequence (Fatal) -This is an internal system error. -Please contact Technical
Support who will help you to find the cause of the error and how it can be rectified.
118
Symbol not found (Fatal) -You are unable to load your object file. You have tried to call a
program that has not been specified in the COBPATH environment variable. -Check that your
COBPATH has been set up correctly. If not, revise your COBPATH to include the program
being called.
119
Symbol redefined (Fatal) -The RTS has detected a symbol (for example, data item, entry point
or module name) which is already defined. -You can recode your application to remove the
naming duplication. If you are not linking with a non-COBOL function, you can use the -e RTS
switch (32-bit RTS only).
120
Symbol string table of zero size (Fatal) -You probably have a malformed object file. -Once the
program has terminated you must correct your object file. If this does not work, contact
Technical Support who will help you to find the specific cause of the error.
121
Symbol is not in TEXT section (Fatal) -You have tried to call a subprogram that is not an
executable program. Alternately, you have used the same name for a called program as for a
previously defined data item. -Check that the subprogram being called is an executable one. If
required, correct the subprogram's name in the calling program and resubmit it to your COBOL
system. Once your program has terminated, recode it to remove the naming duplication.
Resubmit your program to your COBOL system.
122
Coblongjmp() called below level of cobsavenv() (Fatal) -You might have returned control to a
higher level in the CALL/PERFORM hierarchy than the level at which cobsetjmp was called.
Coblongjmp must be called only from the same or from a lower level in the CALL/PERFORM
hierarchy as cobsavenv was. See your Object COBOL User Guide for details of cobsavenv
and coblongjmp.
123
Unknown relocation type (Fatal) -You are using incompatible versions of the object file and the
COBOL run-time library. -Once the program has terminated, resubmit your object file to your
COBOL system with the current version of your COBOL run-time library. If this does not work,
contact Technical Support who will help you to find the specific cause of the error.
124
Communication failure during I/O request to the central file handler
125
All locks/ current transactions canceled due to exceeding time limit
126
Record size exceeds system limit (Fatal)
Automation Engine
17
129
Attempt to access record zero of relative file (Recoverable) -The value specified in the
RELATIVE KEY data item contains the value zero. -You should ensure that the value in the
RELATIVE KEY data item is greater than zero, then continue to run your program.
135
File must not exist (Recoverable) -The operating system has been unable to find a file which
you have tried to access in your program. -Ensure that you are in the correct directory or that a
path to the file concerned exists. You can then try the file operation again. If the error is the
result of a spelling mistake then ask for the correct file and try the file operation again.
137
Illegal device specification - not mass storage
138
File closed with lock - cannot be opened (Recoverable) -You are trying to open a file which you
previously closed with lock, which violates one of the general rules of COBOL programming. You cannot open the relevant file. As this error implies that your program logic contains a
mistake, you might want to close any remaining open files, execute a STOP RUN statement
and recode.
139
Record length or key data inconsistency (Recoverable) -A discrepancy exists between the
length of a record, or the keys which you have specified, in your current program and its
definition in the program in which it was first opened. -Your program has a fault, so you
probably should edit your code, then resubmit it to your COBOL system before running it
again.
141
File already open - cannot be opened (Recoverable) -You have tried to open a file which is
already open and so cannot be opened again. -Cancel your second attempt to open the file
and continue to run your program if the fact that the file is already open is acceptable to you.
However as this error implies that your program logic contains a mistake, you might want to
close any open files, execute a STOP RUN statement and then recode.
142
File not open - cannot be closed (Recoverable) -You have tried to close a file which is not
open. -You can abandon your attempt to close the relevant file and continue to run your
program. However, as this error implies that your program logic contains a mistake, you might
want to close any open files, execute a STOP RUN statement and then recode.
143
Rewrite/delete in sequential mode not preceded by successful read (Recoverable) -You have
failed to do a successful read on a sequentially accessed file trying a REWRITE or DELETE
on some of the information contained in that file. -If the previous read was successful then
perform a read on the relevant file before you retry the unsuccessful REWRITE or DELETE
operation. If the previous read was also unsuccessful close the file, execute a STOP RUN
statement and then recode your program before you next run it.
144
Boundary violation (Recoverable) -You have tried to write a record to a variable length record
file, the length of which is not within the defined range for that file. -Recode your program.
146
No current record defined for sequential read (Recoverable) -The file position indicator in your
file is undefined owing to a failed read/START or INVALID KEY condition. You have tried to
read another record in the file but as the current record is undefined the system cannot find the
start of the record for which you have asked. -You should try a START operation, and
continue to do so until the file position indicator is updated successfully.
147
Wrong open mode or access mode for read/start (Recoverable) -You have tried to carry out a
read or start operation on a file which has not been opened for INPUT or I-O, or which is not
open at all. -Open the file for I-O or for INPUT and you should then be able to continue to run
your program. However, as this error implies that your program logic contains a mistake, you
might want to close any files which are open, execute a STOP RUN statement and then
recode.
18
Chapter 4 External Error Codes
148
Wrong open mode or access mode for write (Recoverable) -You have tried to write to a file in
sequential access mode that you have not opened for OUTPUT or EXTEND, or you have
tried to write to a file in random or dynamic access mode that has not been opened INPUT or
I-O, or which is not open at all. -Close the file and reopen it with the correct open mode for the
file type. However, as this error implies that your program logic contains a mistake, you might
want to close any files that are open, execute a STOP RUN statement and then recode.
149
Wrong open mode or access mode for rewrite/delete (Recoverable) -You are trying to do a
REWRITE or a DELETE on a file that you have not opened for I-O, or which is not open at all.
-Close the file and reopen for I-O. However, as this error implies that your program logic
contains a mistake, you might want to close any open files, execute a STOP RUN statement
and then recode.
151
Random read on sequential file (Recoverable) -You are trying to do a random read on a file
which has sequential organization. -Read the file with the correct access mode. As this error
implies that your program logic contains a mistake, you might like to close any files which are
open, execute a STOP RUN statement and recode.
152
REWRITE on file not opened I-O (Recoverable) -You have tried a REWRITE on a file that is
not open I-O. -Close the relevant file and open it for I-O operations. You should then be able to
carry out the REWRITE operation successfully. However, as this error implies that your
program logic contains a mistake, you might want to close any open files, execute a STOP
RUN statement and then recode.
153
Subscript out of range (Fatal) -A subscript which you have used in your program is out of the
defined range, that is, it is either less than one or it is greater than the number of occurrences
of the item. -You should recode your program.
154
PERFORM nested too deeply (Fatal) -This error usually results if you have used GO TO to
jump out of the range of a PERFORM rather than to jump to an EXIT statement at the end of
its range. -When your program has terminated you should to recode your program to ensure
that the GO TO in question jumps to an EXIT statement at the end of the PERFORM's range.
155
Illegal command line (Fatal) -The run-time system does not recognize as valid the command
line format you have specified. Alternately, the generic command-line interpreter, which must
be present if your program is to be run successfully, is not found on your system. Alternately,
you have set an invalid COBSW value. -Rerun your application with a valid command line.
Ensure that the interpreter is present to enable your system to pick up the commands
correctly and then rerun your program. Reset COBSW to a valid value.
156
Too many parentheses in compute statement (Fatal) -You have coded a COMPUTE
statement which is too complex for your system to handle successfully. -You should recode
your program. We strongly advise you to break the relevant COMPUTE statement into a
number of simpler statements.
157
Not enough program memory: object file too large to load (Recoverable) -Either your program
is too large for the available memory space, or the stack is full. -If you have specified the ON
OVERFLOW/EXCEPTION clause in the relevant CALL statement, the error is recoverable.
Any associated imperative statement is executed before the next instruction.
158
Attempt to REWRITE to a line-sequential file (Recoverable) -You have used the REWRITE
statement in conjunction with a file whose organization is line sequential. The REWRITE
statement cannot be used with line sequential files. -Close the file in error before executing a
STOP RUN statement to ensure that you do not lose any data from it. Recode your program
to make the organization of the file to which you want to do a REWRITE either sequential,
indexed sequential, or relative.
Automation Engine
19
159
Malformed line-sequential file (Recoverable) -A line-sequential file which you are trying to
access is corrupt in some way. -Rerun your program using the backup copy of that file.
160
Overlay loading error (Recoverable) -An error has occurred while trying to load the
intermediate code for an independent segment. The segment is either missing or corrupted in
some way. -If the segment is missing, locate it. If you cannot find it, or if it is present and
corrupt, resubmit your program to your COBOL system.
161
Illegal intermediate code (Fatal) -The intermediate code which is currently being processed is
not valid code. You are probably trying to execute a corrupted file or one which has not been
submitted to your COBOL system successfully. -You should resubmit your source program to
your COBOL system, to try to obtain uncorrupted intermediate code.
162
Arithmetic overflow or underflow (Fatal) -You are executing a program that is trying to perform
a floating-point divide by zero. -You should recode your program to avoid this illegal operation.
163
Illegal character in numeric field (Fatal) -By default the value which you enter into a numeric or
numeric edited field is checked to ensure that it is numeric. You have entered either
nonnumeric characters or uninitialized numerics into numeric or numeric edited fields: these
are automatically space filled and are thus classified as nonnumeric items. -You must adjust
your code so that no invalid data is used. You can locate the invalid numeric data in your code
by setting the +F switch on, and animating your program until you receive this error. You might
need to use one of the Compiler directives, BADSIGNS, HOST-NUMCOMPARE,
SIGNCOMPARE or SPZERO, to resolve invalid data in numeric fields. See your Object
COBOL User Guide for details of these directives.
164
Run-Time subprogram not found (Fatal) -You have tried to call a subroutine whose entry
address has not been set up in your run-time system. -Check to see that you used a valid call
number in the unsuccessful subroutine call. If not, revise your code to contain a call number
which your system recognizes. If you did use a valid call number but still received this error
you should contact Technical Support.
165
Version number incompatibility (Fatal) -One or more of the run-time support modules is
incompatible with the run-time system you are using. The name of the incompatible support
module is displayed. Alternately, the run-time system you are using is incompatible with the
version of your COBOL system. Either "RTS" or the name of the run-time system file is
displayed: coblib.dll (OS/2), coblib.dle (DOS) or coblib.dlw (Windows). -Reinstall the support
module, using your installation disks. Reinstall the run-time system file, using your installation
disks. If no support module name is displayed, you have done one of the following: -Used
intermediate code which has been produced on a version of your COBOL system that is
incompatible with the run-time system you are using. Your RTS, therefore, cannot execute
correctly any generated code you are producing or have already produced from this
intermediate code. -Tried to execute a file which is not your COBOL system's intermediate or
generated code.
166
Recursive COBOL CALL is illegal (Fatal) -You have tried to call a COBOL module that is
already active. -You should recode your program.
167
Too many USING items (Fatal) -The list of items which you have supplied in a
CALL....USING statement is longer than the run-time system can handle. -Once your
program has terminated recode it with group items rather than elementary items before
rerunning it.
20
Chapter 4 External Error Codes
168
Stack overflow (Fatal) -You have nested a PERFORM statement or a series of CALL
statements too deeply. Alternately, if you have specified the CHECKSTACK directive when
compiling your program, an incorrect number of parameters might have been used on a call,
and as a result the stack has been corrupted. -Edit your program to reduce the number of
levels in the nested PERFORM or CALL statement. If the CHECKSTACK directive has been
used, determine which call is at fault and edit the source to provide the correct number and
size of parameters.
169
Illegal configuration information (Fatal) -You have tried an operation for which your machine is
not configured; the most likely cause of this is that Adis is not configured correctly. -Check
that Adis is configured correctly. See your Programmer's Guide to Creating User Interfaces
for details of how you can reconfigure Adis.
170
System program not found (Fatal) -A system program, for example Adis or ExtFH, is not
present on the current logged-in drive. -Ensure that all the system programs are available on
the logged-in drive and copy those which are not currently present using your backup system
disk. Once all the necessary system programs are available you can run your program.
171
Japanese operations illegal with this RTS (Fatal) -You are trying to perform Japanese
operations with a non-Japanese run-time system, or you have used a Japanese version of
your COBOL system to produce code which you are now trying to run using a non-Japanese
run-time system. -You should resubmit your program using a non-Japanese run-time system,
or if you still want your program to perform Japanese operations, you should acquire a
Japanese run-time system.
172
Recursive non-MF PERFORM is illegal (Fatal) -You have tried full recursion of a PERFORM
statement in a program that was submitted to your COBOL system with the OSVS parameter
of the PERFORM-TYPE directive specified. That is, you have tried to end two PERFORMs
with the same return address. -You should either resubmit your program to your COBOL
system with a parameter other than OSVS specified for the PERFORM-TYPE directive, or
recode your program so that each PERFORM has its own unique return address before you
resubmit it to your COBOL system with the MF parameter of the PERFORM-TYPE directive
specified.
173
Called program file not found in drive/directory (Fatal) -You have tried to call a program which
is not present on your current logged-in drive or directory, or in a directory pointed to by the
COBDIR environment variable. -Once your program has terminated you should copy the
relevant file into your logged-in drive or directory. If insufficient space is available, you should
set the COBDIR environment variable to search the directory or drive on which the file is
present when your program calls it. Once you have taken these steps, run your program
again.
174
Imported file not found (Fatal) -You have tried to load a .dll file which contains references to
another .dll file which cannot be found by the operating system. -Locate the missing file and
ensure it is located on the default search path for your operating system.
175
Attempt to run intermediate code program which had severe errors in it (Fatal) -You are trying
to run a program that produced severe faults when you submitted it to your COBOL system
with the run-time switch E turned off. Alternately, you could try to run the program with the E
run-time switch set, though this might not give the desired results. -You should edit your
source code to correct all the severe faults, resubmit it to your COBOL system, then run the
intermediate code that is produced. When your program is being animated, Animator reports
this error and enables you to continue to run the program. See also: E RTS switch
176
Illegal intersegment reference (Fatal) -You might have a corrupted file. Alternately, your code
contains a segment reference for the Forward Reference Table which is illegal. -Resubmit
your source code to your COBOL system. If you receive this error again, contact Technical
Support who will help you to find the specific cause of the error.
Automation Engine
21
177
Attempt to cancel program failed (Fatal) -You have tried to remove a currently executing
program or its parents or grandparents, from memory. Alternately, you have tried to cancel a
DLL, either directly or indirectly as an imported DLL, that contains an entry point which has
been registered as an EXIT LIST function via the OS/2 API call DosExitList. -Once your
program has terminated you need to recode your program to ensure that you do not try to
cancel a program (or its parents or grandparents) while it is still being executed. Locate the
erroneous DLL and ensure that the EXIT LIST function is removed before you cancel the DLL.
If you cannot recode the DLL, you can set the O RTS switch to force a logical cancel on the
DLL. See also:D2 RTS switch O RTS switch
178
Error during save (Fatal) -You cannot save the information which your program has generated.
This can be caused by several different reasons but one of the most common causes is that
you have tried to Build a module that is too large for the available memory space. -If the error
is caused by a lack of space you can either delete some of the files which you no longer need
on your current disk, or insert a new floppy disk to take the output from your program. You
should then be able to rerun your program and save the information given by it.
179
Error during chain (program not found) (Fatal) -You have tried to chain to another program
which your system is unable to find. -Once your program has terminated you should copy the
relevant file into your logged-in drive or directory. If insufficient space is available, you should
set the COBDIR environment variable to search the directory or drive on which the file is
present when your program calls it. Once you have taken these steps, run your program
again.
180
End-of-file marker error (Fatal) -A file-marker used to indicate that the end-of-file has been
reached is missing from one of your files. -You should resubmit your code to your COBOL
system, or use a debugger to place the end-of-file marker at the end of the file. You can then
rerun your program.
181
Invalid parameter error (Fatal) -A parameter which you have used is not one which is
recognized by your system. You have probably used a parameter for a run-time system
subprogram which is not in the first 64K of the Data Division. -Revise your code to contain a
parameter which is known by your system. That is, ensure that the parameter is in the first
64K of the Data Division.
182
Console input or console output open in wrong direction (Fatal) -You are either trying to read
input from the screen or write to the keyboard. -You should recode your program.
183
Attempt to open line sequential file for I-O (Fatal) -You have tried to open a line-sequential file
in the input-output open mode, but this mode is not supported for files with this organization. When your program has terminated you should recode your program to ensure that the file
with organization line sequential is opened for input, output, or extend. You can then rerun
your code.
184
ACCEPT/DISPLAY I-O error (Fatal) -You have either tried to read input from the screen or
write to the keyboard, or the ADIS module has not been able to open your terminal's channels
for I-O. -Your program logic contains a mistake, so you must recode.
185
File malformed (Recoverable)
186
Attempt to open stdin, stdout or stderr with incorrect mode (Recoverable) -You have tried to
open either a standard input file with output mode, or some other file in an incorrect mode.
187
Run-time system not found on $COBDIR path (Fatal) -The run-time system cannot be found
on the path you have set up in the COBDIR environment variable. Alternately, you might not
have installed your COBOL system correctly. -Ensure that the run-time system is on the path
you have set up in the COBDIR environment variable. Alternately, ensure that your COBOL
system has been installed correctly. If it has not, you must reinstall your COBOL system.
22
Chapter 4 External Error Codes
188
Filename too large (Fatal) -A filename which you have used has more characters than the
maximum number allowed by your operating system. -You should recode your program to
check the length of the file in error, and rename it with a shorter filename. You can then run
your program again.
189
Intermediate code load error (Fatal) -You are unable to load your intermediate code. You might
have tried to load intermediate code that either has not been successfully produced, or has
been corrupted in some way. -Try to obtain good intermediate code, for example, by
resubmitting (or submitting) your source code to your COBOL system. You should then be
able to load your code and run the program successfully.
190
Too many arguments to CALL (Fatal) -A CALL statement in your program cannot be
successfully executed because of the number of arguments which you have used with it. When your program has terminated you can recode it using group items rather than
elementary ones. You should then be able to run your program successfully.
191
Terminal type not defined (Fatal) -Your terminal type is undefined, so your operating system is
unable to drive your terminal. -Set up the necessary environment for your terminal.
192
Required terminal capability description missing (Fatal) -A compulsory entry, for example
cursor movement or clear screen, is missing from your terminal configuration database. -Add
the missing entry to your terminal configuration database.
193
Error in variable length count (Fatal) -The intermediate code which is currently being
processed is not a valid operation. You are probably trying to execute a corrupt file or one
which has not been produced. -You should resubmit your source code to your COBOL
system.
194
File size too large (Fatal) -A file which your program is accessing is too large for successful
execution to continue. -When your program has terminated you should recode your program
spreading the data over more than one file to ensure that no file becomes too large for your
operating system to handle. Having recoded your program you can then rerun it.
195
DELETE/REWRITE not preceded by a read (Fatal) -Before a DELETE or a REWRITE
statement can be successfully executed in sequential access mode the last input-output
statement executed for the associated file must have been a successful read. In your code no
read statement precedes your tried DELETE or REWRITE. -When your program has
terminated, recode your program, making sure that the last input-output statement to be
executed before the DELETE or REWRITE is a READ statement.
196
Record number too large in relative or indexed file (Fatal) -The relative record key has
exceeded the system limit, that is, the file is too large for the system to handle. Alternately,
the record key which you have specified is too large for the system to deal with successfully,
or the pointer to the record has been corrupted in some way so that it is either too large or it is
not a multiple of the record length.
197
Screen handling system initialization error (Fatal) -This error can be caused by one of the
following: -Your display adapter is in the wrong mode. -Your screen handling interface has not
been correctly initialized because your terminal does not have the required capabilities. -Your
terminfo file is corrupted. -Memory has been incorrectly allocated. -If you are using a DOS or
OS/2 system, the monitor must be in alphanumeric display mode rather than graphics display
mode. You can set the display mode to a valid alphanumeric mode by using the DOS MODE
utility and then rerunning your program. If you are using a UNIX-type system, you must check
that your terminfo file contains the correct entry for your terminal. If your terminfo file is
corrupt, or your screen handling interface has not been correctly initialized, you must advise
your system administrator of the problem, and he will take steps to try to correct it. If your
memory has been incorrectly allocated, you must rerun your program.
Automation Engine
23
198
Load failure (Fatal) -The system cannot load a program, usually because of insufficient
memory. Alternately your program has run out of memory during the loading or reloading of a
file. This occurs more frequently during Animation because of the extra memory required
during Animation. -Make more memory available and then rerun your program. Ensure that as
much memory as possible is available during Animation by canceling any program you do not
currently need to access.
199
Operating System error code lies outside expected range (Fatal) -A system call has returned
an unexpected error number which is not documented. -Contact Technical Support who will
help you to find the specific cause of this error.
200
Run-time system internal logic error (Fatal) -The amount of memory available on your machine
is so low that not even the run-time system can be fully loaded. Alternately, your run-time
system has stopped as a result of an internal logic error from which you cannot recover. -Free
some memory and then you should be able to run your program successfully. Contact
Technical Support who will help you to find the cause of the error.
201
I-O error in paging system (Fatal) -No room is available in your current directory or on the
floppy disk which you are using, for the paging file. -When your program has terminated,
delete any files which you no longer need from your directory to make room for the paging file,
or insert a new floppy disk.
202
Exported functionality error (Fatal) -You have either caused an internal run-time system error
by invalid use of an exported function, or the code produced by a preprocessor in your COBOL
system contains errors. -Ensure that all of your external assembler applications call and use
run-time system functions correctly before you try to run your program again. If you are using
a preprocessor as part of your COBOL system, you should use the software as a standalone
preprocessor to isolate the problem areas.
203
CALL parameter not supplied (Fatal) -The item you are trying to access in the Linkage Section
of the currently executing program has not been initialized. -Recode your program to ensure
that it contains all of the necessary parameters, or check that it is a valid caller.
206
Reading unwritten data from memory (Fatal) -You are trying to read data which has not been
written, from the core file.
207
Machine does not exist (Recoverable) -You have tried to access a machine that is not
connected to your network, or which is not on-line. -Make sure the machine is connected to
the network and is on-line, then try to access it again.
208
Error in multi-user system (Fatal) -This is normally caused by an unexpected error occurring in
the network or file-sharing facilities. A corrupted network message also causes this error to be
returned. -Retry the unsuccessful operation. If the error persists, contact Technical Support
who will help you to find the specific cause of this error.
209
Network communication error (Recoverable) -This is normally given if an incorrect checksum
has been received in a communications packet. -Your program should continue to execute
after you have received this error but results might be undefined.
210
File is closed with lock (Fatal) -You have tried to open a file which you have previously closed
with lock. -Recode your program to avoid opening a file which has previously been closed with
lock.
211
Program not executable by run-time system (Fatal) -You have tried to run a program that is
incompatible with the current version of either your run-time system, your object file or your
COBOL run-time library. For example, your run-time system does not run a program linked
using a different object file format or COBOL run-time library. -If your object file is
incompatible with the current version of either your COBOL run-time library or your run-time
system, you should relink with the current version of your COBOL run-time library.
24
Chapter 4 External Error Codes
213
Too many locks (Recoverable) -You have either tried to exceed the maximum number of
simultaneous record locks per file you can have, or you have exhausted an operating system
or network resource, for example dynamic memory. -Execute a COMMIT or an UNLOCK
operation on the relevant file and you should then be able to continue to run your program. You
should try not to retain a record lock for longer than is necessary.
214
GO TO has not been ALTERed (Fatal) -You have violated one of the general rules of COBOL
programming. -Close any files which might be open, execute a STOP RUN statement and
then edit your program to avoid such illegal operations.
215
Cannot ANIMATE a program running COMMUNICATIONS (Fatal) -You have tried to animate
a program which makes use of the communications module. This cannot be done as both
Animator and the communications module need full use of the CRT. -You should run your
program without the aid of Animator.
216
Cannot initialize the named communications device (Fatal) -A device driver is probably
missing. -Ensure that all communications drivers are loaded before you try to run
Communications.
217
Incompatible host for native code file (Fatal) -The .gnt file is not valid for the host processor. You must resubmit your program to your COBOL system.
218
Malformed MULTIPLE REEL/UNIT file (Fatal) -Either your file header is not correctly
formatted, or you are not using a MULTIPLE REEL/UNIT file. -You should try to run your
program again using a backup copy of the relevant file.
219
Operating system shared file limit exceeded (Recoverable) -You have tried to exceed your
operating system's limit on the number of shared files that you can have open simultaneously.
As this figure is operating system dependent, you should consult your Release Notes for
details of how many shared files your system permits to be open at any one time. -Close
some of the open shared files you are no longer accessing and retry the file operation.
220
Attempt to execute more than one SORT or MERGE simultaneously (Fatal) -You have coded
your program in such a way that it is trying to execute more than one SORT or MERGE
operation at the same time. For example, you might have coded a SORT statement in the
input or output procedure of another SORT statement, an operation that is specifically
prohibited under the rules of ANSI COBOL. -You should recode your program to ensure that it
does not execute more than one SORT or MERGE at any one time.
221
SORT/MERGE error: see status keys (Fatal) -You have tried a SORT/MERGE operation
which has been unsuccessful for some reason. You might have had too many files open when
you tried a SORT/MERGE operation, or the file which you are trying to access might be
locked. -The action you should take depends on the situation in which it occurs. Check the
status of each file (USING/ GIVING) defined in the SORT statement.
222
SORT/MERGE error: see status keys (Fatal) -You have tried a SORT/MERGE operation
which has been unsuccessful for some reason. You might have had too many files open when
you tried a SORT/MERGE operation, or the file which you are trying to access might be
locked. -The action you should take depends on the situation in which it occurs. Check the
status of each file (USING/ GIVING) defined in the SORT statement.
223
SORT/MERGE error: see status keys (Fatal) -You have tried a SORT/MERGE operation
which has been unsuccessful for some reason. You might have had too many files open when
you tried a SORT/MERGE operation, or the file which you are trying to access might be
locked. Alternately, you have set the TMP environment variable to point to a directory that
does not exist. -The action you should take depends on the situation in which it occurs. Either
set TMP to point to a directory that does exist, or unset TMP.
224
External Language Initialization failure
Automation Engine
25
225
Dynamic load error - program component missing (Fatal) -The run-time system cannot locate
the root or overlay of a program that is currently loaded in memory. Alternately, you have
insufficient memory to load your program. Alternately, the run-time system could not find
enough file handles to open and, therefore, load the code. -Either the library that contained the
program has been canceled, or the program is no longer available on the program search path.
Ensure that the program is available either on disk or on an open library. Either free some
memory, use XM, or restructure your application so that it uses less memory. Increase your
operating system file handles limit.
226
EXTERNAL file definition inconsistent -Two or more programs define the same external file
but with different formats. For example, maximum and minimum record lengths might be
different. -Ensure that all of your programs define the external file with the same format so that
they are consistent. It is useful to have the file definition in a COPY file.
227
EXTERNAL data definition inconsistent (Fatal) -Two or more programs are defining the same
external data item, but the first loaded program has defined the size differently from the
second or subsequent loaded program. -Ensure that both or all of your programs define the
size of the external data item as being the same.
228
Could not allocate memory for EXTERNAL item (Fatal)
229
SORT/MERGE module does not support EXTERNAL using/giving files (Recoverable) -You
have tried a SORT or MERGE operation which has USING/ GIVING files which are defined
as EXTERNAL. The SORT/ MERGE module does not support USING/ GIVING files defined
as EXTERNAL. -Recompile your program to use the callable SORT module (EXTSM).
230
Floating Point Support Module not found (Fatal)
235
Error in animator communications channel (Fatal) -Animator has encountered system limits or
conflicts resulting in communications errors. Perhaps two logins on the same UNIX system
are trying to cross-session animate the same program file. -Copy the animated program file to
a different directory and try animation.
236
Animated program has terminated unexpectedly (Fatal) -A program you are animating has
terminated without following the standard run-time system shut-down process. The
termination was probably either initiated by the user or caused by a severe run-time error. Run your program without animation to determine if it runs successfully; if so, animate the
program without cross-session or intrasession animation.
237
Unable to initialize animated process (Fatal) -Animator has encountered system limits in
starting your program. The animated program cannot start because of either insufficient
memory or too many processes running on the UNIX system. -Animate your program when
the load on the system has reduced. Run the program without animation to determine if it runs
successfully; if so, animate the program without cross-session or intrasession animation. Ask
your system administrator to expand the number of process slots and virtual memory page
maps.
238
STOP RUN encountered during GNT animation (Informational) -Animator has encountered a
STOP RUN statement while animating your .gnt code program. -Step or Zoom the animated
program, and Animator will terminate the program and its current session.
239
Shared run-time system initialization failure (Informational) -You are calling a COBOL module
from a non-COBOL program, and have not initialized the shared run-time system. -Ensure that
your application calls the cobinit() function before executing any COBOL modules.
240
Object reference not valid (Fatal) -You have tried to use an object reference that contains an
incorrect or non-existent object handle. -Ensure that the object reference uses the correct
object handle, and that your program has not previously destroyed the object by sending it a
Finalize message.
26
Chapter 4 External Error Codes
241
Cannot instantiate an abstract class (Fatal) -You have tried to create an instance of a class
that has been declared ABSTRACT. Such classes cannot be instantiated. -Ensure that you
have specified the correct class name. Check to see if there is a subclass that you should use
instead.
242
Could not resolve DoesNotUnderstand message (Fatal) -The run-time system could not
resolve the DoesNotUnderstand message. This is usually because you have defined a class
in such a way that this method cannot be found. -Check the logic in your program to ensure
that it invokes only methods that are supported by the object, or ensure that the object
supports the DoesNotUnderstand method.
243
Class could not be loaded (Fatal) -An attempt to load an object class has failed because the
class does not contain a valid Class-Control section, or because the class is not defined
correctly. -Check the definition of the class.
254
Keyboard interrupt to ANIMATOR during ACCEPT (Fatal) -While using Animator you have
terminated your program with a keyboard interrupt.
4.3 TCP/IP - Error Messages of the TCP/IP-Stack
The following is a list of possible error codes returned by the WSAGetLastError function, along with their
explanations. The error numbers are consistently set across all Windows Sockets-compliant
implementations.
Windows Sockets code
Berkeley equivalent
Error
Interpretation
WSAEINTR
EINTR
10004
As in standard C
WSAEBADF
EBADF
10009
As in standard C
WSAEACCES
EACCES
10013
As in standard C
WSAEDISCON
None
10101
The message terminated
gracefully. Used only for
message-oriented protocols.
WSAEFAULT
EFAULT
10014
As in standard C
WSAEINVAL
EINVAL
10022
As in standard C
WSAEMFILE
EMFILE
10024
As in standard C
WSAEWOULDBLOCK
EWOULDBLOCK
10035
As in BSD
WSAEINPROGRESS
EINPROGRESS
10036
This error is returned if
anyWindows Sockets function is
called while a blocking function is
in progress.
WSAEALREADY
EALREADY
10037
As in BSD
WSAENOTSOCK
ENOTSOCK
10038
As in BSD
WSAEDESTADDRREQ
EDESTADDRREQ
10039
As in BSD
WSAEMSGSIZE
EMSGSIZE
10040
As in BSD
WSAEPROTOTYPE
EPROTOTYPE
10041
As in BSD
WSAENOPROTOOPT
ENOPROTOOPT
10042
As in BSD
WSAEPROTONOSUPPORT EPROTONOSUPPORT 10043
As in BSD
Automation Engine
27
WSAESOCKTNOSUPPORT ESOCKTNOSUPPORT 10044
As in BSD
WSAEOPNOTSUPP
EOPNOTSUPP
10045
As in BSD
WSAEPFNOSUPPORT
EPFNOSUPPORT
10046
As in BSD
WSAEAFNOSUPPORT
EAFNOSUPPORT
10047
As in BSD
WSAEADDRINUSE
EADDRINUSE
10048
As in BSD
WSAEADDRNOTAVAIL
EADDRNOTAVAIL
10049
As in BSD
WSAENETDOWN
ENETDOWN
10050
As in BSD. This error may be
reported at any time if the
Windows Sockets implementation
detects an underlying failure.
WSAENETUNREACH
ENETUNREACH
10051
As in BSD
WSAENETRESET
ENETRESET
10052
As in BSD
WSAECONNABORTED
ECONNABORTED
10053
As in BSD
WSAECONNRESET
ECONNRESET
10054
As in BSD
WSAENOBUFS
ENOBUFS
10055
As in BSD
WSAEISCONN
EISCONN
10056
As in BSD
WSAENOTCONN
ENOTCONN
10057
As in BSD
WSAESHUTDOWN
ESHUTDOWN
10058
As in BSD
WSAETOOMANYREFS
ETOOMANYREFS
10059
As in BSD
WSAETIMEDOUT
ETIMEDOUT
10060
As in BSD
WSAECONNREFUSED
ECONNREFUSED
10061
As in BSD
WSAELOOP
ELOOP
10062
As in BSD
WSAENAMETOOLONG
ENAMETOOLONG
10063
As in BSD
WSAEHOSTDOWN
EHOSTDOWN
10064
As in BSD
WSAEHOSTUNREACH
EHOSTUNREACH
10065
As in BSD
WSASYSNOTREADY
None
10091
Returned by WSAStartup,
indicating that the network
subsystem is unusable.
WSAVERNOTSUPPORTED
None
10092
Returned by WSAStartup,
indicating that the Windows
Sockets DLL cannot support this
app.
WSANOTINITIALISED
None
10093
Returned by any function except
WSAStartup, indicating that a
successful WSAStartup, has not
yet been performed.
WSAHOST_NOT_FOUND
HOST_NOT_FOUND
11001
As in BSD
WSATRY_AGAIN
TRY_AGAIN
11002
As in BSD
WSANO_RECOVERY
NO_RECOVERY
11003
As in BSD
WSANO_DATA
NO_DATA
11004
As in BSD
28
Chapter 4 External Error Codes
The first set of definitions is present to resolve contentions between standard C error codes which may be
defined inconsistently between various C compilers.
The second set of definitions provides Windows Sockets versions of regular Berkeley Sockets error
codes.
The third set of definitions consists of extended Windows Sockets-specific error codes.
The fourth set of errors are returned by Windows Sockets getXbyY and WSAAsyncGetXByY functions
and correspond to the errors that in Berkeley software would be returned in the h_errno variable. They
correspond to various errors that may be returned by the Domain Name Service. If the Windows Sockets
implementation does not use the DNS, it will use the most appropriate code. In general, a Windows
Sockets application should interpret WSAHOST_NOT_FOUND and WSANO_DATA as indicating that
the key (name, address, and so on) was not found, while WSATRY_AGAIN and WSANO_RECOVERY
suggest that the name service itself is nonoperational.
The error numbers are derived from the WINSOCK.H header file and are based on the fact that Windows
Sockets error numbers are computed by adding 10000 to the "normal" Berkeley error number.
Note that this table does not include all of the error codes defined in WINSOCK.H. This is because it
includes only errors that might reasonably be returned by a Windows Sockets implementation.
WINSOCK.H, on the other hand, includes a full set of BSD definitions to ensure compatibility with ported
software.
4.4 UNIX - Error Codes
4.4.1 Error Codes in Log Messages of Agents
Subject
Sun OS (Solaris)
Error codes Sparc, Solaris 1 Version 4.1 and later Error codes Sparc, Solaris 2 Version 5.5 and later Error codes Intel, Solaris 2.4 and later (corresponds to SVR4)
HP-UX
Error codes HP-Workstation (9000); HP-UX 9
Error codes HP-Workstation (9000); HP-UX 10 DEC OSF
Error codes Alpha - DEC-OSF/1 - Digital UNIX 4.0
SCO
Error codes Intel - SCO-UNIX ODT 5.*
IBM AIX
Error codes Power-PC - AIX 4.1 Automation Engine
29
Notes
In the log messages of the Agents, error codes of various UNIX systems are used. An example for such a
log message: "U2003040 error in 'read' call (58), socket '6', error: ('11' - No more processes)".
This log message means that with the function "read" (reading TCP/IP) on socket 6 (internal number) error
code 11 occurred. These messages are normally of minor significance and are to be ignored.
We supply all error codes and text here. If you require further information, you can call up the
documentation of a function by entering man function on the UNIX system. The description of possible
error codes is also included.
Example: man read
4.4.2 DEC OSF
Error Codes Alpha - DEC-OSF/1 - Digital UNIX 4.0
Error Code
Error Text
0
Successful
1
Not owner
2
No such file or directory
3
No such process
4
Interrupted system call
5
I/O error
6
No such device or address
7
Arg list too long
8
Exec format error
9
Bad file number
10
No children
11
Operation would cause deadlock
12
Not enough core
13
Permission denied
14
Bad address
15
Block device required
16
Mount device busy
17
File exists
18
Cross-device link
19
No such device
20
Not a directory
21
Is a directory
22
Invalid argument
23
File table overflow
24
Too many open files
30
Chapter 4 External Error Codes
25
Not a typewriter
26
Text file busy
27
File too large
28
No space left on device
29
Illegal seek
30
Read-only file system
31
Too many links
32
Broken pipe
33
Argument too large
34
Result too large
35
Operation would block
36
Operation now in progress
37
Operation already in progress
38
Socket operation on non-socket
39
Destination address required
40
Message too long
41
Protocol wrong type for socket
42
Protocol not available
43
Protocol not supported
44
Socket type not supported
45
Operation not supported on socket
46
Protocol family not supported
47
Address family not supported by protocol family
48
Address already in use
49
Cannot assign requested address
50
Network is down
51
Network is unreachable
52
Network dropped connection on reset
53
Software caused connection abort
54
Connection reset by peer
55
No buffer space available
56
Socket is already connected
57
Socket is not connected
58
Cannot send after socket shutdown
59
Too many references: cannot splice
60
Connection timed out
61
Connection refused
62
Too many levels of symbolic links
Automation Engine
63
File name too long
64
Host is down
65
No route to host
66
Directory not empty
67
Too many processes
68
Too many users
69
Disc quota exceeded
70
Stale NFS file handle
71
Too many levels of remote in path
72
RPC struct is bad
73
RPC version wrong
74
RPC prog. not avail
75
Program version wrong
76
Bad procedure for program
77
No locks available
78
Function not implemented
79
Inappropriate file type or format
80
No msg matches receive request
81
Msg queue id has been removed
82
Out of STREAMS resources
83
System call timed out
84
Next message has wrong type
85
STREAMS protocol error
86
No message on stream head read q
87
fd not associated with a stream
88
Tells open to clone the device
89
Mounting a dirty fs w/o force
90
Duplicate package name on install
91
Version number mismatch
92
Unresolved package name
93
Unresolved symbol name
94
Operation canceled
95
Cannot start operation
97
Operation (now) in progress
98
Too many timers
99
Function not implemented
100
Internal AIO operation complete
101
Reserved
31
32
Chapter 4 External Error Codes
102
Reserved
103
Value too large to be stored in data type
116
Invalid wide character
4.4.3 HP-UX
Error Codes HP Workstation (9000), HP-UX 9
Error Code
Error Text
1
Not super-user
2
No such file or directory
3
No such process
4
Interrupted system call
5
I/O error
6
No such device or address
7
Arg list too long
8
Exec format error
9
Bad file number
10
No children
11
No more processes
12
Not enough core
13
Permission denied
14
Bad address
15
Block device required
16
Mount device busy
17
File exists
18
Cross-device link
19
No such device
20
Not a directory
21
Is a directory
22
Invalid argument
23
File table overflow
24
Too many open files
25
Not a typewriter
26
Text file busy
27
File too large
28
No space left on device
29
Illegal seek
30
Read only file system
Automation Engine
31
Too many links
32
Broken pipe
35
No message of desired type
36
Identifier removed
37
Channel number out of range
38
Level 2 not synchronized
39
Level 3 halted
40
Level 3 reset
41
Link number out of range
42
Protocol driver not attached
43
No CSI structure available
44
Level 2 halted
45
A deadlock would occur
46
System record lock table was full
47
Illegal byte sequence
50
Machine is not on the network
51
No data (for no delay io)
52
Timer expired
53
Out of streams resources
54
Device not a stream
55
Package not installed
57
The link has been severed
58
Advertise error
59
srmount error
60
Communication error on send
61
Protocol error
64
Multihop attempted
66
Cross mount point (not really error)
67
Trying to read unreadable message
68
For Sun compatibility, will not occur.
69
Disc quota exceeded
70
Stale NFS file handle
71
Too many levels of remote in path
99
Unexpected Error
215
Symbol does not exist in executable
216
Socket operation on non-socket
217
Destination address required
218
Message too long
33
34
Chapter 4 External Error Codes
219
Protocol wrong type for socket
220
Protocol not available
221
Protocol not supported
222
Socket type not supported
223
Operation not supported
224
Protocol family not supported
225
Address family not supported by
226
Address already in use
227
Cannot assign requested address
228
Network is down
229
Network is unreachable
230
Network dropped connection on
231
Software caused connection abort
232
Connection reset by peer
233
No buffer space available
234
Socket is already connected
235
Socket is not connected
236
Cannot send after socket shutdown
237
Too many references: cannot splice
238
Connection timed out
239
Connection refused
240
Remote peer released connection
241
Host is down
242
No route to host
244
Operation already in progress
245
Operation now in progress
246
Operation would block
247
Directory not empty
248
File name too long
249
Too many levels of symbolic links
250
No message of desired type
251
Function not implemented
Error Codes HP Workstation(9000), HP-UX 10
Error Code
Error Text
1
Not super-user
2
No such file or directory
3
No such process
Automation Engine
4
Interrupted system call
5
I/O error
6
No such device or address
7
Arg list too long
8
Exec format error
9
Bad file number
10
No children
11
No more processes
12
Not enough core
13
Permission denied
14
Bad address
15
Block device required
16
Mount device busy
17
File exists
18
Cross-device link
19
No such device
20
Not a directory
21
Is a directory
22
Invalid argument
23
File table overflow
24
Too many open files
25
Not a typewriter
26
Text file busy
27
File too large
28
No space left on device
29
Illegal seek
30
Read only file system
31
Too many links
32
Broken pipe
33
Math arg out of domain of func
34
Math result not representable
35
No message of desired type
36
Identifier removed
37
Channel number out of range
38
Level 2 not synchronized
39
Level 3 halted
40
Level 3 reset
41
Link number out of range
35
36
Chapter 4 External Error Codes
42
Protocol driver not attached
43
No CSI structure available
44
Level 2 halted
45
A deadlock would occur
46
System record lock table was full
47
Illegal byte sequence
50
Machine is not on the network
51
No data (for no delay io)
52
Timer expired
53
Out of streams resources
54
Device not a stream
55
Package not installed
57
The link has been severed
58
Advertise error
59
srmount error
60
Communication error on send
61
Protocol error
64
Multihop attempted
66
Cross mount point (not really error)
67
Trying to read unreadable message
68
For Sun compatibility, will not occur.
69
Disc quota exceeded
70
Stale NFS file handle
71
Too many levels of remote in path
72
Value too large to be stored in data type
215
Symbol does not exist in executable
216
Socket operation on non-socket
217
Destination address required
218
Message too long
219
Protocol wrong type for socket
220
Protocol not available
221
Protocol not supported
222
Socket type not supported
223
Operation not supported
224
Protocol family not supported
225
Address family not supported by
226
Address already in use
227
Cannot assign requested address
Automation Engine
228
Network is down
229
Network is unreachable
230
Network dropped connection on reset
231
Software caused connection abort
232
Connection reset by peer
233
No buffer space available
234
Socket is already connected
235
Socket is not connected
236
Cannot send after socket shutdown
237
Too many references: cannot splice
238
Connection timed out
239
Connection refused
240
Remote peer released connection
241
Host is down
242
No route to host
244
Operation already in progress
245
Operation now in progress
246
Operation would block
247
Directory not empty
248
File name too long
249
Too many levels of symbolic links
251
Function not implemented
252
Function not implemented
4.4.4 IBM AIX
Error Codes Power PC - AIX 4.1
Error Code
Error Text
1 Operation not allowed 2 No such file or directory 3 No such process 4 Interrupted system call 5 I/O error 6 No such device or address 7 Arg list too long 8 Exec format error 9 Bad file descriptor 10
No child processes
37
38
Chapter 4 External Error Codes
11
Resource temporarily unavailable
12
Not enough space
13
Permission denied
14
Bad address
15
Block device required
16
Resource busy
17
File exists
18
Improper link
19
No such device
20
Not a directory
21
Is a directory
22
Invalid argument
23
Too many open files in system
24
Too many open files
25
Inappropriate I/O control operation
26
Text file busy
27
File too large
28
No space left on device
29
Invalid seek
30
Read only file system
31
Too many links
32
Broken pipe
33
Domain error within math function
34
Result too large
35
No message of desired type
36
Identifier removed
37
Channel number out of range
38
Level 2 not synchronized
39
Level 3 halted
40
Level 3 reset
41
Link number out of range
42
Protocol driver not attached
43
No CSI structure available
44
Level 2 halted
45
Resource deadlock avoided
46
Device not ready
47
Write-protected media
48
Unformatted media
Automation Engine
49
No locks available
50
No connection
52
No file system
53
Old, currently unused AIX error
54
Operation would block
55
Operation now in progress
56
Operation already in progress
57
Socket operation on non-socket
58
Destination address required
59
Message too long
60
Protocol wrong type for socket
61
Protocol not available
62
Protocol not supported
63
Socket type not supported
64
Operation not supported on socket
65
Protocol family not supported
66
Address family not supported by protocol family
67
Address already in use
68
Cannot assign requested address
69
Network is down
70
Network is unreachable
71
Network dropped connection on reset
72
Software caused connection abort
73
Connection reset by peer
74
No buffer space available
75
Socket is already connected
76
Socket is not connected
77
Cannot send after socket shutdown
78
Connection timed out
79
Connection refused
80
Host is down
81
No route to host
82
Restart the system call
83
Too many processes
84
Too many users
85
Too many levels of symbolic links
86
File name too long
87
Directory not empty
39
40
Chapter 4 External Error Codes
88
Disc quota exceeded
89 - 92
Reserved for future use compatible with AIX PS/2
93
Item is not local to host
94 - 108
Reserved for future use compatible with AIX PS/2
109
Function not implemented POSIX
110
Media surface error
111
I/O completed, but needs relocation
112
No attribute found
113
Security authentication denied
114
Not a trusted program
115
Too many references: can't splice
116
Invalid wide character
117
Asynchronous i/o canceled
118
Temp out of streams resources
119
I_STR ioctl timed out
120
Wrong message type at stream head
121
STREAMS protocol error
122
No message ready at stream head
123
fd is not a stream
124
POSIX threads unsupported value
125
Multihop is not allowed
126
The link has been severed
127
Value too large to be stored in data type 4.4.5 SCO
Error Codes Intel - SCO-UNIX ODT 5.*
Error Code
Error Text
1
Not owner
2
No such file or directory
3
No such process
4
Interrupted system call
5
I/O error
6
No such device or address
7
Arg list too long
8
Exec format error
9
Bad file number
10
No child processes
Automation Engine
11
No more processes
12
Not enough space
13
Permission denied
14
Bad address
15
Block device required
16
Device busy
17
File exists
18
Cross-device link
19
No such device
20
Not a directory
21
Is a directory
22
Invalid argument
23
File table overflow
24
Too many open files
25
Not a typewriter
26
Text file busy
27
File too large
28
No space left on device
29
Illegal seek
30
Read-only file system
31
Too many links
32
Broken pipe
33
Argument out of domain
34
Result too large
35
No message of desired type
36
Identifier removed
37
Channel number out of range
38
Level 2 not synchronized
39
Level 3 halted
40
Level 3 reset
41
Link number out of range
42
Protocol driver not attached
43
No CSI structure available
44
Level 2 halted
45
Deadlock situation detected/avoided
46
No record locks available
50
Bad exchange descriptor
51
Bad request descriptor
41
42
Chapter 4 External Error Codes
52
Message tables full
53
Anode table overflow
54
Bad request code
55
Invalid slot
56
File locking deadlock
57
Bad font file format
60
Not a stream device
61
No data available
62
Timer expired
63
Out of stream resources
64
Machine is not on the network
65
Package not installed
66
Object is remote
67
Link has been severed
68
Advertise error
69
Srmount error
70
Communication error on send
71
Protocol error
74
Multihop attempted
75
Inode is remote (not really error)
76
Cross mount point (not really error)
77
Not a data message
78
Filename too long
79
(Reserved for future use)
80
Name not unique on network
81
File descriptor in bad state
82
Remote address changed
83
cannot access a needed shared library
84
Accessing a corrupted shared library
85
.lib section in a.out corrupted
86
Attempting to link in too many shared libs.
87
cannot exec a shared library directly
88
Illegal byte sequence
89
Function not implemented
90
Operation would block
91
Operation now in progress
92
Operation already in progress
93
Socket operation on non-socket
Automation Engine
94
Destination address required
95
Message too long
96
Protocol wrong type for socket
97
Protocol not supported
98
Socket type not supported
99
Operation not supported on socket
100
Protocol family not supported
101
Address family not supported by protocol family
102
Address already in use
103
Cannot assign requested address
104
Network is down
105
Network is unreachable
106
Network dropped connection on reset
107
Software caused connection abort
108
Connection reset by peer
110
Socket is already connected
111
Socket is not connected
112
Can't send after socket shutdown
113
Too many references: can't splice
114
Connection timed out
115
Connection refused
116
Host is down
117
No route to host
118
Protocol not available
135
Structure needs cleaning
137
Not a name file
138
Not available
139
Is a name file
140
Remote I/O error
141
(Reserved for future use)
142
Error 142
145
Directory not empty
150
Too many symbolic links in path
151
(Reserved for future use)
152
(Reserved for future use)
153
(Reserved for future use)
500
(Reserved for future use)
43
44
Chapter 4 External Error Codes
4.4.6 Sun OS (Solaris)
Error Codes Sparc, Solaris 1 Version 4.1 and Later
Error Code
Error Text
1
Not owner
2
No such file or directory
3
No such process
4
Interrupted system call
5
I/O error
6
No such device or address
7
Arg list too long
8
Exec format error
9
Bad file number
10
No children
11
No more processes
12
Not enough core
13
Permission denied
14
Bad address
15
Block device required
16
Mount device busy
17
File exists
18
Cross-device link
19
No such device
20
Not a directory
21
Is a directory
22
Invalid argument
23
File table overflow
24
Too many open files
25
Not a typewriter
26
Text file busy
27
File too large
28
No space left on device
29
Illegal seek
30
Read-only file system
31
Too many links
32
Broken pipe
33
Argument too large
34
Result too large
Automation Engine
35
Operation would block
36
Operation now in progress
37
Operation already in progress
38
Socket operation on non-socket
39
Destination address required
40
Message too long
41
Protocol wrong type for socket
42
Protocol not available
43
Protocol not supported
44
Socket type not supported
45
Operation not supported on socket
46
Protocol family not supported
47
Address family not supported by protocol family
48
Address already in use
49
Cannot assign requested address
50
Network is down
51
Network is unreachable
52
Network dropped connection on reset
53
Software caused connection abort
54
Connection reset by peer
55
No buffer space available
56
Socket is already connected
57
Socket is not connected
58
Cannot send after socket shutdown
59
Too many references: cannot splice
60
Connection timed out
61
Connection refused
62
Too many levels of symbolic links
63
File name too long
64
Host is down
65
No route to host
66
Directory not empty
67
Too many processes
68
Too many users
69
Disc quota exceeded
70
Stale NFS file handle
71
Too many levels of remote in path
72
Device is not a stream
45
46
Chapter 4 External Error Codes
73
Timer expired
74
Out of streams resources
75
No message of desired type
76
Trying to read unreadable message
77
Identifier removed
78
Deadlock condition.
79
No record locks available.
80
Machine is not on the network
81
Object is remote
82
The link has been severed
83
Advertise error
84
srmount error
85
Communication error on send
86
Protocol error
87
multihop attempted
88
Cross mount point (not an error)
89
Remote address changed
90
Function not implemented
Error Codes Sparc, Solaris 2 Version 5.5 and Later
Error Code
Error Text
1
Not super-user
2
No such file or directory
3
No such process
4
Interrupted system call
5
I/O error
6
No such device or address
7
Arg list too long
8
Exec format error
9
Bad file number
10
No children
11
Resource temporarily unavailable
12
Not enough core
13
Permission denied
14
Bad address
15
Block device required
16
Mount device busy
17
File exists
Automation Engine
18
Cross-device link
19
No such device
20
Not a directory
21
Is a directory
22
Invalid argument
23
File table overflow
24
Too many open files
25
Inappropriate ioctl for device
26
Text file busy
27
File too large
28
No space left on device
29
Illegal seek
30
Read only file system
31
Too many links
32
Broken pipe
33
Math arg out of domain of func
34
Math result not representable
35
No message of desired type
36
Identifier removed
37
Channel number out of range
38
Level 2 not synchronized
39
Level 3 halted
40
Level 3 reset
41
Link number out of range
42
Protocol driver not attached
43
No CSI structure available
44
Level 2 halted
45
Deadlock condition.
46
No record locks available.
47
Operation canceled
48
Operation not supported
49
Disc quota exceeded
50
Invalid exchange
51
Invalid request descriptor
52
Exchange full
53
No anode
54
Invalid request code
55
Invalid slot
47
48
Chapter 4 External Error Codes
56
File locking deadlock error
57
Bad font file fmt
60
Device not a stream
61
No data (for no delay io)
62
timer expired
63
out of streams resources
64
Machine is not on the network
65
Package not installed
66
The object is remote
67
the link has been severed
68
advertise error
69
srmount error
70
Communication error on send
71
Protocol error
74
Multihop attempted
77
Trying to read unreadable message
78
Path name is too long
79
Value too large to be stored in data type
80
Given log. name not unique
81
f.d. invalid for this operation
82
Remote address changed
83
Cannot access a needed shared lib.
84
Accessing a corrupted shared lib.
85
.lib section in a.out corrupted.
86
Attempting to link in too many libs.
87
Attempting to exec a shared library.
88
Illegal byte sequence.
89
Unsupported file system operation
90
Symbolic link loop
91
Restartable system call
92
If pipe/FIFO, do not sleep in stream head
93
Directory not empty
94
Too many users (for UFS)
95
Socket operation on non-socket
96
Destination address required
97
Message too long
98
Protocol wrong type for socket
99
Protocol not available
Automation Engine
120
Protocol not supported
121
Socket type not supported
122
Operation not supported on socket
123
Protocol family not supported
124
Address family not supported by
125
Address already in use
126
Cannot assign requested address
127
Network is down
128
Network is unreachable
129
Network dropped connection because
130
Software caused connection abort
131
Connection reset by peer
132
No buffer space available
133
Socket is already connected
134
Socket is not connected
135 - 142
XENIX
143
Cannot send after socket shutdown
144
Too many references: cannot splice
145
Connection timed out
146
Connection refused
147
Host is down
148
No route to host
149
Operation already in progress
150
Operation now in progress
151
Stale NFS file handle
Error Codes Intel, Solaris 2.4 and Later
Error Code
Error Text
1
Not super-user
2
No such file or directory
3
No such process
4
Interrupted system call
5
I/O error
6
No such device or address
7
Arg list too long
8
Exec format error
9
Bad file number
10
No children
49
50
Chapter 4 External Error Codes
11
Resource temporarily unavailable
12
Not enough core
13
Permission denied
14
Bad address
15
Block device required
16
Mount device busy
17
File exists
18
Cross-device link
19
No such device
20
Not a directory
21
Is a directory
22
Invalid argument
23
File table overflow
24
Too many open files
25
Inappropriate ioctl for device
26
Text file busy
27
File too large
28
No space left on device
29
Illegal seek
30
Read only file system
31
Too many links
32
Broken pipe
33
Math arg out of domain of func
34
Math result not representable
35
No message of desired type
36
Identifier removed
37
Channel number out of range
38
Level 2 not synchronized
39
Level 3 halted
40
Level 3 reset
41
Link number out of range
42
Protocol driver not attached
43
No CSI structure available
44
Level 2 halted
45
Deadlock condition.
46
No record locks available.
47
Operation canceled
48
Operation not supported
Automation Engine
50
Invalid exchange
51
Invalid request descriptor
52
Exchange full
53
No anode
54
Invalid request code
55
Invalid slot
56
File locking deadlock error
57
Bad font file fmt
60
Device not a stream
61
No data (for no delay io)
62
Timer expired
63
Out of streams resources
64
Machine is not on the network
65
Package not installed
66
The object is remote
67
The link has been severed
68
Advertise error
69
srmount error
70
Communication error on send
71
Protocol error
74
Multihop attempted
77
Trying to read unreadable message
78
Path name is too long
79
Value too large to be stored in data type
80
Given log. name not unique
81
f.d. invalid for this operation
82
Remote address changed
83
Cannot access a needed shared lib.
84
Accessing a corrupted shared lib.
85
.lib section in a.out corrupted.
86
Attempting to link in too many libs.
87
Attempting to exec a shared library.
88
Illegal byte sequence.
89
Unsupported file system operation
90
Symbolic link loop
91
Restartable system call
92
If pipe/FIFO, do not sleep in stream head
93
Directory not empty
51
52
Chapter 4 External Error Codes
94
Too many users (for UFS)
95
Socket operation on non-socket
96
Destination address required
97
Message too long
98
Protocol wrong type for socket
99
Protocol not available
120
Protocol not supported
121
Socket type not supported
122
Operation not supported on socket
123
Protocol family not supported
124
Address family not supported by
125
Address already in use
126
Cannot assign requested address
127
Network is down
128
Network is unreachable
129
Network dropped connection because of reset
130
Software caused connection abort
131
Connection reset by peer
132
No buffer space available
133
Socket is already connected
134
Socket is not connected
135 - 142
XENIX
143
Cannot send after socket shutdown
144
Too many references: cannot splice
145
Connection timed out
146
Connection refused
147
Host is down
148
No route to host
149
Operation already in progress
150
Operation now in progress
4.5 Windows - Error Codes
4.5.1 Win32 - Error Codes (0 - 999)
The following table provides a list of Win32 error codes.
Code Description
Name
Automation Engine
53
0
The operation completed successfully.
ERROR_
SUCCESS
1
Incorrect function.
ERROR_
INVALID_
FUNCTION
2
The system cannot find the file specified.
ERROR_FILE_
NOT_FOUND
3
The system cannot find the path specified.
ERROR_PATH_
NOT_FOUND
4
The system cannot open the file.
ERROR_TOO_
MANY_OPEN_
FILES
5
Access is denied.
ERROR_
ACCESS_
DENIED
6
The handle is invalid.
ERROR_
INVALID_
HANDLE
7
The storage control blocks were destroyed.
ERROR_ARENA_
TRASHED
8
Not enough storage is available to process this command.
ERROR_NOT_
ENOUGH_
MEMORY
9
The storage control block address is invalid.
ERROR_
INVALID_BLOCK
10
The environment is incorrect.
ERROR_BAD_
ENVIRONMENT
11
An attempt was made to load a program with an incorrect format.
ERROR_BAD_
FORMAT
12
The access code is invalid.
ERROR_
INVALID_
ACCESS
13
The data is invalid.
ERROR_
INVALID_DATA
14
Not enough storage is available to complete this operation.
ERROR_
OUTOFMEMORY
15
The system cannot find the drive specified.
ERROR_
INVALID_DRIVE
16
The directory cannot be removed.
ERROR_
CURRENT_
DIRECTORY
17
The system cannot move the file to a different disk drive.
ERROR_NOT_
SAME_DEVICE
18
There are no more files.
ERROR_NO_
MORE_FILES
54
Chapter 4 External Error Codes
19
The media is write protected.
ERROR_WRITE_
PROTECT
20
The system cannot find the device specified.
ERROR_BAD_
UNIT
21
The device is not ready.
ERROR_NOT_
READY
22
The device does not recognize the command.
ERROR_BAD_
COMMAND
23
Data error (cyclic redundancy check).
ERROR_CRC
24
The program issued a command but the command length is incorrect.
ERROR_BAD_
LENGTH
25
The drive cannot locate a specific area or track on the disk.
ERROR_SEEK
26
The specified disk or diskette cannot be accessed.
ERROR_NOT_
DOS_DISK
27
The drive cannot find the sector requested.
ERROR_
SECTOR_NOT_
FOUND
28
The printer is out of paper.
ERROR_OUT_
OF_PAPER
29
The system cannot write to the specified device.
ERROR_WRITE_
FAULT
30
The system cannot read from the specified device.
ERROR_READ_
FAULT
31
A device attached to the system is not functioning.
ERROR_GEN_
FAILURE
32
The process cannot access the file because it is being used by another
process.
ERROR_
SHARING_
VIOLATION
33
The process cannot access the file because another process has locked a
portion of the file.
ERROR_LOCK_
VIOLATION
34
The wrong diskette is in the drive. Insert %2 (Volume Serial Number: %3)
into drive %1.
ERROR_
WRONG_DISK
36
Too many files opened for sharing.
ERROR_
SHARING_
BUFFER_
EXCEEDED
38
Reached the end of the file.
ERROR_
HANDLE_EOF
39
The disk is full.
ERROR_
HANDLE_DISK_
FULL
50
The network request is not supported.
ERROR_NOT_
SUPPORTED
51
The remote computer is not available.
ERROR_REM_
NOT_LIST
Automation Engine
55
52
A duplicate name exists on the network.
ERROR_DUP_
NAME
53
The network path was not found.
ERROR_BAD_
NETPATH
54
The network is busy.
ERROR_
NETWORK_BUSY
55
The specified network resource or device is no longer available.
ERROR_DEV_
NOT_EXIST
56
The network BIOS command limit has been reached.
ERROR_TOO_
MANY_CMDS
57
A network adapter hardware error occurred.
ERROR_ADAP_
HDW_ERR
58
The specified server cannot perform the requested operation.
ERROR_BAD_
NET_RESP
59
An unexpected network error occurred.
ERROR_UNEXP_
NET_ERR
60
The remote adapter is not compatible.
ERROR_BAD_
REM_ADAP
61
The printer queue is full.
ERROR_
PRINTQ_FULL
62
Space to store the file waiting to be printed is not available on the server.
ERROR_NO_
SPOOL_SPACE
63
Your file waiting to be printed was deleted.
ERROR_PRINT_
CANCELED
64
The specified network name is no longer available.
ERROR_
NETNAME_
DELETED
65
Network access is denied.
ERROR_
NETWORK_
ACCESS_
DENIED
66
The network resource type is not correct.
ERROR_BAD_
DEV_TYPE
67
The network name cannot be found.
ERROR_BAD_
NET_NAME
68
The name limit for the local computer network adapter card was exceeded.
ERROR_TOO_
MANY_NAMES
69
The network BIOS session limit was exceeded.
ERROR_TOO_
MANY_SESS
70
The remote server has been paused or is in the process of being started.
ERROR_
SHARING_
PAUSED
71
No more connections can be made to this remote computer at this time
because there are already as many connections as the computer can
accept.
ERROR_REQ_
NOT_ACCEP
56
Chapter 4 External Error Codes
72
The specified printer or disk device has been paused.
ERROR_REDIR_
PAUSED
80
The file exists.
ERROR_FILE_
EXISTS
82
The directory or file cannot be created.
ERROR_
CANNOT_MAKE
83
Fail on INT 24.
ERROR_FAIL_I24
84
Storage to process this request is not available.
ERROR_OUT_
OF_
STRUCTURES
85
The local device name is already in use.
ERROR_
ALREADY_
ASSIGNED
86
The specified network password is not correct.
ERROR_
INVALID_
PASSWORD
87
The parameter is incorrect.
ERROR_
INVALID_
PARAMETER
88
A write fault occurred on the network.
ERROR_NET_
WRITE_FAULT
89
The system cannot start another process at this time.
ERROR_NO_
PROC_SLOTS
100
Cannot create another system semaphore.
ERROR_TOO_
MANY_
SEMAPHORES
101
The exclusive semaphore is owned by another process.
ERROR_EXCL_
SEM_ALREADY_
OWNED
102
The semaphore is set and cannot be closed.
ERROR_SEM_IS_
SET
103
The semaphore cannot be set again.
ERROR_TOO_
MANY_SEM_
REQUESTS
104
Cannot request exclusive semaphores at interrupt time.
ERROR_
INVALID_AT_
INTERRUPT_
TIME
105
The previous ownership of this semaphore has ended.
ERROR_SEM_
OWNER_DIED
106
Insert the diskette for drive %1.
ERROR_SEM_
USER_LIMIT
107
The program stopped because an alternate diskette was not inserted.
ERROR_DISK_
CHANGE
108
The disk is in use or locked by another process.
ERROR_DRIVE_
LOCKED
Automation Engine
57
109
The pipe has been ended.
ERROR_
BROKEN_PIPE
110
The system cannot open the device or file specified.
ERROR_OPEN_
FAILED
111
The file name is too long.
ERROR_
BUFFER_
OVERFLOW
112
There is not enough space on the disk.
ERROR_DISK_
FULL
113
No more internal file identifiers available.
ERROR_NO_
MORE_SEARCH_
HANDLES
114
The target internal file identifier is incorrect.
ERROR_
INVALID_
TARGET_
HANDLE
117
The IOCTL call made by the application program is not correct.
ERROR_
INVALID_
CATEGORY
118
The verify-on-write switch parameter value is not correct.
ERROR_
INVALID_
VERIFY_SWITCH
119
The system does not support the command requested.
ERROR_BAD_
DRIVER_LEVEL
120
This function is not supported on this system.
ERROR_CALL_
NOT_
IMPLEMENTED
121
The semaphore timeout period has expired.
ERROR_SEM_
TIMEOUT
122
The data area passed to a system call is too small.
ERROR_
INSUFFICIENT_
BUFFER
123
The filename, directory name, or volume label syntax is incorrect.
ERROR_
INVALID_NAME
124
The system call level is not correct.
ERROR_
INVALID_LEVEL
125
The disk has no volume label.
ERROR_NO_
VOLUME_LABEL
126
The specified module could not be found.
ERROR_MOD_
NOT_FOUND
127
The specified procedure could not be found.
ERROR_PROC_
NOT_FOUND
128
There are no child processes to wait for.
ERROR_WAIT_
NO_CHILDREN
129
The %1 application cannot be run in Win32 mode.
ERROR_CHILD_
NOT_COMPLETE
58
Chapter 4 External Error Codes
130
Attempt to use a file handle to an open disk partition for an operation other
than raw disk I/O.
ERROR_
DIRECT_
ACCESS_
HANDLE
131
An attempt was made to move the file pointer before the beginning of the
file.
ERROR_
NEGATIVE_SEEK
132
The file pointer cannot be set on the specified device or file.
ERROR_SEEK_
ON_DEVICE
133
A JOIN or SUBST command cannot be used for a drive that contains
previously joined drives.
ERROR_IS_
JOIN_TARGET
134
An attempt was made to use a JOIN or SUBST command on a drive that
has already been joined.
ERROR_IS_
JOINED
135
An attempt was made to use a JOIN or SUBST command on a drive that
has already been substituted.
ERROR_IS_
SUBSTED
136
The system tried to delete the JOIN of a drive that is not joined.
ERROR_NOT_
JOINED
137
The system tried to delete the substitution of a drive that is not substituted. ERROR_NOT_
SUBSTED
138
The system tried to join a drive to a directory on a joined drive.
ERROR_JOIN_
TO_JOIN
139
The system tried to substitute a drive to a directory on a substituted drive.
ERROR_SUBST_
TO_SUBST
140
The system tried to join a drive to a directory on a substituted drive.
ERROR_JOIN_
TO_SUBST
141
The system tried to SUBST a drive to a directory on a joined drive.
ERROR_SUBST_
TO_JOIN
142
The system cannot perform a JOIN or SUBST at this time.
ERROR_BUSY_
DRIVE
143
The system cannot join or substitute a drive to or for a directory on the
same drive.
ERROR_SAME_
DRIVE
144
The directory is not a subdirectory of the root directory.
ERROR_DIR_
NOT_ROOT
145
The directory is not empty.
ERROR_DIR_
NOT_EMPTY
146
The path specified is being used in a substitute.
ERROR_IS_
SUBST_PATH
147
Not enough resources are available to process this command.
ERROR_IS_
JOIN_PATH
148
The path specified cannot be used at this time.
ERROR_PATH_
BUSY
149
An attempt was made to join or substitute a drive for which a directory on
the drive is the target of a previous substitute.
ERROR_IS_
SUBST_TARGET
150
System trace information was not specified in your CONFIG.SYS file, or
tracing is disallowed.
ERROR_
SYSTEM_TRACE
Automation Engine
59
151
The number of specified semaphore events for DosMuxSemWait is not
correct.
ERROR_
INVALID_EVENT_
COUNT
152
DosMuxSemWait did not execute; too many semaphores are already set.
ERROR_TOO_
MANY_
MUXWAITERS
153
The DosMuxSemWait list is not correct.
ERROR_
INVALID_LIST_
FORMAT
154
The volume label you entered exceeds the label character limit of the target ERROR_LABEL_
file system.
TOO_LONG
155
Cannot create another thread.
ERROR_TOO_
MANY_TCBS
156
The recipient process has refused the signal.
ERROR_SIGNAL_
REFUSED
157
The segment is already discarded and cannot be locked.
ERROR_
DISCARDED
158
The segment is already unlocked.
ERROR_NOT_
LOCKED
159
The address for the thread ID is not correct.
ERROR_BAD_
THREADID_
ADDR
160
The argument string passed to DosExecPgm is not correct.
ERROR_BAD_
ARGUMENTS
161
The specified path is invalid.
ERROR_BAD_
PATHNAME
162
A signal is already pending.
ERROR_SIGNAL_
PENDING
164
No more threads can be created in the system.
ERROR_MAX_
THRDS_
REACHED
167
Unable to lock a region of a file.
ERROR_LOCK_
FAILED
170
The requested resource is in use.
ERROR_BUSY
173
A lock request was not outstanding for the supplied cancel region.
ERROR_
CANCEL_
VIOLATION
174
The file system does not support atomic changes to the lock type.
ERROR_
ATOMIC_LOCKS_
NOT_
SUPPORTED
180
The system detected a segment number that was not correct.
ERROR_
INVALID_
SEGMENT_
NUMBER
60
Chapter 4 External Error Codes
182
The operating system cannot run %1.
ERROR_
INVALID_
ORDINAL
183
Cannot create a file when that file already exists.
ERROR_
ALREADY_
EXISTS
186
The flag passed is not correct.
ERROR_
INVALID_FLAG_
NUMBER
187
The specified system semaphore name was not found.
ERROR_SEM_
NOT_FOUND
188
The operating system cannot run %1.
ERROR_
INVALID_
STARTING_
CODESEG
189
The operating system cannot run %1.
ERROR_
INVALID_
STACKSEG
190
The operating system cannot run %1.
ERROR_
INVALID_
MODULETYPE
191
Cannot run %1 in Win32 mode.
ERROR_
INVALID_EXE_
SIGNATURE
192
The operating system cannot run %1.
ERROR_EXE_
MARKED_
INVALID
193
%1 is not a valid Win32 application.
ERROR_BAD_
EXE_FORMAT
194
The operating system cannot run %1.
ERROR_
ITERATED_
DATA_
EXCEEDS_64k
195
The operating system cannot run %1.
ERROR_
INVALID_
MINALLOCSIZE
196
The operating system cannot run this application program.
ERROR_
DYNLINK_FROM_
INVALID_RING
197
The operating system is not presently configured to run this application.
ERROR_IOPL_
NOT_ENABLED
198
The operating system cannot run %1.
ERROR_
INVALID_
SEGDPL
199
The operating system cannot run this application program.
ERROR_
AUTODATASEG_
EXCEEDS_64k
Automation Engine
61
200
The code segment cannot be greater than or equal to 64K.
ERROR_
RING2SEG_
MUST_BE_
MOVABLE
201
The operating system cannot run %1.
ERROR_RELOC_
CHAIN_XEEDS_
SEGLIM
202
The operating system cannot run %1.
ERROR_
INFLOOP_IN_
RELOC_CHAIN
203
The system could not find the environment option that was entered.
ERROR_
ENVVAR_NOT_
FOUND
205
No process in the command subtree has a signal handler.
ERROR_NO_
SIGNAL_SENT
206
The filename or extension is too long.
ERROR_
FILENAME_
EXCED_RANGE
207
The ring 2 stack is in use.
ERROR_RING2_
STACK_IN_USE
208
The global filename characters, * or ?, are entered incorrectly or too many
global filename characters are specified.
ERROR_META_
EXPANSION_
TOO_LONG
209
The signal being posted is not correct.
ERROR_
INVALID_
SIGNAL_
NUMBER
210
The signal handler cannot be set.
ERROR_
THREAD_1_
INACTIVE
212
The segment is locked and cannot be reallocated.
ERROR_LOCKED
214
Too many dynamic-link modules are attached to this program or dynamiclink module.
ERROR_TOO_
MANY_MODULES
215
Cannot nest calls to LoadModule.
ERROR_
NESTING_NOT_
ALLOWED
216
The image file %1 is valid, but is for a machine type other than the current
machine.
ERROR_EXE_
MACHINE_TYPE_
MISMATCH
230
The pipe state is invalid.
ERROR_BAD_
PIPE
231
All pipe instances are busy.
ERROR_PIPE_
BUSY
232
The pipe is being closed.
ERROR_NO_
DATA
62
Chapter 4 External Error Codes
233
No process is on the other end of the pipe.
ERROR_PIPE_
NOT_
CONNECTED
234
More data is available.
ERROR_MORE_
DATA
240
The session was canceled.
ERROR_VC_
DISCONNECTED
254
The specified extended attribute name was invalid.
ERROR_
INVALID_EA_
NAME
255
The extended attributes are inconsistent.
ERROR_EA_
LIST_
INCONSISTENT
258
The wait operation timed out.
WAIT_TIMEOUT
259
No more data is available.
ERROR_NO_
MORE_ITEMS
266
The copy functions cannot be used.
ERROR_
CANNOT_COPY
267
The directory name is invalid.
ERROR_
DIRECTORY
275
The extended attributes did not fit in the buffer.
ERROR_EAS_
DIDNT_FIT
276
The extended attribute file on the mounted file system is corrupt.
ERROR_EA_
FILE_CORRUPT
277
The extended attribute table file is full.
ERROR_EA_
TABLE_FULL
278
The specified extended attribute handle is invalid.
ERROR_
INVALID_EA_
HANDLE
282
The mounted file system does not support extended attributes.
ERROR_EAS_
NOT_
SUPPORTED
288
Attempt to release mutex not owned by caller.
ERROR_NOT_
OWNER
298
Too many posts were made to a semaphore.
ERROR_TOO_
MANY_POSTS
299
Only part of a ReadProcessMemory or WriteProcessMemory request was
completed.
ERROR_
PARTIAL_COPY
300
The oplock request is denied.
ERROR_
OPLOCK_NOT_
GRANTED
301
An invalid oplock acknowledgment was received by the system.
ERROR_
INVALID_
OPLOCK_
PROTOCOL
Automation Engine
317
The system cannot find message text for message number 0x%1 in the
message file for %2.
ERROR_MR_
MID_NOT_
FOUND
487
Attempt to access invalid address.
ERROR_
INVALID_
ADDRESS
534
Arithmetic result exceeded 32 bits.
ERROR_
ARITHMETIC_
OVERFLOW
535
There is a process on other end of the pipe.
ERROR_PIPE_
CONNECTED
536
Waiting for a process to open the other end of the pipe.
ERROR_PIPE_
LISTENING
994
Access to the extended attribute was denied.
ERROR_EA_
ACCESS_
DENIED
995
The I/O operation has been aborted because of either a thread exit or an
application request.
ERROR_
OPERATION_
ABORTED
996
Overlapped I/O event is not in a signaled state.
ERROR_IO_
INCOMPLETE
997
Overlapped I/O operation is in progress.
ERROR_IO_
PENDING
998
Invalid access to memory location.
ERROR_
NOACCESS
999
Error performing inpage operation. ERROR_
SWAPERROR 63
4.5.2 Win32 - Error Codes (1000 - 1999)
The following table provides a list of Win32 error codes.
Code Description
Name
1001
Recursion too deep; the stack overflowed.
ERROR_STACK_
OVERFLOW
1002
The window cannot act on the sent message.
ERROR_INVALID_
MESSAGE
1003
Cannot complete this function.
ERROR_CAN_NOT_
COMPLETE
1004
Invalid flags.
ERROR_INVALID_
FLAGS
1005
The volume does not contain a recognized file system. Please make sure ERROR_
that all required file system drivers are loaded and that the volume is not
UNRECOGNIZED_
corrupted.
VOLUME
1006
The volume for a file has been externally altered so that the opened file is
no longer valid.
ERROR_FILE_
INVALID
64
Chapter 4 External Error Codes
1007
The requested operation cannot be performed in full-screen mode.
ERROR_
FULLSCREEN_
MODE
1008
An attempt was made to reference a token that does not exist.
ERROR_NO_
TOKEN
1009
The configuration registry database is corrupt.
ERROR_BADDB
1010
The configuration registry key is invalid.
ERROR_BADKEY
1011
The configuration registry key could not be opened.
ERROR_
CANTOPEN
1012
The configuration registry key could not be read.
ERROR_
CANTREAD
1013
The configuration registry key could not be written.
ERROR_
CANTWRITE
1014
One of the files in the registry database had to be recovered by use of a
log or alternate copy. The recovery was successful.
ERROR_
REGISTRY_
RECOVERED
1015
The registry is corrupted. The structure of one of the files that contains
ERROR_
registry data is corrupted, or the system's image of the file in memory is
REGISTRY_
corrupted, or the file could not be recovered because the alternate copy or CORRUPT
log was absent or corrupted.
1016
An I/O operation initiated by the registry failed unrecoverably. The registry ERROR_
could not read in, or write out, or flush, one of the files that contain the
REGISTRY_IO_
system's image of the registry.
FAILED
1017
The system has attempted to load or restore a file into the registry, but the ERROR_NOT_
specified file is not in a registry file format.
REGISTRY_FILE
1018
Illegal operation attempted on a registry key that has been marked for
deletion.
ERROR_KEY_
DELETED
1019
System could not allocate the required space in a registry log.
ERROR_NO_LOG_
SPACE
1020
Cannot create a symbolic link in a registry key that already has subkeys
or values.
ERROR_KEY_HAS_
CHILDREN
1021
Cannot create a stable subkey under a volatile parent key.
ERROR_CHILD_
MUST_BE_
VOLATILE
1022
A notify change request is being completed and the information is not
being returned in the caller's buffer. The caller now must enumerate the
files to find the changes.
ERROR_NOTIFY_
ENUM_DIR
1051
A stop control has been sent to a service that other running services are
dependent on.
ERROR_
DEPENDENT_
SERVICES_
RUNNING
1052
The requested control is not valid for this service.
ERROR_INVALID_
SERVICE_
CONTROL
1053
The service did not respond to the start or control request in a timely
fashion.
ERROR_SERVICE_
REQUEST_
TIMEOUT
Automation Engine
65
1054
A thread could not be created for the service.
ERROR_SERVICE_
NO_THREAD
1055
The service database is locked.
ERROR_SERVICE_
DATABASE_
LOCKED
1056
An instance of the service is already running.
ERROR_SERVICE_
ALREADY_
RUNNING
1057
The account name is invalid or does not exist.
ERROR_INVALID_
SERVICE_
ACCOUNT
1058
The service cannot be started, either because it is disabled or because it
has no enabled devices associated with it.
ERROR_SERVICE_
DISABLED
1059
Circular service dependency was specified.
ERROR_
CIRCULAR_
DEPENDENCY
1060
The specified service does not exist as an installed service.
ERROR_SERVICE_
DOES_NOT_EXIST
1061
The service cannot accept control messages at this time.
ERROR_SERVICE_
CANNOT_ACCEPT_
CTRL
1062
The service has not been started.
ERROR_SERVICE_
NOT_ACTIVE
1063
The service process could not connect to the service controller.
ERROR_FAILED_
SERVICE_
CONTROLLER_
CONNECT
1064
An exception occurred in the service when handling the control request.
ERROR_
EXCEPTION_IN_
SERVICE
1065
The database specified does not exist.
ERROR_
DATABASE_DOES_
NOT_EXIST
1066
The service has returned a service-specific error code.
ERROR_SERVICE_
SPECIFIC_ERROR
1067
The process terminated unexpectedly.
ERROR_
PROCESS_
ABORTED
1068
The dependency service or group failed to start.
ERROR_SERVICE_
DEPENDENCY_
FAIL
1069
The service did not start due to a logon failure.
ERROR_SERVICE_
LOGON_FAILED
1070
After starting, the service hung in a start-pending state.
ERROR_SERVICE_
START_HANG
1071
The specified service database lock is invalid.
ERROR_INVALID_
SERVICE_LOCK
66
Chapter 4 External Error Codes
1072
The specified service has been marked for deletion.
ERROR_SERVICE_
MARKED_FOR_
DELETE
1073
The specified service already exists.
ERROR_SERVICE_
EXISTS
1074
The system is currently running with the last-known-good configuration.
ERROR_ALREADY_
RUNNING_LKG
1075
The dependency service does not exist or has been marked for deletion.
ERROR_SERVICE_
DEPENDENCY_
DELETED
1076
The current boot has already been accepted for use as the last-knowngood control set.
ERROR_BOOT_
ALREADY_
ACCEPTED
1077
No attempts to start the service have been made since the last boot.
ERROR_SERVICE_
NEVER_STARTED
1078
The name is already in use as either a service name or a service display
name.
ERROR_
DUPLICATE_
SERVICE_NAME
1079
The account specified for this service is different from the account
specified for other services running in the same process.
ERROR_
DIFFERENT_
SERVICE_
ACCOUNT
1080
Failure actions can only be set for Win32 services, not for drivers.
ERROR_CANNOT_
DETECT_DRIVER_
FAILURE
1081
This service runs in the same process as the service control manager.
ERROR_CANNOT_
Therefore, the service control manager cannot take action if this service's DETECT_
process terminates unexpectedly.
PROCESS_ABORT
1082
No recovery program has been configured for this service.
ERROR_NO_
RECOVERY_
PROGRAM
1083
The executable program that this service is configured to run in does not
implement the service.
ERROR_SERVICE_
NOT_IN_EXE
1100
The physical end of the tape has been reached.
ERROR_END_OF_
MEDIA
1101
A tape access reached a filemark.
ERROR_
FILEMARK_
DETECTED
1102
The beginning of the tape or a partition was encountered.
ERROR_
BEGINNING_OF_
MEDIA
1103
A tape access reached the end of a set of files.
ERROR_
SETMARK_
DETECTED
1104
No more data is on the tape.
ERROR_NO_DATA_
DETECTED
Automation Engine
67
1105
Tape could not be partitioned.
ERROR_
PARTITION_
FAILURE
1106
When accessing a new tape of a multivolume partition, the current block
size is incorrect.
ERROR_INVALID_
BLOCK_LENGTH
1107
Tape partition information could not be found when loading a tape.
ERROR_DEVICE_
NOT_PARTITIONED
1108
Unable to lock the media eject mechanism.
ERROR_UNABLE_
TO_LOCK_MEDIA
1109
Unable to unload the media.
ERROR_UNABLE_
TO_UNLOAD_
MEDIA
1110
The media in the drive can have changed.
ERROR_MEDIA_
CHANGED
1111
The I/O bus was reset.
ERROR_BUS_
RESET
1112
No media in drive.
ERROR_NO_
MEDIA_IN_DRIVE
1113
No mapping for the Unicode character exists in the target multi-byte code ERROR_NO_
page.
UNICODE_
TRANSLATION
1114
A dynamic link library (DLL) initialization routine failed.
ERROR_DLL_INIT_
FAILED
1115
A system shutdown is in progress.
ERROR_
SHUTDOWN_IN_
PROGRESS
1116
Unable to abort the system shutdown because no shutdown was in
progress.
ERROR_NO_
SHUTDOWN_IN_
PROGRESS
1117
The request could not be performed because of an I/O device error.
ERROR_IO_
DEVICE
1118
No serial device was successfully initialized. The serial driver will unload. ERROR_SERIAL_
NO_DEVICE
1119
Unable to open a device that was sharing an interrupt request (IRQ) with
other devices. At least one other device that uses that IRQ was already
opened.
ERROR_IRQ_BUSY
1120
A serial I/O operation was completed by another write to the serial port.
(The IOCTL_SERIAL_XOFF_COUNTER reached zero.)
ERROR_MORE_
WRITES
1121
A serial I/O operation completed because the timeout period expired. (The ERROR_
IOCTL_SERIAL_XOFF_COUNTER did not reach zero.)
COUNTER_
TIMEOUT
1122
No ID address mark was found on the floppy disk.
ERROR_FLOPPY_
ID_MARK_NOT_
FOUND
1123
Mismatch between the floppy disk sector ID field and the floppy disk
controller track address.
ERROR_FLOPPY_
WRONG_
CYLINDER
68
Chapter 4 External Error Codes
1124
The floppy disk controller reported an error that is not recognized by the
floppy disk driver.
ERROR_FLOPPY_
UNKNOWN_
ERROR
1125
The floppy disk controller returned inconsistent results in its registers.
ERROR_FLOPPY_
BAD_REGISTERS
1126
While accessing the hard disk, a recalibrate operation failed, even after
retries.
ERROR_DISK_
RECALIBRATE_
FAILED
1127
While accessing the hard disk, a disk operation failed even after retries.
ERROR_DISK_
OPERATION_
FAILED
1128
While accessing the hard disk, a disk controller reset was needed, but
even that failed.
ERROR_DISK_
RESET_FAILED
1129
Physical end of tape encountered.
ERROR_EOM_
OVERFLOW
1130
Not enough server storage is available to process this command.
ERROR_NOT_
ENOUGH_
SERVER_MEMORY
1131
A potential deadlock condition has been detected.
ERROR_
POSSIBLE_
DEADLOCK
1132
The base address or the file offset specified does not have the proper
alignment.
ERROR_MAPPED_
ALIGNMENT
1140
An attempt to change the system power state was vetoed by another
application or driver.
ERROR_SET_
POWER_STATE_
VETOED
1141
The system BIOS failed an attempt to change the system power state.
ERROR_SET_
POWER_STATE_
FAILED
1142
An attempt was made to create more links on a file than the file system
supports.
ERROR_TOO_
MANY_LINKS
1150
The specified program requires a newer version of Windows.
ERROR_OLD_WIN_
VERSION
1151
The specified program is not a Windows or MS-DOS program.
ERROR_APP_
WRONG_OS
1152
Cannot start more than one instance of the specified program.
ERROR_SINGLE_
INSTANCE_APP
1153
The specified program was written for an earlier version of Windows.
ERROR_RMODE_
APP
1154
One of the library files needed to run this application is damaged.
ERROR_INVALID_
DLL
1155
No application is associated with the specified file for this operation.
ERROR_NO_
ASSOCIATION
1156
An error occurred in sending the command to the application.
ERROR_DDE_FAIL
1157
One of the library files needed to run this application cannot be found.
ERROR_DLL_NOT_
FOUND
Automation Engine
69
1158
The current process has used all of its system allowance of handles for
Window Manager objects.
ERROR_NO_
MORE_USER_
HANDLES
1159
The message can be used only with synchronous operations.
ERROR_
MESSAGE_SYNC_
ONLY
1160
The indicated source element has no media.
ERROR_SOURCE_
ELEMENT_EMPTY
1161
The indicated destination element already contains media.
ERROR_
DESTINATION_
ELEMENT_FULL
1162
The indicated element does not exist.
ERROR_ILLEGAL_
ELEMENT_
ADDRESS
1163
The indicated element is part of a magazine that is not present.
ERROR_
MAGAZINE_NOT_
PRESENT
1164
The indicated device requires reinitialization due to hardware errors.
ERROR_DEVICE_
REINITIALIZATION_
NEEDED
1165
The device has indicated that cleaning is required before further
operations are attempted.
ERROR_DEVICE_
REQUIRES_
CLEANING
1166
The device has indicated that its door is open.
ERROR_DEVICE_
DOOR_OPEN
1167
The device is not connected.
ERROR_DEVICE_
NOT_CONNECTED
1168
Element not found.
ERROR_NOT_
FOUND
1169
There was no match for the specified key in the index.
ERROR_NO_
MATCH
1170
The property set specified does not exist on the object.
ERROR_SET_NOT_
FOUND
1171
The point passed to GetMouseMovePointsEx is not in the buffer.
ERROR_POINT_
NOT_FOUND
1172
The tracking (workstation) service is not running.
ERROR_NO_
TRACKING_
SERVICE
1173
The Volume ID could not be found.
ERROR_NO_
VOLUME_ID
1174
The specified Very Large Memory (64-bit) operation is invalid.
ERROR_INVALID_
VLM_OPERATION
1175
Unable to remove the file to be replaced.
ERROR_UNABLE_
TO_REMOVE_
REPLACED
70
Chapter 4 External Error Codes
1176
Unable to move the replacement file to the file to be replaced. The file to
be replaced has retained its original name.
ERROR_UNABLE_
TO_MOVE_
REPLACEMENT
1177
Unable to move the replacement file to the file to be replaced. The file to
be replaced has been renamed using the backup name.
ERROR_UNABLE_
TO_MOVE_
REPLACEMENT_2
1178
The volume change journal is being deleted.
ERROR_JOURNAL_
DELETE_IN_
PROGRESS
1179
The volume change journal service is not active.
ERROR_JOURNAL_
NOT_ACTIVE
1180
A file was found, but it cannot be the correct file.
ERROR_
POTENTIAL_FILE_
FOUND
1181
The journal entry has been deleted from the journal.
ERROR_JOURNAL_
ENTRY_DELETED
1200
The specified device name is invalid.
ERROR_BAD_
DEVICE
1201
The device is not currently connected but it is a remembered connection.
ERROR_
CONNECTION_
UNAVAIL
1202
An attempt was made to remember a device that had previously been
remembered.
ERROR_DEVICE_
ALREADY_
REMEMBERED
1203
No network provider accepted the given network path.
ERROR_NO_NET_
OR_BAD_PATH
1204
The specified network provider name is invalid.
ERROR_BAD_
PROVIDER
1205
Unable to open the network connection profile.
ERROR_CANNOT_
OPEN_PROFILE
1206
The network connection profile is corrupted.
ERROR_BAD_
PROFILE
1207
Cannot enumerate a noncontainer.
ERROR_NOT_
CONTAINER
1208
An extended error has occurred.
ERROR_
EXTENDED_
ERROR
1209
The format of the specified group name is invalid.
ERROR_INVALID_
GROUPNAME
1210
The format of the specified computer name is invalid.
ERROR_INVALID_
COMPUTERNAME
1211
The format of the specified event name is invalid.
ERROR_INVALID_
EVENTNAME
1212
The format of the specified domain name is invalid.
ERROR_INVALID_
DOMAINNAME
1213
The format of the specified service name is invalid.
ERROR_INVALID_
SERVICENAME
Automation Engine
71
1214
The format of the specified network name is invalid.
ERROR_INVALID_
NETNAME
1215
The format of the specified share name is invalid.
ERROR_INVALID_
SHARENAME
1216
The format of the specified password is invalid.
ERROR_INVALID_
PASSWORDNAME
1217
The format of the specified message name is invalid.
ERROR_INVALID_
MESSAGENAME
1218
The format of the specified message destination is invalid.
ERROR_INVALID_
MESSAGEDEST
1219
The credentials supplied conflict with an existing set of credentials.
ERROR_SESSION_
CREDENTIAL_
CONFLICT
1220
An attempt was made to establish a session to a network server, but
there are already too many sessions established to that server.
ERROR_REMOTE_
SESSION_LIMIT_
EXCEEDED
1221
The workgroup or domain name is already in use by another computer on
the network.
ERROR_DUP_
DOMAINNAME
1222
The network is not present or not started.
ERROR_NO_
NETWORK
1223
The operation was canceled by the user.
ERROR_
CANCELED
1224
The requested operation cannot be performed on a file with a usermapped section open.
ERROR_USER_
MAPPED_FILE
1225
The remote system refused the network connection.
ERROR_
CONNECTION_
REFUSED
1226
The network connection was gracefully closed.
ERROR_
GRACEFUL_
DISCONNECT
1227
The network transport endpoint already has an address associated with it. ERROR_
ADDRESS_
ALREADY_
ASSOCIATED
1228
An address has not yet been associated with the network endpoint.
ERROR_
ADDRESS_NOT_
ASSOCIATED
1229
An operation was attempted on a nonexistent network connection.
ERROR_
CONNECTION_
INVALID
1230
An invalid operation was attempted on an active network connection.
ERROR_
CONNECTION_
ACTIVE
1231
The remote network is not reachable by the transport.
ERROR_
NETWORK_
UNREACHABLE
72
Chapter 4 External Error Codes
1232
The remote system is not reachable by the transport.
ERROR_HOST_
UNREACHABLE
1233
The remote system does not support the transport protocol.
ERROR_
PROTOCOL_
UNREACHABLE
1234
No service is operating at the destination network endpoint on the remote ERROR_PORT_
system.
UNREACHABLE
1235
The request was aborted.
ERROR_
REQUEST_
ABORTED
1236
The network connection was aborted by the local system.
ERROR_
CONNECTION_
ABORTED
1237
The operation could not be completed. A retry should be performed.
ERROR_RETRY
1238
A connection to the server could not be made because the limit on the
number of concurrent connections for this account has been reached.
ERROR_
CONNECTION_
COUNT_LIMIT
1239
Attempting to log in during an unauthorized time of day for this account.
ERROR_LOGIN_
TIME_
RESTRICTION
1240
The account is not authorized to log in from this station.
ERROR_LOGIN_
WKSTA_
RESTRICTION
1241
The network address could not be used for the operation requested.
ERROR_
INCORRECT_
ADDRESS
1242
The service is already registered.
ERROR_ALREADY_
REGISTERED
1243
The specified service does not exist.
ERROR_SERVICE_
NOT_FOUND
1244
The operation being requested was not performed because the user has
not been authenticated.
ERROR_NOT_
AUTHENTICATED
1245
The operation being requested was not performed because the user has
not logged on to the network. The specified service does not exist.
ERROR_NOT_
LOGGED_ON
1246
Continue with work in progress.
ERROR_CONTINUE
1247
An attempt was made to perform an initialization operation when
initialization has already been completed.
ERROR_ALREADY_
INITIALIZED
1248
No more local devices.
ERROR_NO_
MORE_DEVICES
1249
The specified site does not exist.
ERROR_NO_
SUCH_SITE
1250
A domain controller with the specified name already exists.
ERROR_DOMAIN_
CONTROLLER_
EXISTS
1251
This operation is supported only when you are connected to the server.
ERROR_ONLY_IF_
CONNECTED
Automation Engine
73
1300
Not all privileges referenced are assigned to the caller.
ERROR_NOT_ALL_
ASSIGNED
1301
Some mapping between account names and security IDs was not done.
ERROR_SOME_
NOT_MAPPED
1302
No system quota limits are specifically set for this account.
ERROR_NO_
QUOTAS_FOR_
ACCOUNT
1303
No encryption key is available. A well-known encryption key was
returned.
ERROR_LOCAL_
USER_SESSION_
KEY
1304
The Windows NT password is too complex to be converted to a LAN
Manager password. The LAN Manager password returned is a NULL
string.
ERROR_NULL_LM_
PASSWORD
1305
The revision level is unknown.
ERROR_
UNKNOWN_
REVISION
1306
Indicates two revision levels are incompatible.
ERROR_
REVISION_
MISMATCH
1307
This security ID cannot be assigned as the owner of this object.
ERROR_INVALID_
OWNER
1308
This security ID cannot be assigned as the primary group of an object.
ERROR_INVALID_
PRIMARY_GROUP
1309
An attempt has been made to operate on an impersonation token by a
thread that is not currently impersonating a client.
ERROR_NO_
IMPERSONATION_
TOKEN
1310
The group cannot be disabled.
ERROR_CANT_
DISABLE_
MANDATORY
1311
There are currently no logon servers available to service the logon
request.
ERROR_NO_
LOGON_SERVERS
1312
A specified logon session does not exist. It can already have been
terminated.
ERROR_NO_
SUCH_LOGON_
SESSION
1313
A specified privilege does not exist.
ERROR_NO_
SUCH_PRIVILEGE
1314
A required privilege is not held by the client.
ERROR_
PRIVILEGE_NOT_
HELD
1315
The name provided is not a properly formed account name.
ERROR_INVALID_
ACCOUNT_NAME
1316
The specified user already exists.
ERROR_USER_
EXISTS
1317
The specified user does not exist.
ERROR_NO_
SUCH_USER
1318
The specified group already exists.
ERROR_GROUP_
EXISTS
74
Chapter 4 External Error Codes
1319
The specified group does not exist.
ERROR_NO_
SUCH_GROUP
1320
Either the specified user account is already a member of the specified
group, or the specified group cannot be deleted because it contains a
member.
ERROR_MEMBER_
IN_GROUP
1321
The specified user account is not a member of the specified group
account.
ERROR_MEMBER_
NOT_IN_GROUP
1322
The last remaining administration account cannot be disabled or deleted.
ERROR_LAST_
ADMIN
1323
Unable to update the password. The value provided as the current
password is incorrect.
ERROR_WRONG_
PASSWORD
1324
Unable to update the password. The value provided for the new password ERROR_ILL_
contains values that are not allowed in passwords.
FORMED_
PASSWORD
1325
Unable to update the password because a password update rule has been ERROR_
violated.
PASSWORD_
RESTRICTION
1326
Logon failure: unknown user name or bad password.
ERROR_LOGON_
FAILURE
1327
Logon failure: user account restriction.
ERROR_
ACCOUNT_
RESTRICTION
1328
Logon failure: account logon time restriction violation.
ERROR_INVALID_
LOGON_HOURS
1329
Logon failure: user not allowed to log on to this computer.
ERROR_INVALID_
WORKSTATION
1330
Logon failure: the specified account password has expired.
ERROR_
PASSWORD_
EXPIRED
1331
Logon failure: account currently disabled.
ERROR_
ACCOUNT_
DISABLED
1332
No mapping between account names and security IDs was done.
ERROR_NONE_
MAPPED
1333
Too many local user identifiers (LUIDs) were requested at one time.
ERROR_TOO_
MANY_LUIDS_
REQUESTED
1334
No more local user identifiers (LUIDs) are available.
ERROR_LUIDS_
EXHAUSTED
1335
The subauthority part of a security ID is invalid for this particular use.
ERROR_INVALID_
SUB_AUTHORITY
1336
The access control list (ACL) structure is invalid.
ERROR_INVALID_
ACL
1337
The security ID structure is invalid.
ERROR_INVALID_
SID
1338
The security descriptor structure is invalid.
ERROR_INVALID_
SECURITY_DESCR
Automation Engine
75
1340
The inherited access control list (ACL) or access control entry (ACE)
could not be built.
ERROR_BAD_
INHERITANCE_ACL
1341
The server is currently disabled.
ERROR_SERVER_
DISABLED
1342
The server is currently enabled.
ERROR_SERVER_
NOT_DISABLED
1343
The value provided was an invalid value for an identifier authority.
ERROR_INVALID_
ID_AUTHORITY
1344
No more memory is available for security information updates.
ERROR_
ALLOTTED_
SPACE_
EXCEEDED
1345
The specified attributes are invalid, or incompatible with the attributes for
the group as a whole.
ERROR_INVALID_
GROUP_
ATTRIBUTES
1346
Either a required impersonation level was not provided, or the provided
impersonation level is invalid.
ERROR_BAD_
IMPERSONATION_
LEVEL
1347
Cannot open an anonymous level security token.
ERROR_CANT_
OPEN_
ANONYMOUS
1348
The validation information class requested was invalid.
ERROR_BAD_
VALIDATION_
CLASS
1349
The type of the token is inappropriate for its attempted use.
ERROR_BAD_
TOKEN_TYPE
1350
Unable to perform a security operation on an object that has no
associated security.
ERROR_NO_
SECURITY_ON_
OBJECT
1351
Configuration information could not be read from the domain controller,
either because the machine is unavailable, or access has been denied.
ERROR_CANT_
ACCESS_DOMAIN_
INFO
1352
The security account manager (SAM) or local security authority (LSA)
server was in the wrong state to perform the security operation.
ERROR_INVALID_
SERVER_STATE
1353
The domain was in the wrong state to perform the security operation.
ERROR_INVALID_
DOMAIN_STATE
1354
This operation is only allowed for the Primary Domain Controller of the
domain.
ERROR_INVALID_
DOMAIN_ROLE
1355
The specified domain did not exist.
ERROR_NO_
SUCH_DOMAIN
1356
The specified domain already exists.
ERROR_DOMAIN_
EXISTS
1357
An attempt was made to exceed the limit on the number of domains per
server.
ERROR_DOMAIN_
LIMIT_EXCEEDED
1358
Unable to complete the requested operation because of either a
catastrophic media failure or a data structure corruption on the disk.
ERROR_
INTERNAL_DB_
CORRUPTION
76
Chapter 4 External Error Codes
1359
The security account database contains an internal inconsistency.
ERROR_
INTERNAL_ERROR
1360
Generic access types were contained in an access mask which should
already be mapped to nongeneric types.
ERROR_GENERIC_
NOT_MAPPED
1361
A security descriptor is not in the right format (absolute or self-relative).
ERROR_BAD_
DESCRIPTOR_
FORMAT
1362
The requested action is restricted for use by logon processes only. The
calling process has not registered as a logon process.
ERROR_NOT_
LOGON_PROCESS
1363
Cannot start a new logon session with an ID that is already in use.
ERROR_LOGON_
SESSION_EXISTS
1364
A specified authentication package is unknown.
ERROR_NO_
SUCH_PACKAGE
1365
The logon session is not in a state that is consistent with the requested
operation.
ERROR_BAD_
LOGON_SESSION_
STATE
1366
The logon session ID is already in use.
ERROR_LOGON_
SESSION_
COLLISION
1367
A logon request contained an invalid logon type value.
ERROR_INVALID_
LOGON_TYPE
1368
Unable to impersonate using a named pipe until data has been read from
that pipe.
ERROR_CANNOT_
IMPERSONATE
1369
The transaction state of a registry subtree is incompatible with the
requested operation.
ERROR_RXACT_
INVALID_STATE
1370
An internal security database corruption has been encountered.
ERROR_RXACT_
COMMIT_FAILURE
1371
Cannot perform this operation on built-in accounts.
ERROR_SPECIAL_
ACCOUNT
1372
Cannot perform this operation on this built-in special group.
ERROR_SPECIAL_
GROUP
1373
Cannot perform this operation on this built-in special user.
ERROR_SPECIAL_
USER
1374
The user cannot be removed from a group because the group is currently
the user's primary group.
ERROR_
MEMBERS_
PRIMARY_GROUP
1375
The token is already in use as a primary token.
ERROR_TOKEN_
ALREADY_IN_USE
1376
The specified local group does not exist.
ERROR_NO_
SUCH_ALIAS
1377
The specified account name is not a member of the local group.
ERROR_MEMBER_
NOT_IN_ALIAS
1378
The specified account name is already a member of the local group.
ERROR_MEMBER_
IN_ALIAS
1379
The specified local group already exists.
ERROR_ALIAS_
EXISTS
Automation Engine
77
1380
Logon failure: the user has not been granted the requested logon type at
this computer.
ERROR_LOGON_
NOT_GRANTED
1381
The maximum number of secrets that can be stored in a single system
has been exceeded.
ERROR_TOO_
MANY_SECRETS
1382
The length of a secret exceeds the maximum length allowed.
ERROR_SECRET_
TOO_LONG
1383
The local security authority database contains an internal inconsistency.
ERROR_
INTERNAL_DB_
ERROR
1384
During a logon attempt, the user's security context accumulated too
many security IDs.
ERROR_TOO_
MANY_CONTEXT_
IDS
1385
Logon failure: the user has not been granted the requested logon type at
this computer.
ERROR_LOGON_
TYPE_NOT_
GRANTED
1386
A cross-encrypted password is necessary to change a user password.
ERROR_NT_
CROSS_
ENCRYPTION_
REQUIRED
1387
A new member could not be added to a local group because the member
does not exist.
ERROR_NO_
SUCH_MEMBER
1388
A new member could not be added to a local group because the member
has the wrong account type.
ERROR_INVALID_
MEMBER
1389
Too many security IDs have been specified.
ERROR_TOO_
MANY_SIDS
1390
A cross-encrypted password is necessary to change this user password. ERROR_LM_
CROSS_
ENCRYPTION_
REQUIRED
1391
Indicates an ACL contains no inheritable components.
ERROR_NO_
INHERITANCE
1392
The file or directory is corrupted and unreadable.
ERROR_FILE_
CORRUPT
1393
The disk structure is corrupted and unreadable.
ERROR_DISK_
CORRUPT
1394
There is no user session key for the specified logon session.
ERROR_NO_
USER_SESSION_
KEY
1395
The service being accessed is licensed for a particular number of
connections. No more connections can be made to the service at this
time because there are already as many connections as the service can
accept.
ERROR_LICENSE_
QUOTA_
EXCEEDED
1396
Logon Failure: The target account name is incorrect.
ERROR_WRONG_
TARGET_NAME
1397
Mutual Authentication failed. The server's password is out of date at the
domain controller.
ERROR_MUTUAL_
AUTH_FAILED
78
Chapter 4 External Error Codes
1398
There is a time difference between the client and server.
ERROR_TIME_
SKEW
1400
Invalid window handle.
ERROR_INVALID_
WINDOW_HANDLE
1401
Invalid menu handle.
ERROR_INVALID_
MENU_HANDLE
1402
Invalid cursor handle.
ERROR_INVALID_
CURSOR_HANDLE
1403
Invalid accelerator table handle.
ERROR_INVALID_
ACCEL_HANDLE
1404
Invalid hook handle.
ERROR_INVALID_
HOOK_HANDLE
1405
Invalid handle to a multiple-window position structure.
ERROR_INVALID_
DWP_HANDLE
1406
Cannot create a top-level child window.
ERROR_TLW_
WITH_WSCHILD
1407
Cannot find window class.
ERROR_CANNOT_
FIND_WND_CLASS
1408
Invalid window; it belongs to other thread.
ERROR_WINDOW_
OF_OTHER_
THREAD
1409
Hot key is already registered.
ERROR_HOTKEY_
ALREADY_
REGISTERED
1410
Class already exists.
ERROR_CLASS_
ALREADY_EXISTS
1411
Class does not exist.
ERROR_CLASS_
DOES_NOT_EXIST
1412
Class still has open windows.
ERROR_CLASS_
HAS_WINDOWS
1413
Invalid index.
ERROR_INVALID_
INDEX
1414
Invalid icon handle.
ERROR_INVALID_
ICON_HANDLE
1415
Using private DIALOG window words.
ERROR_PRIVATE_
DIALOG_INDEX
1416
The list box identifier was not found.
ERROR_LISTBOX_
ID_NOT_FOUND
1417
No wildcards were found.
ERROR_NO_
WILDCARD_
CHARACTERS
1418
Thread does not have a clipboard open.
ERROR_
CLIPBOARD_NOT_
OPEN
1419
Hot key is not registered.
ERROR_HOTKEY_
NOT_REGISTERED
Automation Engine
79
1420
The window is not a valid dialog window.
ERROR_WINDOW_
NOT_DIALOG
1421
Control ID not found.
ERROR_
CONTROL_ID_
NOT_FOUND
1422
Invalid message for a combo box because it does not have an edit
control.
ERROR_INVALID_
COMBOBOX_
MESSAGE
1423
The window is not a combo box.
ERROR_WINDOW_
NOT_COMBOBOX
1424
Height must be less than 256.
ERROR_INVALID_
EDIT_HEIGHT
1425
Invalid device context (DC) handle.
ERROR_DC_NOT_
FOUND
1426
Invalid hook procedure type.
ERROR_INVALID_
HOOK_FILTER
1427
Invalid hook procedure.
ERROR_INVALID_
FILTER_PROC
1428
Cannot set nonlocal hook without a module handle.
ERROR_HOOK_
NEEDS_HMOD
1429
This hook procedure can only be set globally.
ERROR_GLOBAL_
ONLY_HOOK
1430
The journal hook procedure is already installed.
ERROR_JOURNAL_
HOOK_SET
1431
The hook procedure is not installed.
ERROR_HOOK_
NOT_INSTALLED
1432
Invalid message for single-selection list box.
ERROR_INVALID_
LB_MESSAGE
1433
LB_SETCOUNT sent to non-lazy list box.
ERROR_
SETCOUNT_ON_
BAD_LB
1434
This list box does not support tab stops.
ERROR_LB_
WITHOUT_
TABSTOPS
1435
Cannot destroy object created by another thread.
ERROR_
DESTROY_
OBJECT_OF_
OTHER_THREAD
1436
Child windows cannot have menus.
ERROR_CHILD_
WINDOW_MENU
1437
The window does not have a system menu.
ERROR_NO_
SYSTEM_MENU
1438
Invalid message box style.
ERROR_INVALID_
MSGBOX_STYLE
1439
Invalid system-wide (SPI_*) parameter.
ERROR_INVALID_
SPI_VALUE
80
Chapter 4 External Error Codes
1440
Screen already locked.
ERROR_SCREEN_
ALREADY_LOCKED
1441
All handles to windows in a multiple-window position structure must have ERROR_HWNDS_
the same parent.
HAVE_DIFF_
PARENT
1442
The window is not a child window.
ERROR_NOT_
CHILD_WINDOW
1443
Invalid GW_* command.
ERROR_INVALID_
GW_COMMAND
1444
Invalid thread identifier.
ERROR_INVALID_
THREAD_ID
1445
Cannot process a message from a window that is not a multiple
document interface (MDI) window.
ERROR_NON_
MDICHILD_
WINDOW
1446
Context menu already active.
ERROR_POPUP_
ALREADY_ACTIVE
1447
The window does not have scroll bars.
ERROR_NO_
SCROLLBARS
1448
Scroll bar range cannot be greater than 0x7FFF.
ERROR_INVALID_
SCROLLBAR_
RANGE
1449
Cannot show or remove the window in the way specified.
ERROR_INVALID_
SHOWWIN_
COMMAND
1450
Insufficient system resources exist to complete the requested service.
ERROR_NO_
SYSTEM_
RESOURCES
1451
Insufficient system resources exist to complete the requested service.
ERROR_
NONPAGED_
SYSTEM_
RESOURCES
1452
Insufficient system resources exist to complete the requested service.
ERROR_PAGED_
SYSTEM_
RESOURCES
1453
Insufficient quota to complete the requested service.
ERROR_
WORKING_SET_
QUOTA
1454
Insufficient quota to complete the requested service.
ERROR_
PAGEFILE_QUOTA
1455
The paging file is too small for this operation to complete.
ERROR_
COMMITMENT_
LIMIT
1456
A menu item was not found.
ERROR_MENU_
ITEM_NOT_FOUND
1457
Invalid keyboard layout handle.
ERROR_INVALID_
KEYBOARD_
HANDLE
Automation Engine
81
1458
Hook type not allowed.
ERROR_HOOK_
TYPE_NOT_
ALLOWED
1459
This operation requires an interactive window station.
ERROR_
REQUIRES_
INTERACTIVE_
WINDOWSTATION
1460
This operation returned because the timeout period expired.
ERROR_TIMEOUT
1461
Invalid monitor handle.
ERROR_INVALID_
MONITOR_HANDLE
1500
The event log file is corrupted.
ERROR_
EVENTLOG_FILE_
CORRUPT
1501
No event log file could be opened, so the event logging service did not
start.
ERROR_
EVENTLOG_CANT_
START
1502
The event log file is full.
ERROR_LOG_FILE_
FULL
1503
The event log file has changed between read operations.
ERROR_
EVENTLOG_FILE_
CHANGED
1601
Failure accessing installation service.
ERROR_INSTALL_
SERVICE_FAILURE
1602
User canceled installation.
ERROR_INSTALL_
USEREXIT
1603
Fatal error during installation.
ERROR_INSTALL_
FAILURE
1604
Installation suspended, incomplete.
ERROR_INSTALL_
SUSPEND
1605
Product is not installed.
ERROR_
UNKNOWN_
PRODUCT
1606
Feature ID not registered.
ERROR_
UNKNOWN_
FEATURE
1607
Component ID not registered.
ERROR_
UNKNOWN_
COMPONENT
1608
Unknown property.
ERROR_
UNKNOWN_
PROPERTY
1609
Handle is in an invalid state.
ERROR_INVALID_
HANDLE_STATE
1610
Configuration data corrupt.
ERROR_BAD_
CONFIGURATION
1611
Component qualifier not present.
ERROR_INDEX_
ABSENT
82
Chapter 4 External Error Codes
1612
Install source unavailable.
ERROR_INSTALL_
SOURCE_ABSENT
1613
Database version unsupported.
ERROR_INSTALL_
PACKAGE_
VERSION
1614
Product is uninstalled.
ERROR_
PRODUCT_
UNINSTALLED
1615
SQL query syntax invalid or unsupported.
ERROR_BAD_
QUERY_SYNTAX
1616
Record field does not exist.
ERROR_INVALID_
FIELD
1617
The device has been removed.
ERROR_DEVICE_
REMOVED
1618
An installation is in progress.
ERROR_INSTALL_
ALREADY_
RUNNING
1619
Installation package could not be opened.
ERROR_INSTALL_
PACKAGE_OPEN_
FAILED
1620
Installation package invalid.
ERROR_INSTALL_
PACKAGE_INVALID
1621
Could not initialize installer user interface.
ERROR_INSTALL_
UI_FAILURE
1622
Error opening installation log file.
ERROR_INSTALL_
LOG_FAILURE
1623
Product language not supported by system.
ERROR_INSTALL_
LANGUAGE_
UNSUPPORTED
1624
Error applying transform to install package.
ERROR_INSTALL_
TRANSFORM_
FAILURE
1625
Install package signature not accepted.
ERROR_INSTALL_
PACKAGE_
REJECTED
1626
Function could not be executed.
ERROR_
FUNCTION_NOT_
CALLED
1627
Function failed during execution.
ERROR_
FUNCTION_FAILED
1628
Invalid or unknown table specified.
ERROR_INVALID_
TABLE
1629
Data supplied is of wrong type.
ERROR_
DATATYPE_
MISMATCH
Automation Engine
83
1630
Data of this type is not supported.
ERROR_
UNSUPPORTED_
TYPE
1631
Unable to create requested object.
ERROR_CREATE_
FAILED
1632
Temp folder is full or inaccessible.
ERROR_INSTALL_
TEMP_
UNWRITABLE
1633
Product platform not supported.
ERROR_INSTALL_
PLATFORM_
UNSUPPORTED
1634
Component not used on this computer.
ERROR_INSTALL_
NOTUSED
1635
Patch package could not be opened.
ERROR_PATCH_
PACKAGE_OPEN_
FAILED
1636
Patch package invalid.
ERROR_PATCH_
PACKAGE_INVALID
1637
Patch package unsupported.
ERROR_PATCH_
PACKAGE_
UNSUPPORTED.
1638
Invalid command line argument.
ERROR_INVALID_
COMMAND_LINE
1700
The string binding is invalid.
RPC_S_INVALID_
STRING_BINDING
1701
The binding handle is not the correct type.
RPC_S_WRONG_
KIND_OF_BINDING
1702
The binding handle is invalid.
RPC_S_INVALID_
BINDING
1703
The RPC protocol sequence is not supported.
RPC_S_PROTSEQ_
NOT_SUPPORTED
1704
The RPC protocol sequence is invalid.
RPC_S_INVALID_
RPC_PROTSEQ
1705
The string universal unique identifier (UUID) is invalid.
RPC_S_INVALID_
STRING_UUID
1706
The endpoint format is invalid.
RPC_S_INVALID_
ENDPOINT_
FORMAT
1707
The network address is invalid.
RPC_S_INVALID_
NET_ADDR
1708
No endpoint was found.
RPC_S_NO_
ENDPOINT_FOUND
1709
The timeout value is invalid.
RPC_S_INVALID_
TIMEOUT
1710
The object universal unique identifier (UUID) was not found.
RPC_S_OBJECT_
NOT_FOUND
84
Chapter 4 External Error Codes
1711
The object universal unique identifier (UUID) has already been registered. RPC_S_ALREADY_
REGISTERED
1712
The type universal unique identifier (UUID) has already been registered.
RPC_S_TYPE_
ALREADY_
REGISTERED
1713
The RPC server is already listening.
RPC_S_ALREADY_
LISTENING
1714
No protocol sequences have been registered.
RPC_S_NO_
PROTSEQS_
REGISTERED
1715
The RPC server is not listening.
RPC_S_NOT_
LISTENING
1716
The manager type is unknown.
RPC_S_
UNKNOWN_MGR_
TYPE
1717
The interface is unknown.
RPC_S_
UNKNOWN_IF
1718
There are no bindings.
RPC_S_NO_
BINDINGS
1719
There are no protocol sequences.
RPC_S_NO_
PROTSEQS
1720
The endpoint cannot be created.
RPC_S_CANT_
CREATE_
ENDPOINT
1721
Not enough resources are available to complete this operation.
RPC_S_OUT_OF_
RESOURCES
1722
The RPC server is unavailable.
RPC_S_SERVER_
UNAVAILABLE
1723
The RPC server is too busy to complete this operation.
RPC_S_SERVER_
TOO_BUSY
1724
The network options are invalid.
RPC_S_INVALID_
NETWORK_
OPTIONS
1725
There are no remote procedure calls active on this thread.
RPC_S_NO_CALL_
ACTIVE
1726
The remote procedure call failed.
RPC_S_CALL_
FAILED
1727
The remote procedure call failed and did not execute.
RPC_S_CALL_
FAILED_DNE
1728
A remote procedure call (RPC) protocol error occurred.
RPC_S_
PROTOCOL_
ERROR
1730
The transfer syntax is not supported by the RPC server.
RPC_S_
UNSUPPORTED_
TRANS_SYN
Automation Engine
85
1732
The universal unique identifier (UUID) type is not supported.
RPC_S_
UNSUPPORTED_
TYPE
1733
The tag is invalid.
RPC_S_INVALID_
TAG
1734
The array bounds are invalid.
RPC_S_INVALID_
BOUND
1735
The binding does not contain an entry name.
RPC_S_NO_
ENTRY_NAME
1736
The name syntax is invalid.
RPC_S_INVALID_
NAME_SYNTAX
1737
The name syntax is not supported.
RPC_S_
UNSUPPORTED_
NAME_SYNTAX
1739
No network address is available to use to construct a universal unique
identifier (UUID).
RPC_S_UUID_NO_
ADDRESS
1740
The endpoint is a duplicate.
RPC_S_
DUPLICATE_
ENDPOINT
1741
The authentication type is unknown.
RPC_S_
UNKNOWN_
AUTHN_TYPE
1742
The maximum number of calls is too small.
RPC_S_MAX_
CALLS_TOO_SMALL
1743
The string is too long.
RPC_S_STRING_
TOO_LONG
1744
The RPC protocol sequence was not found.
RPC_S_PROTSEQ_
NOT_FOUND
1745
The procedure number is out of range.
RPC_S_
PROCNUM_OUT_
OF_RANGE
1746
The binding does not contain any authentication information.
RPC_S_BINDING_
HAS_NO_AUTH
1747
The authentication service is unknown.
RPC_S_
UNKNOWN_
AUTHN_SERVICE
1748
The authentication level is unknown.
RPC_S_
UNKNOWN_
AUTHN_LEVEL
1749
The security context is invalid.
RPC_S_INVALID_
AUTH_IDENTITY
1750
The authorization service is unknown.
RPC_S_
UNKNOWN_
AUTHZ_SERVICE
1751
The entry is invalid.
EPT_S_INVALID_
ENTRY
86
Chapter 4 External Error Codes
1752
The server endpoint cannot perform the operation.
EPT_S_CANT_
PERFORM_OP
1753
There are no more endpoints available from the endpoint mapper.
EPT_S_NOT_
REGISTERED
1754
No interfaces have been exported.
RPC_S_NOTHING_
TO_EXPORT
1755
The entry name is incomplete.
RPC_S_
INCOMPLETE_
NAME
1756
The version option is invalid.
RPC_S_INVALID_
VERS_OPTION
1757
There are no more members.
RPC_S_NO_MORE_
MEMBERS
1758
There is nothing to unexport.
RPC_S_NOT_ALL_
OBJS_
UNEXPORTED
1759
The interface was not found.
RPC_S_
INTERFACE_NOT_
FOUND
1760
The entry already exists.
RPC_S_ENTRY_
ALREADY_EXISTS
1761
The entry is not found.
RPC_S_ENTRY_
NOT_FOUND
1762
The name service is unavailable.
RPC_S_NAME_
SERVICE_
UNAVAILABLE
1763
The network address family is invalid.
RPC_S_INVALID_
NAF_ID
1764
The requested operation is not supported.
RPC_S_CANNOT_
SUPPORT
1765
No security context is available to allow impersonation.
RPC_S_NO_
CONTEXT_
AVAILABLE
1766
An internal error occurred in a remote procedure call (RPC).
RPC_S_INTERNAL_
ERROR
1767
The RPC server attempted an integer division by zero.
RPC_S_ZERO_
DIVIDE
1768
An addressing error occurred in the RPC server.
RPC_S_ADDRESS_
ERROR
1769
A floating-point operation at the RPC server caused a division by zero.
RPC_S_FP_DIV_
ZERO
1770
A floating-point underflow occurred at the RPC server.
RPC_S_FP_
UNDERFLOW
1771
A floating-point overflow occurred at the RPC server.
RPC_S_FP_
OVERFLOW
Automation Engine
87
1772
The list of RPC servers available for the binding of auto handles has been RPC_X_NO_MORE_
exhausted.
ENTRIES
1773
Unable to open the character translation table file.
RPC_X_SS_CHAR_
TRANS_OPEN_FAIL
1774
The file containing the character translation table has fewer than 512
bytes.
RPC_X_SS_CHAR_
TRANS_SHORT_
FILE
1775
A null context handle was passed from the client to the host during a
remote procedure call.
RPC_X_SS_IN_
NULL_CONTEXT
1777
The context handle changed during a remote procedure call.
RPC_X_SS_
CONTEXT_
DAMAGED
1778
The binding handles passed to a remote procedure call do not match.
RPC_X_SS_
HANDLES_
MISMATCH
1779
The stub is unable to get the remote procedure call handle.
RPC_X_SS_
CANNOT_GET_
CALL_HANDLE
1780
A null reference pointer was passed to the stub.
RPC_X_NULL_REF_
POINTER
1781
The enumeration value is out of range.
RPC_X_ENUM_
VALUE_OUT_OF_
RANGE
1782
The byte count is too small.
RPC_X_BYTE_
COUNT_TOO_
SMALL
1783
The stub received bad data.
RPC_X_BAD_
STUB_DATA
1784
The supplied user buffer is not valid for the requested operation.
ERROR_INVALID_
USER_BUFFER
1785
The disk media is not recognized. It cannot be formatted.
ERROR_
UNRECOGNIZED_
MEDIA
1786
The workstation does not have a trust secret.
ERROR_NO_
TRUST_LSA_
SECRET
1787
The SAM database on the Windows NT Server does not have a computer ERROR_NO_
account for this workstation trust relationship.
TRUST_SAM_
ACCOUNT
1788
The trust relationship between the primary domain and the trusted domain ERROR_TRUSTED_
failed.
DOMAIN_FAILURE
1789
The trust relationship between this workstation and the primary domain
failed.
ERROR_TRUSTED_
RELATIONSHIP_
FAILURE
1790
The network logon failed.
ERROR_TRUST_
FAILURE
88
Chapter 4 External Error Codes
1791
A remote procedure call is already in progress for this thread.
RPC_S_CALL_IN_
PROGRESS
1792
An attempt was made to logon, but the network logon service was not
started.
ERROR_
NETLOGON_NOT_
STARTED
1793
The user's account has expired.
ERROR_
ACCOUNT_
EXPIRED
1794
The redirector is in use and cannot be unloaded.
ERROR_
REDIRECTOR_
HAS_OPEN_
HANDLES
1795
The specified printer driver is already installed.
ERROR_PRINTER_
DRIVER_
ALREADY_
INSTALLED
1796
The specified port is unknown.
ERROR_
UNKNOWN_PORT
1797
The printer driver is unknown.
ERROR_
UNKNOWN_
PRINTER_DRIVER
1798
The print processor is unknown.
ERROR_
UNKNOWN_
PRINTPROCESSOR
1799
The specified separator file is invalid.
ERROR_INVALID_
SEPARATOR_FILE
1800
The specified priority is invalid.
ERROR_INVALID_
PRIORITY
1801
The printer name is invalid.
ERROR_INVALID_
PRINTER_NAME
1802
The printer already exists.
ERROR_PRINTER_
ALREADY_EXISTS
1803
The printer command is invalid.
ERROR_INVALID_
PRINTER_
COMMAND
1804
The specified datatype is invalid.
ERROR_INVALID_
DATATYPE
1805
The environment specified is invalid.
ERROR_INVALID_
ENVIRONMENT
1806
There are no more bindings.
RPC_S_NO_MORE_
BINDINGS
1807
The account used is an interdomain trust account. Use your global user
account or local user account to access this server.
ERROR_
NOLOGON_
INTERDOMAIN_
TRUST_ACCOUNT
Automation Engine
89
1808
The account used is a computer account. Use your global user account or ERROR_
local user account to access this server.
NOLOGON_
WORKSTATION_
TRUST_ACCOUNT
1809
The account used is a server trust account. Use your global user account ERROR_
or local user account to access this server.
NOLOGON_
SERVER_TRUST_
ACCOUNT
1810
The name or security ID (SID) of the domain specified is inconsistent with ERROR_DOMAIN_
the trust information for that domain.
TRUST_
INCONSISTENT
1811
The server is in use and cannot be unloaded.
ERROR_SERVER_
HAS_OPEN_
HANDLES
1812
The specified image file did not contain a resource section.
ERROR_
RESOURCE_DATA_
NOT_FOUND
1813
The specified resource type cannot be found in the image file.
ERROR_
RESOURCE_TYPE_
NOT_FOUND
1814
The specified resource name cannot be found in the image file.
ERROR_
RESOURCE_
NAME_NOT_
FOUND
1815
The specified resource language ID cannot be found in the image file.
ERROR_
RESOURCE_LANG_
NOT_FOUND
1816
Not enough quota is available to process this command.
ERROR_NOT_
ENOUGH_QUOTA
1817
No interfaces have been registered.
RPC_S_NO_
INTERFACES
1818
The remote procedure call was canceled.
RPC_S_CALL_
CANCELED
1819
The binding handle does not contain all required information.
RPC_S_BINDING_
INCOMPLETE
1820
A communications failure occurred during a remote procedure call.
RPC_S_COMM_
FAILURE
1821
The requested authentication level is not supported.
RPC_S_
UNSUPPORTED_
AUTHN_LEVEL
1822
No principal name registered.
RPC_S_NO_
PRINC_NAME
1823
The error specified is not a valid Windows RPC error code.
RPC_S_NOT_RPC_
ERROR
1824
A UUID that is valid only on this computer has been allocated.
RPC_S_UUID_
LOCAL_ONLY
90
Chapter 4 External Error Codes
1825
A security package specific error occurred.
RPC_S_SEC_PKG_
ERROR
1826
Thread is not canceled.
RPC_S_NOT_
CANCELED
1827
Invalid operation on the encoding/decoding handle.
RPC_X_INVALID_
ES_ACTION
1828
Incompatible version of the serializing package.
RPC_X_WRONG_
ES_VERSION
1829
Incompatible version of the RPC stub.
RPC_X_WRONG_
STUB_VERSION
1830
The RPC pipe object is invalid or corrupted.
RPC_X_INVALID_
PIPE_OBJECT
1831
An invalid operation was attempted on an RPC pipe object.
RPC_X_WRONG_
PIPE_ORDER
1832
Unsupported RPC pipe version.
RPC_X_WRONG_
PIPE_VERSION
1898
The group member was not found.
RPC_S_GROUP_
MEMBER_NOT_
FOUND
1899
The endpoint mapper database entry could not be created.
EPT_S_CANT_
CREATE
1900
The object universal unique identifier (UUID) is the nil UUID.
RPC_S_INVALID_
OBJECT
1901
The specified time is invalid.
ERROR_INVALID_
TIME
1902
The specified form name is invalid.
ERROR_INVALID_
FORM_NAME
1903
The specified form size is invalid.
ERROR_INVALID_
FORM_SIZE
1904
The specified printer handle is already being waited on
ERROR_ALREADY_
WAITING
1905
The specified printer has been deleted.
ERROR_PRINTER_
DELETED
1906
The state of the printer is invalid.
ERROR_INVALID_
PRINTER_STATE
1907
The user must change his password before he logs on the first time.
ERROR_
PASSWORD_
MUST_CHANGE
1908
Could not find the domain controller for this domain.
ERROR_DOMAIN_
CONTROLLER_
NOT_FOUND
1909
The referenced account is currently locked out and cannot be logged on
to.
ERROR_
ACCOUNT_
LOCKED_OUT
1910
The object exporter specified was not found.
OR_INVALID_OXID
1911
The object specified was not found.
OR_INVALID_OID
Automation Engine
91
1912
The object resolver set specified was not found.
OR_INVALID_SET
1913
Some data remains to be sent in the request buffer.
RPC_S_SEND_
INCOMPLETE
1914
Invalid asynchronous remote procedure call handle.
RPC_S_INVALID_
ASYNC_HANDLE
1915
Invalid asynchronous RPC call handle for this operation.
RPC_S_INVALID_
ASYNC_CALL
1916
The RPC pipe object has already been closed.
RPC_X_PIPE_
CLOSED
1917
The RPC call completed before all pipes were processed.
RPC_X_PIPE_
DISCIPLINE_
ERROR
1918
No more data is available from the RPC pipe.
RPC_X_PIPE_
EMPTY
1919
No site name is available for this machine.
ERROR_NO_
SITENAME
1920
The file cannot be accessed by the system.
ERROR_CANT_
ACCESS_FILE
1921
The name of the file cannot be resolved by the system.
ERROR_CANT_
RESOLVE_
FILENAME
1922
The entry is not of the expected type.
RPC_S_ENTRY_
TYPE_MISMATCH
1923
Not all object UUIDs could be exported to the specified entry.
RPC_S_NOT_ALL_
OBJS_EXPORTED
1924
Interface could not be exported to the specified entry.
RPC_S_
INTERFACE_NOT_
EXPORTED
1925
The specified profile entry could not be added.
RPC_S_PROFILE_
NOT_ADDED
1926
The specified profile element could not be added.
RPC_S_PRF_ELT_
NOT_ADDED
1927
The specified profile element could not be removed.
RPC_S_PRF_ELT_
NOT_REMOVED
1928
The group element could not be added.
RPC_S_GRP_ELT_
NOT_ADDED
1929
The group element could not be removed. RPC_S_GRP_ELT_
NOT_REMOVED 4.5.3 Win32 - Error Codes (2000 - 5999)
The following table provides a list of Win32 error codes.
Code
Description
Name
92
Chapter 4 External Error Codes
2000
The pixel format is
invalid.
ERROR_INVALID_PIXEL_FORMAT
2001
The specified
driver is invalid.
ERROR_BAD_DRIVER
2002
The window style ERROR_INVALID_WINDOW_STYLE
or class attribute is
invalid for this
operation.
2003
The requested
metafile operation
is not supported.
ERROR_METAFILE_NOT_SUPPORTED
2004
The requested
transformation
operation is not
supported.
ERROR_TRANSFORM_NOT_SUPPORTED
2005
The requested
clipping operation
is not supported.
ERROR_CLIPPING_NOT_SUPPORTED
2010
The specified color ERROR_INVALID_CMM
management
module is invalid.
2011
The specified color ERROR_INVALID_PROFILE
profile is invalid.
2012
The specified tag
was not found.
ERROR_TAG_NOT_FOUND
2013
A required tag is
not present.
ERROR_TAG_NOT_PRESENT
2014
The specified tag is ERROR_DUPLICATE_TAG
already present.
2015
The specified color ERROR_PROFILE_NOT_ASSOCIATED_WITH_
profile is not
DEVICE
associated with
any device.
2016
The specified color ERROR_PROFILE_NOT_FOUND
profile was not
found.
2017
The specified color ERROR_INVALID_COLORSPACE
space is invalid.
2018
Image Color
ERROR_ICM_NOT_ENABLED
Management is not
enabled.
2019
There was an error ERROR_DELETING_ICM_XFORM
while deleting the
color transform.
2020
The specified color ERROR_INVALID_TRANSFORM
transform is
invalid.
Automation Engine
2021
The specified
ERROR_COLORSPACE_MISMATCH
transform does not
match the bitmap's
color space.
2022
The specified
ERROR_INVALID_COLORINDEX
named color index
is not present in the
profile.
2108
The network
ERROR_CONNECTED_OTHER_PASSWORD
connection was
made
successfully, but
the user had to be
prompted for a
password other
than the one
originally specified.
2202
The specified
username is
invalid.
ERROR_BAD_USERNAME
2250
This network
connection does
not exist.
ERROR_NOT_CONNECTED
2401
This network
connection has
files open or
requests pending.
ERROR_OPEN_FILES
2402
Active connections ERROR_ACTIVE_CONNECTIONS
still exist.
2404
The device is in
use by an active
process and
cannot be
disconnected.
ERROR_DEVICE_IN_USE
3000
The specified print
monitor is
unknown.
ERROR_UNKNOWN_PRINT_MONITOR
3001
The specified
printer driver is
currently in use.
ERROR_PRINTER_DRIVER_IN_USE
3002
The spool file was
not found.
ERROR_SPOOL_FILE_NOT_FOUND
3003
A StartDocPrinter
call was not
issued.
ERROR_SPL_NO_STARTDOC
3004
An AddJob call
was not issued.
ERROR_SPL_NO_ADDJOB
93
94
Chapter 4 External Error Codes
3005
The specified print
processor has
already been
installed.
ERROR_PRINT_PROCESSOR_ALREADY_INSTALLED
3006
The specified print
monitor has
already been
installed.
ERROR_PRINT_MONITOR_ALREADY_INSTALLED
3007
The specified print
monitor does not
have the required
functions.
ERROR_INVALID_PRINT_MONITOR
3008
The specified print ERROR_PRINT_MONITOR_IN_USE
monitor is currently
in use.
3009
The requested
ERROR_PRINTER_HAS_JOBS_QUEUED
operation is not
allowed when there
are jobs queued to
the printer.
3010
The requested
operation is
successful.
Changes will not
be effective until
the system
reboots.
ERROR_SUCCESS_REBOOT_REQUIRED
3011
The requested
operation is
successful.
Changes will not
be effective until
the service is
restarted.
ERROR_SUCCESS_RESTART_REQUIRED
3012
No printers were
found.
ERROR_PRINTER_NOT_FOUND
4000
WINS encountered ERROR_WINS_INTERNAL
an error while
processing the
command.
4001
The local WINS
cannot be deleted.
ERROR_CAN_NOT_DEL_LOCAL_WINS
4002
The importation
from the file failed.
ERROR_STATIC_INIT
4003
The backup failed.
Was a full backup
done before?
ERROR_INC_BACKUP
Automation Engine
4004
The backup failed. ERROR_FULL_BACKUP
Check the
directory to which
you are backing the
database.
4005
The name does not ERROR_REC_NON_EXISTENT
exist in the WINS
database.
4006
Replication with a
nonconfigured
partner is not
allowed.
4100
The DHCP client
ERROR_DHCP_ADDRESS_CONFLICT
has obtained an IP
address that is
already in use on
the network. The
local interface will
be disabled until
the DHCP client
can obtain a new
address.
4200
The GUID passed ERROR_WMI_GUID_NOT_FOUND
was not recognized
as valid by a WMI
data provider.
4201
The instance name ERROR_WMI_INSTANCE_NOT_FOUND
passed was not
recognized as valid
by a WMI data
provider.
4202
The data item ID
ERROR_WMI_ITEMID_NOT_FOUND
passed was not
recognized as valid
by a WMI data
provider.
4203
The WMI request
could not be
completed and
should be retried.
ERROR_WMI_TRY_AGAIN
4204
The WMI data
provider could not
be located.
ERROR_WMI_DP_NOT_FOUND
4205
The WMI data
ERROR_WMI_UNRESOLVED_INSTANCE_REF
provider references
an instance set
that has not been
registered.
ERROR_RPL_NOT_ALLOWED
95
96
Chapter 4 External Error Codes
4206
The WMI data
block or event
notification has
already been
enabled.
ERROR_WMI_ALREADY_ENABLED
4207
The WMI data
block is no longer
available.
ERROR_WMI_GUID_DISCONNECTED
4208
The WMI data
service is not
available.
ERROR_WMI_SERVER_UNAVAILABLE
4209
The WMI data
provider failed to
carry out the
request.
ERROR_WMI_DP_FAILED
4210
The WMI MOF
information is not
valid.
ERROR_WMI_INVALID_MOF
4211
The WMI
registration
information is not
valid.
ERROR_WMI_INVALID_REGINFO
4212
The WMI data
block or event
notification has
already been
disabled.
ERROR_WMI_ALREADY_DISABLED
4213
The WMI data item ERROR_WMI_READ_ONLY
or data block is
read only.
4214
The WMI data item ERROR_WMI_SET_FAILURE
or data block could
not be changed.
4300
The media
identifier does not
represent a valid
medium.
ERROR_INVALID_MEDIA
4301
The library
identifier does not
represent a valid
library.
ERROR_INVALID_LIBRARY
4302
The media pool
identifier does not
represent a valid
media pool.
ERROR_INVALID_MEDIA_POOL
Automation Engine
4303
The drive and
ERROR_DRIVE_MEDIA_MISMATCH
medium are not
compatible or exist
in different
libraries.
4304
The medium
ERROR_MEDIA_OFFLINE
currently exists in
an offline library
and must be online
to perform this
operation.
4305
The operation
cannot be
performed on an
offline library.
ERROR_LIBRARY_OFFLINE
4306
The library, drive,
or media pool is
empty.
ERROR_EMPTY
4307
The library, drive,
ERROR_NOT_EMPTY
or media pool must
be empty to
perform this
operation.
4308
No media is
currently available
in this media pool
or library.
4309
A resource required ERROR_RESOURCE_DISABLED
for this operation is
disabled.
4310
The media
identifier does not
represent a valid
cleaner.
4311
The drive cannot
ERROR_UNABLE_TO_CLEAN
be cleaned or does
not support
cleaning.
4312
The object
identifier does not
represent a valid
object.
4313
Unable to read
ERROR_DATABASE_FAILURE
from or write to the
database.
4314
The database is
full.
ERROR_MEDIA_UNAVAILABLE
ERROR_INVALID_CLEANER
ERROR_OBJECT_NOT_FOUND
ERROR_DATABASE_FULL
97
98
Chapter 4 External Error Codes
4315
The medium is not ERROR_MEDIA_INCOMPATIBLE
compatible with the
device or media
pool.
4316
The resource
required for this
operation does not
exist.
ERROR_RESOURCE_NOT_PRESENT
4317
The operation
identifier is not
valid.
ERROR_INVALID_OPERATION
4318
The media is not
mounted or ready
for use.
ERROR_MEDIA_NOT_AVAILABLE
4319
The device is not
ready for use.
ERROR_DEVICE_NOT_AVAILABLE
4320
The operator or
administrator has
refused the
request.
ERROR_REQUEST_REFUSED
4321
The drive identifier ERROR_INVALID_DRIVE_OBJECT
does not represent
a valid drive.
4322
Library is full. No
ERROR_LIBRARY_FULL
slot is available for
use.
4323
The transport
cannot access the
medium.
ERROR_MEDIUM_NOT_ACCESSIBLE
4324
Unable to load the
medium into the
drive.
ERROR_UNABLE_TO_LOAD_MEDIUM
4325
Unable to retrieve
status about the
drive.
ERROR_UNABLE_TO_INVENTORY_DRIVE
4326
Unable to retrieve
status about the
slot.
ERROR_UNABLE_TO_INVENTORY_SLOT
4327
Unable to retrieve
status about the
transport.
ERROR_UNABLE_TO_INVENTORY_TRANSPORT
4328
Cannot use the
ERROR_TRANSPORT_FULL
transport because
it is already in use.
4329
Unable to open or
close the
inject/eject port.
ERROR_CONTROLLING_IEPORT
Automation Engine
4330
Unable to eject the ERROR_UNABLE_TO_EJECT_MOUNTED_MEDIA
media because it is
in a drive.
4331
A cleaner slot is
already reserved.
ERROR_CLEANER_SLOT_SET
4332
A cleaner slot is
not reserved.
ERROR_CLEANER_SLOT_NOT_SET
4333
The cleaner
cartridge has
performed the
maximum number
of drive cleanings.
ERROR_CLEANER_CARTRIDGE_SPENT
4334
Unexpected onmedium identifier.
ERROR_UNEXPECTED_OMID
4335
The last remaining ERROR_CANT_DELETE_LAST_ITEM
item in this group or
resource cannot be
deleted.
4336
The message
provided exceeds
the maximum size
allowed for this
parameter.
4337
The volume
ERROR_VOLUME_CONTAINS_SYS_FILES
contains system or
paging files.
4338
The media type
ERROR_INDIGENOUS_TYPE
cannot be removed
from this library
since at least one
drive in the library
reports it can
support this media
type.
4339
This offline media ERROR_NO_SUPPORTING_DRIVES
cannot be mounted
on this system
since no enabled
drives are present
which can be used.
4350
The remote storage ERROR_FILE_OFFLINE
service was not
able to recall the
file.
4351
The remote storage ERROR_REMOTE_STORAGE_NOT_ACTIVE
service is not
operational at this
time.
ERROR_MESSAGE_EXCEEDS_MAX_SIZE
99
100
Chapter 4 External Error Codes
4352
The remote storage ERROR_REMOTE_STORAGE_MEDIA_ERROR
service
encountered a
media error.
4390
The file or directory ERROR_NOT_A_REPARSE_POINT
is not a reparse
point.
4391
The reparse point
ERROR_REPARSE_ATTRIBUTE_CONFLICT
attribute cannot be
set because it
conflicts with an
existing attribute.
4392
The data present in ERROR_INVALID_REPARSE_DATA
the reparse point
buffer is invalid.
4393
The tag present in
the reparse point
buffer is invalid.
4394
There is a
ERROR_REPARSE_TAG_MISMATCH
mismatch between
the tag specified in
the request and the
tag present in the
reparse point.
5001
The cluster
ERROR_DEPENDENT_RESOURCE_EXISTS
resource cannot be
moved to another
group because
other resources are
dependent on it.
5002
The cluster
resource
dependency
cannot be found.
5003
The cluster
ERROR_DEPENDENCY_ALREADY_EXISTS
resource cannot be
made dependent
on the specified
resource because
it is already
dependent.
5004
The cluster
resource is not
online.
ERROR_RESOURCE_NOT_ONLINE
5005
A cluster node is
not available for
this operation.
ERROR_HOST_NODE_NOT_AVAILABLE
ERROR_REPARSE_TAG_INVALID
ERROR_DEPENDENCY_NOT_FOUND
Automation Engine
5006
The cluster
resource is not
available.
ERROR_RESOURCE_NOT_AVAILABLE
5007
The cluster
resource could not
be found.
ERROR_RESOURCE_NOT_FOUND
5008
The cluster is being ERROR_SHUTDOWN_CLUSTER
shut down.
5009
A cluster node
cannot be evicted
from the cluster
while it is online.
ERROR_CANT_EVICT_ACTIVE_NODE
5010
The object already
exists.
ERROR_OBJECT_ALREADY_EXISTS
5011
The object is
already in the list.
ERROR_OBJECT_IN_LIST
5012
The cluster group
is not available for
any new requests.
ERROR_GROUP_NOT_AVAILABLE
5013
The cluster group ERROR_GROUP_NOT_FOUND
could not be found.
5014
The operation
ERROR_GROUP_NOT_ONLINE
could not be
completed
because the
cluster group is not
online.
5015
The cluster node is ERROR_HOST_NODE_NOT_RESOURCE_OWNER
not the owner of
the resource.
5016
The cluster node is ERROR_HOST_NODE_NOT_GROUP_OWNER
not the owner of
the group.
5017
The cluster
resource could not
be created in the
specified resource
monitor.
ERROR_RESMON_CREATE_FAILED
5018
The cluster
resource could not
be brought online
by the resource
monitor.
ERROR_RESMON_ONLINE_FAILED
101
102
Chapter 4 External Error Codes
5019
The operation
could not be
completed
because the
cluster resource is
online.
ERROR_RESOURCE_ONLINE
5020
The cluster
resource could not
be deleted or
brought offline
because it is the
quorum resource.
ERROR_QUORUM_RESOURCE
5021
The cluster could
ERROR_NOT_QUORUM_CAPABLE
not make the
specified resource
a quorum resource
because it is not
capable of being a
quorum resource.
5022
The cluster
software is
shutting down.
5023
The group or
ERROR_INVALID_STATE
resource is not in
the correct state to
perform the
requested
operation.
5024
The properties
ERROR_RESOURCE_PROPERTIES_STORED
were stored but not
all changes will
take effect until the
next time the
resource is brought
online.
5025
The cluster could
ERROR_NOT_QUORUM_CLASS
not make the
specified resource
a quorum resource
because it does not
belong to a shared
storage class.
5026
The cluster
resource could not
be deleted since it
is a core resource.
ERROR_CORE_RESOURCE
5027
The quorum
resource failed to
come online.
ERROR_QUORUM_RESOURCE_ONLINE_FAILED
ERROR_CLUSTER_SHUTTING_DOWN
Automation Engine
5028
The quorum log
ERROR_QUORUMLOG_OPEN_FAILED
could not be
created or mounted
successfully.
5029
The cluster log is
corrupt.
5030
The record could
ERROR_CLUSTERLOG_RECORD_EXCEEDS_
not be written to
MAXSIZE
the cluster log
since it exceeds
the maximum size.
5031
The cluster log
exceeds its
maximum size.
5032
No checkpoint
ERROR_CLUSTERLOG_CHKPOINT_NOT_FOUND
record was found in
the cluster log.
5033
The minimum
ERROR_CLUSTERLOG_NOT_ENOUGH_SPACE
required disk space
needed for logging
is not available.
5035
A cluster network
is not available for
this operation.
ERROR_NETWORK_NOT_AVAILABLE
5036
A cluster node is
not available for
this operation.
ERROR_NODE_NOT_AVAILABLE
5037
All cluster nodes
must be running to
perform this
operation.
ERROR_ALL_NODES_NOT_AVAILABLE
5038
A cluster resource
failed.
ERROR_RESOURCE_FAILED
5039
The cluster node is ERROR_CLUSTER_INVALID_NODE
not valid.
5040
The cluster node
already exists.
ERROR_CLUSTER_NODE_EXISTS
5041
A node is in the
process of joining
the cluster.
ERROR_CLUSTER_JOIN_IN_PROGRESS
5042
The cluster node
was not found.
ERROR_CLUSTER_NODE_NOT_FOUND
5043
The cluster local
node information
was not found.
ERROR_CLUSTER_LOCAL_NODE_NOT_FOUND
ERROR_CLUSTERLOG_CORRUPT
ERROR_CLUSTERLOG_EXCEEDS_MAXSIZE
103
104
Chapter 4 External Error Codes
5044
The cluster
network already
exists.
ERROR_CLUSTER_NETWORK_EXISTS
5045
The cluster
network was not
found.
ERROR_CLUSTER_NETWORK_NOT_FOUND
5046
The cluster
network interface
already exists.
ERROR_CLUSTER_NETINTERFACE_EXISTS
5047
The cluster
network interface
was not found.
ERROR_CLUSTER_NETINTERFACE_NOT_FOUND
5048
The cluster request ERROR_CLUSTER_INVALID_REQUEST
is not valid for this
object.
5049
The cluster
ERROR_CLUSTER_INVALID_NETWORK_PROVIDER
network provider is
not valid.
5050
The cluster node is ERROR_CLUSTER_NODE_DOWN
down.
5051
The cluster node is ERROR_CLUSTER_NODE_UNREACHABLE
not reachable.
5052
The cluster node is ERROR_CLUSTER_NODE_NOT_MEMBER
not a member of
the cluster.
5053
A cluster join
operation is not in
progress.
ERROR_CLUSTER_JOIN_NOT_IN_PROGRESS
5054
The cluster
network is not
valid.
ERROR_CLUSTER_INVALID_NETWORK
5056
The cluster node is ERROR_CLUSTER_NODE_UP
up.
5057
The cluster IP
address is already
in use.
5058
The cluster node is ERROR_CLUSTER_NODE_NOT_PAUSED
not paused.
5059
No cluster security ERROR_CLUSTER_NO_SECURITY_CONTEXT
context is
available.
5060
The cluster
network is not
configured for
internal cluster
communication.
ERROR_CLUSTER_IPADDR_IN_USE
ERROR_CLUSTER_NETWORK_NOT_INTERNAL
Automation Engine
105
5061
The cluster node is ERROR_CLUSTER_NODE_ALREADY_UP
already up.
5062
The cluster node is ERROR_CLUSTER_NODE_ALREADY_DOWN
already down.
5063
The cluster
network is already
online.
ERROR_CLUSTER_NETWORK_ALREADY_ONLINE
5064
The cluster
network is already
offline.
ERROR_CLUSTER_NETWORK_ALREADY_OFFLINE
5065
The cluster node is ERROR_CLUSTER_NODE_ALREADY_MEMBER
already a member
of the cluster.
5066
The cluster
ERROR_CLUSTER_LAST_INTERNAL_NETWORK
network is the only
one configured for
internal cluster
communication
between two or
more active cluster
nodes. The
internal
communication
capability cannot
be removed from
the network.
5067
One or more
cluster resources
depend on the
network to provide
service to clients.
The client access
capability cannot
be removed from
the network.
5068
This operation
ERROR_INVALID_OPERATION_ON_QUORUM
cannot be
performed on the
cluster resource as
it the quorum
resource. You
cannot bring the
quorum resource
offline or modify its
possible owners
list.
5069
The cluster quorum ERROR_DEPENDENCY_NOT_ALLOWED
resource is not
allowed to have
any dependencies.
ERROR_CLUSTER_NETWORK_HAS_DEPENDENTS
106
Chapter 4 External Error Codes
5070
The cluster node is ERROR_CLUSTER_NODE_PAUSED
paused.
5071
The cluster
ERROR_NODE_CANT_HOST_RESOURCE
resource cannot be
brought online. The
owner node cannot
run this resource.
5072
The cluster node is ERROR_CLUSTER_NODE_NOT_READY
not ready to
perform the
requested
operation.
5073
The cluster node is ERROR_CLUSTER_NODE_SHUTTING_DOWN
shutting down.
5074
The cluster join
operation was
aborted.
5075
The cluster join
ERROR_CLUSTER_INCOMPATIBLE_VERSIONS
operation failed due
to incompatible
software versions
between the joining
node and its
sponsor.
5076
This resource
ERROR_CLUSTER_MAXNUM_OF_RESOURCES_
cannot be created EXCEEDED
because the
cluster has
reached the limit on
the number of
resources it can
monitor.
5077
The system
ERROR_CLUSTER_SYSTEM_CONFIG_CHANGED
configuration
changed during the
cluster join or form
operation. The join
or form operation
was aborted.
5078
The specified
resource type was
not found.
ERROR_CLUSTER_JOIN_ABORTED
ERROR_CLUSTER_RESOURCE_TYPE_NOT_FOUND
Automation Engine
5079
The specified node ERROR_CLUSTER_RESTYPE_NOT_SUPPORTED
does not support a
resource of this
type. This can be
due to version
inconsistencies or
due to the absence
of the resource
DLL on this node.
5080
The specified
ERROR_CLUSTER_RESNAME_NOT_FOUND
resource name is
supported by this
resource DLL. This
can be due to a bad
(or changed) name
supplied to the
resource DLL.
5081
No authentication
package could be
registered with the
RPC server.
5082
You cannot bring
ERROR_CLUSTER_OWNER_NOT_IN_PREFLIST
the group online
because the owner
of the group is not
in the preferred list
for the group. To
change the owner
node for the group,
move the group.
5083
The join operation
failed because the
cluster database
sequence number
has changed or is
incompatible with
the locker node.
This can happen
during a join
operation if the
cluster database
was changing
during the join.
ERROR_CLUSTER_NO_RPC_PACKAGES_
REGISTERED
ERROR_CLUSTER_DATABASE_SEQMISMATCH
107
108
Chapter 4 External Error Codes
5084
The resource
ERROR_RESMON_INVALID_STATE
monitor will not
allow the fail
operation to be
performed while
the resource is in
its current state.
This can happen if
the resource is in a
pending state.
´
4.5.4 Win32 - Error Codes (6000 - 11999)
The following table provides a list of Win32 error codes.
Code
Description
Name
6000
The specified file could not be encrypted.
ERROR_ENCRYPTION_
FAILED
6001
The specified file could not be decrypted.
ERROR_DECRYPTION_
FAILED
6002
The specified file is encrypted and the user does not have the ERROR_FILE_ENCRYPTED
ability to decrypt it.
6003
There is no encryption recovery policy configured for this
system.
ERROR_NO_RECOVERY_
POLICY
6004
The required encryption driver is not loaded for this system.
ERROR_NO_EFS
6005
The file was encrypted with a different encryption driver than
is currently loaded.
ERROR_WRONG_EFS
6006
There are no EFS keys defined for the user.
ERROR_NO_USER_KEYS
6007
The specified file is not encrypted.
ERROR_FILE_NOT_
ENCRYPTED
6008
The specified file is not in the defined EFS export format.
ERROR_NOT_EXPORT_
FORMAT
6009
The specified file is read only.
ERROR_FILE_READ_ONLY
6118
The list of servers for this workgroup is not currently available ERROR_NO_BROWSER_
SERVERS_FOUND
7001
The specified session name is invalid.
ERROR_CTX_WINSTATION_
NAME_INVALID
7002
The specified protocol driver is invalid.
ERROR_CTX_INVALID_PD
7003
The specified protocol driver was not found in the system
path.
ERROR_CTX_PD_NOT_
FOUND
7004
The specified terminal connection driver was not found in the
system path.
ERROR_CTX_WD_NOT_
FOUND
7005
A registry key for event logging could not be created for this
session.
ERROR_CTX_CANNOT_
MAKE_EVENTLOG_ENTRY
Automation Engine
109
7006
A service with the same name already exists on the system.
ERROR_CTX_SERVICE_
NAME_COLLISION
7007
A close operation is pending on the session.
ERROR_CTX_CLOSE_
PENDING
7008
There are no free output buffers available.
ERROR_CTX_NO_OUTBUF
7009
The MODEM.INF file was not found.
ERROR_CTX_MODEM_INF_
NOT_FOUND
7010
The modem name was not found in MODEM.INF.
ERROR_CTX_INVALID_
MODEMNAME
7011
The modem did not accept the command sent to it. Verify
that the configured modem name matches the attached
modem.
ERROR_CTX_MODEM_
RESPONSE_ERROR
7012
The modem did not respond to the command sent to it. Verify
that the modem is properly cabled and powered on.
ERROR_CTX_MODEM_
RESPONSE_TIMEOUT
7013
Carrier detect has failed or carrier has been dropped due to
disconnect.
ERROR_CTX_MODEM_
RESPONSE_NO_CARRIER
7014
Dial tone not detected within the required time. Verify that the ERROR_CTX_MODEM_
phone cable is properly attached and functional.
RESPONSE_NO_DIALTONE
7015
Busy signal detected at remote site on callback.
ERROR_CTX_MODEM_
RESPONSE_BUSY
7016
Voice detected at remote site on callback.
ERROR_CTX_MODEM_
RESPONSE_VOICE
7017
Transport driver error
ERROR_CTX_TD_ERROR
7022
The specified session cannot be found.
ERROR_CTX_WINSTATION_
NOT_FOUND
7023
The specified session name is already in use.
ERROR_CTX_WINSTATION_
ALREADY_EXISTS
7024
The requested operation cannot be completed because the
terminal connection is currently busy processing a connect,
disconnect, reset, or delete operation.
ERROR_CTX_WINSTATION_
BUSY
7025
An attempt has been made to connect to a session whose
video mode is not supported by the current client.
ERROR_CTX_BAD_VIDEO_
MODE
7035
The application attempted to enable DOS graphics mode.
DOS graphics mode is not supported.
ERROR_CTX_GRAPHICS_
INVALID
7037
Your interactive logon privilege has been disabled. Please
contact your administrator.
ERROR_CTX_LOGON_
DISABLED
7038
The requested operation can be performed only on the
system console. This is most often the result of a driver or
system DLL requiring direct console access.
ERROR_CTX_NOT_
CONSOLE
7040
The client failed to respond to the server connect message.
ERROR_CTX_CLIENT_
QUERY_TIMEOUT
7041
Disconnecting the console session is not supported.
ERROR_CTX_CONSOLE_
DISCONNECT
7042
Reconnecting a disconnected session to the console is not
supported.
ERROR_CTX_CONSOLE_
CONNECT
110
Chapter 4 External Error Codes
7044
The request to shadow another session was denied.
ERROR_CTX_SHADOW_
DENIED
7045
The requested session access is denied.
ERROR_CTX_WINSTATION_
ACCESS_DENIED
7049
The specified terminal connection driver is invalid.
ERROR_CTX_INVALID_WD
7050
The requested session cannot be shadowed. This can be
because the session is disconnected or does not currently
have a user logged on. Also, you cannot shadow a session
from the system console or shadow the system console.
ERROR_CTX_SHADOW_
INVALID
7051
The requested session is not configured to allow shadowing.
ERROR_CTX_SHADOW_
DISABLED
7052
Your request to connect to this Terminal Server has been
rejected. Your Terminal Server client license number is
currently being used by another user. Please call your
system administrator to obtain a new copy of the Terminal
Server client with a valid, unique license number.
ERROR_CTX_CLIENT_
LICENSE_IN_USE
7053
Your request to connect to this Terminal Server has been
rejected. Your Terminal Server client license number has not
been entered for this copy of the Terminal Server client.
Please call your system administrator for help in entering a
valid, unique license number for this Terminal Server client.
ERROR_CTX_CLIENT_
LICENSE_NOT_SET
7054
The system has reached its licensed logon limit. Please try
again later.
ERROR_CTX_LICENSE_
NOT_AVAILABLE
7055
The client you are using is not licensed to use this system.
Your logon request is denied.
ERROR_CTX_LICENSE_
CLIENT_INVALID
7056
The system license has expired. Your logon request is
denied.
ERROR_CTX_LICENSE_
EXPIRED
8001
The file replication service API was called incorrectly.
FRS_ERR_INVALID_API_
SEQUENCE
8002
The file replication service cannot be started.
FRS_ERR_STARTING_
SERVICE
8003
The file replication service cannot be stopped.
FRS_ERR_STOPPING_
SERVICE
8004
The file replication service API terminated the request.
FRS_ERR_INTERNAL_API
8005
The file replication service terminated the request.
FRS_ERR_INTERNAL
8006
The file replication service cannot be contacted.
FRS_ERR_SERVICE_COMM
8007
The file replication service cannot satisfy the request
because the user is not a member of the Administrators
group.
FRS_ERR_INSUFFICIENT_
PRIV
8008
The file replication service cannot satisfy the request
because authenticated RPC is not available.
FRS_ERR_
AUTHENTICATION
8009
The file replication service cannot satisfy the request
because the user is not a member of Administrators group on
the domain controller.
FRS_ERR_PARENT_
INSUFFICIENT_PRIV
Automation Engine
111
8010
The file replication service cannot satisfy the request
because authenticated RPC is not available on the domain
controller.
FRS_ERR_PARENT_
AUTHENTICATION
8011
The file replication service cannot communicate with the file
replication service on the domain controller.
FRS_ERR_CHILD_TO_
PARENT_COMM
8012
The file replication service on the domain controller cannot
communicate with the file replication service on this
computer.
FRS_ERR_PARENT_TO_
CHILD_COMM
8013
The file replication service cannot populate the system
volume because of an internal error.
FRS_ERR_SYSVOL_
POPULATE
8014
The file replication service cannot populate the system
volume because of an internal timeout.
FRS_ERR_SYSVOL_
POPULATE_TIMEOUT
8015
The file replication service cannot process the request. The
system volume is busy with a previous request.
FRS_ERR_SYSVOL_IS_
BUSY
8016
The file replication service cannot stop replicating the system FRS_ERR_SYSVOL_
volume because of an internal error.
DEMOTE
8017
The file replication service detected an invalid parameter.
FRS_ERR_INVALID_
SERVICE_PARAMETER
8200
An error occurred while installing the Windows NT directory
service. For more information, see the event log.
ERROR_DS_NOT_
INSTALLED
8201
The directory service evaluated group memberships locally.
ERROR_DS_MEMBERSHIP_
EVALUATED_LOCALLY
8202
The specified directory service attribute or value does not
exist.
ERROR_DS_NO_
ATTRIBUTE_OR_VALUE
8203
The attribute syntax specified to the directory service is
invalid.
ERROR_DS_INVALID_
ATTRIBUTE_SYNTAX
8204
The attribute type specified to the directory service is not
defined.
ERROR_DS_ATTRIBUTE_
TYPE_UNDEFINED
8205
The specified directory service attribute or value already
exists.
ERROR_DS_ATTRIBUTE_
OR_VALUE_EXISTS
8206
The directory service is busy.
ERROR_DS_BUSY
8207
The directory service is unavailable.
ERROR_DS_UNAVAILABLE
8208
The directory service was unable to allocate a relative
identifier.
ERROR_DS_NO_RIDS_
ALLOCATED
8209
The directory service has exhausted the pool of relative
identifiers.
ERROR_DS_NO_MORE_
RIDS
8210
The requested operation could not be performed because the
directory service is not the master for that type of operation.
ERROR_DS_INCORRECT_
ROLE_OWNER
8211
The directory service was unable to initialize the subsystem
that allocates relative identifiers.
ERROR_DS_RIDMGR_INIT_
ERROR
8212
The requested operation did not satisfy one or more
constraints associated with the class of the object.
ERROR_DS_OBJ_CLASS_
VIOLATION
8213
The directory service can perform the requested operation
only on a leaf object.
ERROR_DS_CANT_ON_
NON_LEAF
112
Chapter 4 External Error Codes
8214
The directory service cannot perform the requested operation
on the RDN attribute of an object.
ERROR_DS_CANT_ON_RDN
8215
The directory service detected an attempt to modify the
object class of an object.
ERROR_DS_CANT_MOD_
OBJ_CLASS
8216
The requested cross-domain move operation could not be
performed.
ERROR_DS_CROSS_DOM_
MOVE_ERROR
8217
Unable to contact the global catalog server.
ERROR_DS_GC_NOT_
AVAILABLE
8218
The policy object is shared and can only be modified at the
root.
ERROR_SHARED_POLICY
8219
The policy object does not exist.
ERROR_POLICY_OBJECT_
NOT_FOUND
8220
The requested policy information is only in the directory
service.
ERROR_POLICY_ONLY_IN_
DS
8221
A domain controller promotion is currently active.
ERROR_PROMOTION_
ACTIVE
8222
A domain controller promotion is not currently active
ERROR_NO_PROMOTION_
ACTIVE
8224
An operations error occurred.
ERROR_DS_OPERATIONS_
ERROR
8225
A protocol error occurred.
ERROR_DS_PROTOCOL_
ERROR
8226
The time limit for this request was exceeded.
ERROR_DS_TIMELIMIT_
EXCEEDED
8227
The size limit for this request was exceeded.
ERROR_DS_SIZELIMIT_
EXCEEDED
8228
The administrative limit for this request was exceeded.
ERROR_DS_ADMIN_LIMIT_
EXCEEDED
8229
The compare response was false.
ERROR_DS_COMPARE_
FALSE
8230
The compare response was true.
ERROR_DS_COMPARE_
TRUE
8231
The requested authentication method is not supported by the
server.
ERROR_DS_AUTH_
METHOD_NOT_SUPPORTED
8232
A more secure authentication method is required for this
server.
ERROR_DS_STRONG_
AUTH_REQUIRED
8233
Inappropriate authentication.
ERROR_DS_
INAPPROPRIATE_AUTH
8234
The authentication mechanism is unknown.
ERROR_DS_AUTH_
UNKNOWN
8235
A referral was returned from the server.
ERROR_DS_REFERRAL
8236
The server does not support the requested critical extension.
ERROR_DS_UNAVAILABLE_
CRIT_EXTENSION
Automation Engine
113
8237
This request requires a secure connection.
ERROR_DS_
CONFIDENTIALITY_
REQUIRED
8238
Inappropriate matching.
ERROR_DS_
INAPPROPRIATE_
MATCHING
8239
A constraint violation occurred.
ERROR_DS_CONSTRAINT_
VIOLATION
8240
There is no such object on the server.
ERROR_DS_NO_SUCH_
OBJECT
8241
There is an alias problem.
ERROR_DS_ALIAS_
PROBLEM
8242
An invalid dn syntax has been specified.
ERROR_DS_INVALID_DN_
SYNTAX
8243
The object is a leaf object.
ERROR_DS_IS_LEAF
8244
There is an alias dereferencing problem.
ERROR_DS_ALIAS_DEREF_
PROBLEM
8245
The server is unwilling to process the request.
ERROR_DS_UNWILLING_
TO_PERFORM
8246
A loop has been detected.
ERROR_DS_LOOP_DETECT
8247
There is a naming violation.
ERROR_DS_NAMING_
VIOLATION
8248
The result set is too large.
ERROR_DS_OBJECT_
RESULTS_TOO_LARGE
8249
The operation affects multiple DSAs
ERROR_DS_AFFECTS_
MULTIPLE_DSAS
8250
The server is not operational.
ERROR_DS_SERVER_
DOWN
8251
A local error has occurred.
ERROR_DS_LOCAL_ERROR
8252
An encoding error has occurred.
ERROR_DS_ENCODING_
ERROR
8253
A decoding error has occurred.
ERROR_DS_DECODING_
ERROR
8254
The search filter cannot be recognized.
ERROR_DS_FILTER_
UNKNOWN
8255
One or more parameters are illegal.
ERROR_DS_PARAM_
ERROR
8256
The specified method is not supported.
ERROR_DS_NOT_
SUPPORTED
8257
No results were returned.
ERROR_DS_NO_RESULTS_
RETURNED
8258
The specified control is not supported by the server.
ERROR_DS_CONTROL_
NOT_FOUND
8259
A referral loop was detected by the client.
ERROR_DS_CLIENT_LOOP
114
Chapter 4 External Error Codes
8260
The preset referral limit was exceeded.
ERROR_DS_REFERRAL_
LIMIT_EXCEEDED
8301
The root object must be the head of a naming context. The
root object cannot have an instantiated parent.
ERROR_DS_ROOT_MUST_
BE_NC
8302
The add replica operation cannot be performed. The naming
context must be writable in order to create the replica.
ERROR_DS_ADD_REPLICA_
INHIBITED
8303
A reference to an attribute that is not defined in the schema
occurred.
ERROR_DS_ATT_NOT_DEF_
IN_SCHEMA
8304
The maximum size of an object has been exceeded.
ERROR_DS_MAX_OBJ_
SIZE_EXCEEDED
8305
An attempt was made to add an object to the directory with a
name that is already in use.
ERROR_DS_OBJ_STRING_
NAME_EXISTS
8306
An attempt was made to add an object of a class that does
not have an RDN defined in the schema.
ERROR_DS_NO_RDN_
DEFINED_IN_SCHEMA
8307
An attempt was made to add an object using an RDN that is
not the RDN defined in the schema.
ERROR_DS_RDN_DOESNT_
MATCH_SCHEMA
8308
None of the requested attributes were found on the objects.
ERROR_DS_NO_
REQUESTED_ATTS_FOUND
8309
The user buffer is too small.
ERROR_DS_USER_
BUFFER_TO_SMALL
8310
The attribute specified in the operation is not present on the
object.
ERROR_DS_ATT_IS_NOT_
ON_OBJ
8311
Illegal modify operation. Some aspect of the modification is
not allowed.
ERROR_DS_ILLEGAL_MOD_
OPERATION
8312
The specified object is too large.
ERROR_DS_OBJ_TOO_
LARGE
8313
The specified instance type is not valid.
ERROR_DS_BAD_
INSTANCE_TYPE
8314
The operation must be performed at the master DSA. The
DNS root attribute is missing on the cross-reference object.
ERROR_DS_MASTERDSA_
REQUIRED
8315
The object class attribute must be specified.
ERROR_DS_OBJECT_
CLASS_REQUIRED
8316
A required attribute is missing.
ERROR_DS_MISSING_
REQUIRED_ATT
8317
An attempt was made to modify an object to include an
attribute that is not legal for its class
ERROR_DS_ATT_NOT_DEF_
FOR_CLASS
8318
The specified attribute is already present on the object.
ERROR_DS_ATT_ALREADY_
EXISTS
8320
The specified attribute is not present, or has no values.
ERROR_DS_CANT_ADD_
ATT_VALUES
8321
An attribute's single value constraint has been violated.
ERROR_DS_SINGLE_
VALUE_CONSTRAINT
8322
An attribute's range constraint has been violated.
ERROR_DS_RANGE_
CONSTRAINT
Automation Engine
115
8323
The specified value already exists.
ERROR_DS_ATT_VAL_
ALREADY_EXISTS
8324
The attribute cannot be removed because it is not present on
the object.
ERROR_DS_CANT_REM_
MISSING_ATT
8325
The attribute value cannot be removed because it is not
present on the object.
ERROR_DS_CANT_REM_
MISSING_ATT_VAL
8326
The specified root object cannot be a subref.
ERROR_DS_ROOT_CANT_
BE_SUBREF
8327
Chaining is not allowed.
ERROR_DS_NO_CHAINING
8328
Chained evaluation is not allowed.
ERROR_DS_NO_CHAINED_
EVAL
8329
The operation could not be performed because the object's
parent is either uninstantiated or deleted.
ERROR_DS_NO_PARENT_
OBJECT
8330
Having a parent that is an alias is not allowed. Aliases are
leaf objects.
ERROR_DS_PARENT_IS_
AN_ALIAS
8331
The object and parent must be of the same type, either both
masters or both replicas.
ERROR_DS_CANT_MIX_
MASTER_AND_REPS
8332
The operation cannot be performed because child objects
exist. This operation can only be performed on a leaf object.
ERROR_DS_CHILDREN_
EXIST
8333
Directory object not found.
ERROR_DS_OBJ_NOT_
FOUND
8334
The aliased object is missing.
ERROR_DS_ALIASED_OBJ_
MISSING
8335
The object name has bad syntax.
ERROR_DS_BAD_NAME_
SYNTAX
8336
It is not allowed for an alias to refer to another alias.
ERROR_DS_ALIAS_POINTS_
TO_ALIAS
8337
The alias cannot be dereferenced.
ERROR_DS_CANT_DEREF_
ALIAS
8338
The operation is out of scope.
ERROR_DS_OUT_OF_
SCOPE
8340
The DSA object cannot be deleted.
ERROR_DS_CANT_
DELETE_DSA_OBJ
8341
A directory service error has occurred.
ERROR_DS_GENERIC_
ERROR
8342
The operation can only be performed on an internal master
DSA object.
ERROR_DS_DSA_MUST_
BE_INT_MASTER
8343
The object must be of class DSA.
ERROR_DS_CLASS_NOT_
DSA
8344
Insufficient access rights to perform the operation.
ERROR_DS_INSUFF_
ACCESS_RIGHTS
8345
The object cannot be added because the parent is not on the
list of possible superiors.
ERROR_DS_ILLEGAL_
SUPERIOR
116
Chapter 4 External Error Codes
8346
Access to the attribute is not allowed because the attribute is
owned by the Security Accounts Manager (SAM).
ERROR_DS_ATTRIBUTE_
OWNED_BY_SAM
8347
The name has too many parts.
ERROR_DS_NAME_TOO_
MANY_PARTS
8348
The name is too long.
ERROR_DS_NAME_TOO_
LONG
8349
The name value is too long.
ERROR_DS_NAME_VALUE_
TOO_LONG
8350
The directory service encountered an error parsing a name.
ERROR_DS_NAME_
UNPARSEABLE
8351
The directory service cannot get the attribute type for a
name.
ERROR_DS_NAME_TYPE_
UNKNOWN
8352
The name does not identify an object; the name identifies a
phantom.
ERROR_DS_NOT_AN_
OBJECT
8353
The security descriptor is too short.
ERROR_DS_SEC_DESC_
TOO_SHORT
8354
The security descriptor is invalid.
ERROR_DS_SEC_DESC_
INVALID
8355
Failed to create name for deleted object.
ERROR_DS_NO_DELETED_
NAME
8356
The parent of a new subref must exist.
ERROR_DS_SUBREF_
MUST_HAVE_PARENT
8357
The object must be a naming context.
ERROR_DS_NCNAME_
MUST_BE_NC
8358
It is not allowed to add an attribute which is owned by the
system.
ERROR_DS_CANT_ADD_
SYSTEM_ONLY
8359
The class of the object must be structural; you cannot
instantiate an abstract class.
ERROR_DS_CLASS_MUST_
BE_CONCRETE
8360
The schema object could not be found.
ERROR_DS_INVALID_DMD
8361
A local object with this GUID (dead or alive) already exists.
ERROR_DS_OBJ_GUID_
EXISTS
8362
The operation cannot be performed on a back link.
ERROR_DS_NOT_ON_
BACKLINK
8363
The cross reference for the specified naming context could
not be found.
ERROR_DS_NO_
CROSSREF_FOR_NC
8364
The operation could not be performed because the directory
service is shutting down.
ERROR_DS_SHUTTING_
DOWN
8365
The directory service request is invalid.
ERROR_DS_UNKNOWN_
OPERATION
8366
The role owner attribute could not be read.
ERROR_DS_INVALID_
ROLE_OWNER
8367
The requested FSMO operation failed. The current FSMO
holder could not be reached.
ERROR_DS_COULDNT_
CONTACT_FSMO
Automation Engine
117
8368
Modification of a DN across a naming context is not allowed.
ERROR_DS_CROSS_NC_
DN_RENAME
8369
The attribute cannot be modified because it is owned by the
system.
ERROR_DS_CANT_MOD_
SYSTEM_ONLY
8370
Only the replicator can perform this function.
ERROR_DS_REPLICATOR_
ONLY
8371
The specified class is not defined.
ERROR_DS_OBJ_CLASS_
NOT_DEFINED
8372
The specified class is not a subclass.
ERROR_DS_OBJ_CLASS_
NOT_SUBCLASS
8373
The name reference is invalid.
ERROR_DS_NAME_
REFERENCE_INVALID
8374
A cross reference already exists.
ERROR_DS_CROSS_REF_
EXISTS
8375
It is not allowed to delete a master cross reference.
ERROR_DS_CANT_DEL_
MASTER_CROSSREF
8376
Subtree notifications are only supported on NC heads.
ERROR_DS_SUBTREE_
NOTIFY_NOT_NC_HEAD
8377
Notification filter is too complex.
ERROR_DS_NOTIFY_
FILTER_TOO_COMPLEX
8378
Schema update failed: duplicate RDN.
ERROR_DS_DUP_RDN
8379
Schema update failed: duplicate OID
ERROR_DS_DUP_OID
8380
Schema update failed: duplicate MAPI identifier.
ERROR_DS_DUP_MAPI_ID
8381
Schema update failed: duplicate schema-id GUID.
ERROR_DS_DUP_SCHEMA_
ID_GUID
8382
Schema update failed: duplicate LDAP display name.
ERROR_DS_DUP_LDAP_
DISPLAY_NAME
8383
Schema update failed: range-lower less than range upper
ERROR_DS_SEMANTIC_
ATT_TEST
8384
Schema update failed: syntax mismatch
ERROR_DS_SYNTAX_
MISMATCH
8385
Schema deletion failed: attribute is used in must-contain
ERROR_DS_EXISTS_IN_
MUST_HAVE
8386
Schema deletion failed: attribute is used in can-contain
ERROR_DS_EXISTS_IN_
can_HAVE
8387
Schema update failed: attribute in can-contain does not exist
ERROR_DS_
NONEXISTENT_can_HAVE
8388
Schema update failed: attribute in must-contain does not
exist
ERROR_DS_
NONEXISTENT_MUST_
HAVE
8389
Schema update failed: class in aux-class list does not exist
or is not an auxiliary class
ERROR_DS_AUX_CLS_
TEST_FAIL
8390
Schema update failed: class in poss-superiors does not exist
ERROR_DS_
NONEXISTENT_POSS_SUP
118
Chapter 4 External Error Codes
8391
Schema update failed: class in subclass of list does not exist ERROR_DS_SUB_CLS_
or does not satisfy hierarchy rules
TEST_FAIL
8392
Schema update failed: Rdn-Att-Id has wrong syntax
ERROR_DS_BAD_RDN_
ATT_ID_SYNTAX
8393
Schema deletion failed: class is used as auxiliary class
ERROR_DS_EXISTS_IN_
AUX_CLS
8394
Schema deletion failed: class is used as sub class
ERROR_DS_EXISTS_IN_
SUB_CLS
8395
Schema deletion failed: class is used as poss superior
ERROR_DS_EXISTS_IN_
POSS_SUP
8396
Schema update failed in recalculating validation cache.
ERROR_DS_
RECALCSCHEMA_FAILED
8397
The tree deletion is not finished.
ERROR_DS_TREE_DELETE_
NOT_FINISHED
8398
The requested delete operation could not be performed.
ERROR_DS_CANT_DELETE
8399
Cannot read the governs class identifier for the schema
record.
ERROR_DS_ATT_SCHEMA_
REQ_ID
8400
The attribute schema has bad syntax.
ERROR_DS_BAD_ATT_
SCHEMA_SYNTAX
8401
The attribute could not be cached.
ERROR_DS_CANT_CACHE_
ATT
8402
The class could not be cached.
ERROR_DS_CANT_CACHE_
CLASS
8403
The attribute could not be removed from the cache.
ERROR_DS_CANT_
REMOVE_ATT_CACHE
8404
The class could not be removed from the cache.
ERROR_DS_CANT_
REMOVE_CLASS_CACHE
8405
The distinguished name attribute could not be read.
ERROR_DS_CANT_
RETRIEVE_DN
8406
A required subref is missing.
ERROR_DS_MISSING_
SUPREF
8407
The instance type attribute could not be retrieved.
ERROR_DS_CANT_
RETRIEVE_INSTANCE
8408
An internal error has occurred.
ERROR_DS_CODE_
INCONSISTENCY
8409
A database error has occurred.
ERROR_DS_DATABASE_
ERROR
8410
The attribute GOVERNSID is missing.
ERROR_DS_GOVERNSID_
MISSING
8411
An expected attribute is missing.
ERROR_DS_MISSING_
EXPECTED_ATT
8412
The specified naming context is missing a cross reference.
ERROR_DS_NCNAME_
MISSING_CR_REF
Automation Engine
119
8413
A security checking error has occurred.
ERROR_DS_SECURITY_
CHECKING_ERROR
8414
The schema is not loaded.
ERROR_DS_SCHEMA_NOT_
LOADED
8415
Schema allocation failed.
ERROR_DS_SCHEMA_
ALLOC_FAILED
8416
Failed to obtain the required syntax for the attribute schema.
ERROR_DS_ATT_SCHEMA_
REQ_SYNTAX
8417
The global catalog verification failed. The global catalog is
not available or does not support the operation. Some part of
the directory is currently not available.
ERROR_DS_GCVERIFY_
ERROR
8418
The replication operation failed because of a schema
mismatch between the servers involved.
ERROR_DS_DRA_SCHEMA_
MISMATCH
8419
The DSA object could not be found.
ERROR_DS_CANT_FIND_
DSA_OBJ
8420
The naming context could not be found.
ERROR_DS_CANT_FIND_
EXPECTED_NC
8421
The naming context could not be found in the cache.
ERROR_DS_CANT_FIND_
NC_IN_CACHE
8422
The child object could not be retrieved.
ERROR_DS_CANT_
RETRIEVE_CHILD
8423
The modification was not allowed for security reasons.
ERROR_DS_SECURITY_
ILLEGAL_MODIFY
8424
The operation cannot replace the hidden record.
ERROR_DS_CANT_
REPLACE_HIDDEN_REC
8425
The hierarchy file is invalid.
ERROR_DS_BAD_
HIERARCHY_FILE
8426
The attempt to build the hierarchy table failed.
ERROR_DS_BUILD_
HIERARCHY_TABLE_FAILED
8427
The directory configuration parameter is missing from the
registry.
ERROR_DS_CONFIG_
PARAM_MISSING
8428
The attempt to count the address book indices failed.
ERROR_DS_COUNTING_
AB_INDICES_FAILED
8429
The allocation of the hierarchy table failed.
ERROR_DS_HIERARCHY_
TABLE_MALLOC_FAILED
8430
The directory service encountered an internal failure.
ERROR_DS_INTERNAL_
FAILURE
8431
The directory service encountered an unknown failure.
ERROR_DS_UNKNOWN_
ERROR
8432
A root object requires a class of 'top'.
ERROR_DS_ROOT_
REQUIRES_CLASS_TOP
8433
This directory server is shutting down, and cannot take
ownership of new floating single-master operation roles.
ERROR_DS_REFUSING_
FSMO_ROLES
120
Chapter 4 External Error Codes
8434
The directory service is missing mandatory configuration
information, and is unable to determine the ownership of
floating single-master operation roles.
ERROR_DS_MISSING_
FSMO_SETTINGS
8435
The directory service was unable to transfer ownership of
one or more floating single-master operation roles to other
servers.
ERROR_DS_UNABLE_TO_
SURRENDER_ROLES
8436
The replication operation failed.
ERROR_DS_DRA_GENERIC
8437
An invalid parameter was specified for this replication
operation.
ERROR_DS_DRA_INVALID_
PARAMETER
8438
The Windows NT directory service is too busy to complete
the replication operation at this time.
ERROR_DS_DRA_BUSY
8439
The distinguished name specified for this replication
operation is invalid.
ERROR_DS_DRA_BAD_DN
8440
The naming context specified for this replication operation is
invalid.
ERROR_DS_DRA_BAD_NC
8441
The distinguished name specified for this replication
operation already exists.
ERROR_DS_DRA_DN_
EXISTS
8442
The replication system encountered an internal error.
ERROR_DS_DRA_
INTERNAL_ERROR
8443
The replication operation encountered a database
inconsistency.
ERROR_DS_DRA_
INCONSISTENT_DIT
8444
The server specified for this replication operation could not be ERROR_DS_DRA_
contacted.
CONNECTION_FAILED
8445
The replication operation encountered an object with an
invalid instance type.
ERROR_DS_DRA_BAD_
INSTANCE_TYPE
8446
The replication operation failed to allocate memory.
ERROR_DS_DRA_OUT_OF_
MEM
8447
The replication operation encountered an error with the mail
system.
ERROR_DS_DRA_MAIL_
PROBLEM
8448
The replication reference information for the target server
already exists.
ERROR_DS_DRA_REF_
ALREADY_EXISTS
8449
The replication reference information for the target server
does not exist.
ERROR_DS_DRA_REF_
NOT_FOUND
8450
The naming context cannot be removed because it is
replicated to another server.
ERROR_DS_DRA_OBJ_IS_
REP_SOURCE
8451
The replication operation encountered a database error.
ERROR_DS_DRA_DB_
ERROR
8452
The naming context is in the process of being removed or is
not replicated from the specified server.
ERROR_DS_DRA_NO_
REPLICA
8453
Replication access was denied.
ERROR_DS_DRA_ACCESS_
DENIED
8454
The requested operation is not supported by this version of
the Windows NT directory service.
ERROR_DS_DRA_NOT_
SUPPORTED
8455
The replication remote procedure call was canceled.
ERROR_DS_DRA_RPC_
CANCELED
Automation Engine
121
8456
The source server is currently rejecting replication requests.
ERROR_DS_DRA_SOURCE_
DISABLED
8457
The destination server is currently rejecting replication
requests.
ERROR_DS_DRA_SINK_
DISABLED
8458
The replication operation failed due to a collision of object
names.
ERROR_DS_DRA_NAME_
COLLISION
8459
The replication source has been reinstalled.
ERROR_DS_DRA_SOURCE_
REINSTALLED
8460
The replication operation failed because a required parent
object is missing.
ERROR_DS_DRA_MISSING_
PARENT
8461
The replication operation was preempted.
ERROR_DS_DRA_
PREEMPTED
8462
The replication synchronization attempt was abandoned
because of a lack of updates.
ERROR_DS_DRA_
ABANDON_SYNC
8463
The replication operation was terminated because the
system is shutting down.
ERROR_DS_DRA_
SHUTDOWN
8464
The replication synchronization attempt failed as the
destination partial attribute set is not a subset of source
partial attribute set.
ERROR_DS_DRA_
INCOMPATIBLE_PARTIAL_
SET
8465
The replication synchronization attempt failed because a
master replica attempted to sync from a partial replica.
ERROR_DS_DRA_SOURCE_
IS_PARTIAL_REPLICA
8466
The server specified for this replication operation was
contacted, but that server was unable to contact an
additional server needed to complete the operation.
ERROR_DS_DRA_EXTN_
CONNECTION_FAILED
8467
A schema mismatch is detected between the source and the
build used during a replica install. The replica cannot be
installed.
ERROR_DS_INSTALL_
SCHEMA_MISMATCH
8468
Schema update failed: An attribute with the same link
identifier already exists.
ERROR_DS_DUP_LINK_ID
8469
Name translation: Generic processing error.
ERROR_DS_NAME_ERROR_
RESOLVING
8470
Name translation: Could not find the name or insufficient right ERROR_DS_NAME_ERROR_
to see name.
NOT_FOUND
8471
Name translation: Input name mapped to more than one
output name.
ERROR_DS_NAME_ERROR_
NOT_UNIQUE
8472
Name translation: Input name found, but not the associated
output format.
ERROR_DS_NAME_ERROR_
NO_MAPPING
8473
Name translation: Unable to resolve completely, only the
domain was found.
ERROR_DS_NAME_ERROR_
DOMAIN_ONLY
8474
Name translation: Unable to perform purely syntactical
mapping at the client without going out to the wire.
ERROR_DS_NAME_ERROR_
NO_SYNTACTICAL_
MAPPING
8475
Modification of a constructed att is not allowed.
ERROR_DS_
CONSTRUCTED_ATT_MOD
122
Chapter 4 External Error Codes
8476
The OM-Object-Class specified is incorrect for an attribute
with the specified syntax.
ERROR_DS_WRONG_OM_
OBJ_CLASS
8477
The replication request has been posted; waiting for reply.
ERROR_DS_DRA_REPL_
PENDING
8478
The requested operation requires a directory service, and
none was available.
ERROR_DS_DS_REQUIRED
8479
The LDAP display name of the class or attribute contains
non-ASCII characters.
ERROR_DS_INVALID_LDAP_
DISPLAY_NAME
8480
The requested search operation is only supported for base
searches.
ERROR_DS_NON_BASE_
SEARCH
8481
The search failed to retrieve attributes from the database.
ERROR_DS_CANT_
RETRIEVE_ATTS
8482
The schema update operation tried to add a backward link
attribute that has no corresponding forward link.
ERROR_DS_BACKLINK_
WITHOUT_LINK
8483
Source and destination of a cross domain move do not agree
on the object's epoch number. Either source or destination
does not have the latest version of the object.
ERROR_DS_EPOCH_
MISMATCH
8484
Source and destination of a cross domain move do not agree
on the object's current name. Either source or destination
does not have the latest version of the object.
ERROR_DS_SRC_NAME_
MISMATCH
8485
Source and destination of a cross domain move operation are ERROR_DS_SRC_AND_
identical. Caller should use local move operation instead of
DST_NC_IDENTICAL
cross domain move operation.
8486
Source and destination for a cross domain move are not in
agreement on the naming contexts in the forest. Either
source or destination does not have the latest version of the
Partitions container.
ERROR_DS_DST_NC_
MISMATCH
8487
Destination of a cross domain move is not authoritative for
the destination naming context.
ERROR_DS_NOT_
AUTHORITIVE_FOR_DST_
NC
8488
Source and destination of a cross domain move do not agree
on the identity of the source object. Either source or
destination does not have the latest version of the source
object.
ERROR_DS_SRC_GUID_
MISMATCH
8489
Object being moved across domains is already known to be
ERROR_DS_CANT_MOVE_
deleted by the destination server. The source server does not DELETED_OBJECT
have the latest version of the source object.
8490
Another operation which requires exclusive access to the
PDC PSMO is already in progress.
ERROR_DS_PDC_
OPERATION_IN_PROGRESS
8491
A cross domain move operation failed such that the two
versions of the moved object exist - one each in the source
and destination domains. The destination object must be
removed to restore the system to a consistent state.
ERROR_DS_CROSS_
DOMAIN_CLEANUP_REQD
8492
This object cannot be moved across domain boundaries
either because cross domain moves for this class are
disallowed, or the object has some special characteristics,
eg: trust account or restricted RID, which prevent its move.
ERROR_DS_ILLEGAL_
XDOM_MOVE_OPERATION
Automation Engine
123
8493
Can't move objects with memberships across domain
boundaries as once moved, this would violate the
membership conditions of the account group. Remove the
object from any account group memberships and retry.
ERROR_DS_CANT_WITH_
ACCT_GROUP_
MEMBERSHPS
8494
A naming context head must be the immediate child of
another naming context head, not of an interior node.
ERROR_DS_NC_MUST_
HAVE_NC_PARENT
8495
The directory cannot validate the proposed naming context
name because it does not hold a replica of the naming
context above the proposed naming context.
ERROR_DS_CR_
IMPOSSIBLE_TO_VALIDATE
8496
Destination of a cross domain move must be in native mode.
ERROR_DS_DST_DOMAIN_
NOT_NATIVE
8497
The operation cannot be performed because the server does
not have an infrastructure container in the domain of interest.
ERROR_DS_MISSING_
INFRASTRUCTURE_
CONTAINER
8498
Cross domain move of account groups is not allowed.
ERROR_DS_CANT_MOVE_
ACCOUNT_GROUP
8499
Cross domain move of resource groups is not allowed.
ERROR_DS_CANT_MOVE_
RESOURCE_GROUP
8500
The search flags for the attribute are invalid. The ANR bit is
valid only on attributes of Unicode or Teletex strings.
ERROR_DS_INVALID_
SEARCH_FLAG
8501
Tree deletions starting at an object which has an NC head as
a descendant are not allowed.
ERROR_DS_NO_TREE_
DELETE_ABOVE_NC
8502
The directory service failed to lock a tree in preparation for a
tree deletion because the tree was in use.
ERROR_DS_COULDNT_
LOCK_TREE_FOR_DELETE
8503
The directory service failed to identify the list of objects to
delete while attempting a tree deletion.
ERROR_DS_COULDNT_
IDENTIFY_OBJECTS_FOR_
TREE_DELETE
8504
Security Accounts Manager initialization failed because of
the following error: %1.
ERROR_DS_SAM_INIT_
FAILURE
Error Status: 0x%2. Click OK tab to shut down the system,
then select Safe Mode during reboot. For more information,
check the event log.
8505
Only an administrator can modify the membership list of an
administrative group.
ERROR_DS_SENSITIVE_
GROUP_VIOLATION
8506
Cannot change the primary group ID of a domain controller
account.
ERROR_DS_CANT_MOD_
PRIMARYGROUPID
9001
DNS server unable to interpret format.
DNS_ERROR_RCODE_
FORMAT_ERROR
9002
DNS server failure.
DNS_ERROR_RCODE_
SERVER_FAILURE
9003
DNS name does not exist.
DNS_ERROR_RCODE_
NAME_ERROR
9004
DNS request not supported by name server.
DNS_ERROR_RCODE_NOT_
IMPLEMENTED
124
Chapter 4 External Error Codes
9005
DNS operation refused.
DNS_ERROR_RCODE_
REFUSED
9006
DNS name that ought not exist, does exist.
DNS_ERROR_RCODE_
YXDOMAIN
9007
DNS RR set that ought not exist, does exist.
DNS_ERROR_RCODE_
YXRRSET
9008
DNS RR set that ought to exist, does not exist.
DNS_ERROR_RCODE_
NXRRSET
9009
DNS server not authoritative for zone.
DNS_ERROR_RCODE_
NOTAUTH
9010
DNS name in update or prereq is not in zone.
DNS_ERROR_RCODE_
NOTZONE
9016
DNS signature failed to verify.
DNS_ERROR_RCODE_
BADSIG
9017
DNS bad key.
DNS_ERROR_RCODE_
BADKEY
9018
DNS signature validity expired.
DNS_ERROR_RCODE_
BADTIME
9501
No records found for given DNS query.
DNS_INFO_NO_RECORDS
9502
Bad DNS packet.
DNS_ERROR_BAD_PACKET
9503
No DNS packet.
DNS_ERROR_NO_PACKET
9504
DNS error, check rcode.
DNS_ERROR_RCODE
9505
Unsecured DNS packet.
DNS_ERROR_UNSECURE_
PACKET
9551
Invalid DNS type.
DNS_ERROR_INVALID_
TYPE
9552
Invalid IP address.
DNS_ERROR_INVALID_IP_
ADDRESS
9553
Invalid property.
DNS_ERROR_INVALID_
PROPERTY
9554
Try DNS operation again later.
DNS_ERROR_TRY_AGAIN_
LATER
9555
Record for given name and type is not unique.
DNS_ERROR_NOT_UNIQUE
9556
DNS name does not comply with RFC specifications.
DNS_ERROR_NON_RFC_
NAME
9557
DNS name is a fully-qualified DNS name.
DNS_STATUS_FQDN
9558
DNS name is dotted (multi-label).
DNS_STATUS_DOTTED_
NAME
9559
DNS name is a single-part name.
DNS_STATUS_SINGLE_
PART_NAME
9601
DNS zone does not exist.
DNS_ERROR_ZONE_DOES_
NOT_EXIST
Automation Engine
125
9602
DNS zone information not available.
DNS_ERROR_NO_ZONE_
INFO
9603
Invalid operation for DNS zone.
DNS_ERROR_INVALID_
ZONE_OPERATION
9604
Invalid DNS zone configuration.
DNS_ERROR_ZONE_
CONFIGURATION_ERROR
9605
DNS zone has no start of authority (SOA) record.
DNS_ERROR_ZONE_HAS_
NO_SOA_RECORD
9606
DNS zone has no name server (NS) record.
DNS_ERROR_ZONE_HAS_
NO_NS_RECORDS
9607
DNS zone is locked.
DNS_ERROR_ZONE_
LOCKED
9608
DNS zone creation failed.
DNS_ERROR_ZONE_
CREATION_FAILED
9609
DNS zone already exists.
DNS_ERROR_ZONE_
ALREADY_EXISTS
9610
DNS automatic zone already exists.
DNS_ERROR_AUTOZONE_
ALREADY_EXISTS
9611
Invalid DNS zone type.
DNS_ERROR_INVALID_
ZONE_TYPE
9612
Secondary DNS zone requires master IP address.
DNS_ERROR_
SECONDARY_REQUIRES_
MASTER_IP
9613
DNS zone not secondary.
DNS_ERROR_ZONE_NOT_
SECONDARY
9614
Need secondary IP address.
DNS_ERROR_NEED_
SECONDARY_ADDRESSES
9615
WINS initialization failed.
DNS_ERROR_WINS_INIT_
FAILED
9616
Need WINS servers.
DNS_ERROR_NEED_WINS_
SERVERS
9617
NBTSTAT initialization call failed.
DNS_ERROR_NBSTAT_
INIT_FAILED
9618
Invalid delete of start of authority (SOA)
DNS_ERROR_SOA_
DELETE_INVALID
9651
Primary DNS zone requires datafile.
DNS_ERROR_PRIMARY_
REQUIRES_DATAFILE
9652
Invalid datafile name for DNS zone.
DNS_ERROR_INVALID_
DATAFILE_NAME
9653
Failed to open datafile for DNS zone.
DNS_ERROR_DATAFILE_
OPEN_FAILURE
9654
Failed to write datafile for DNS zone.
DNS_ERROR_FILE_
WRITEBACK_FAILED
9655
Failure while reading datafile for DNS zone.
DNS_ERROR_DATAFILE_
PARSING
126
Chapter 4 External Error Codes
9701
DNS record does not exist.
DNS_ERROR_RECORD_
DOES_NOT_EXIST
9702
DNS record format error.
DNS_ERROR_RECORD_
FORMAT
9703
Node creation failure in DNS.
DNS_ERROR_NODE_
CREATION_FAILED
9704
Unknown DNS record type.
DNS_ERROR_UNKNOWN_
RECORD_TYPE
9705
DNS record timed out.
DNS_ERROR_RECORD_
TIMED_OUT
9706
Name not in DNS zone.
DNS_ERROR_NAME_NOT_
IN_ZONE
9707
CNAME loop detected.
DNS_ERROR_CNAME_LOOP
9708
Node is a CNAME DNS record.
DNS_ERROR_NODE_IS_
CNAME
9709
A CNAME record already exists for given name.
DNS_ERROR_CNAME_
COLLISION
9710
Record only at DNS zone root.
DNS_ERROR_RECORD_
ONLY_AT_ZONE_ROOT
9711
DNS record already exists.
DNS_ERROR_RECORD_
ALREADY_EXISTS
9712
Secondary DNS zone data error.
DNS_ERROR_
SECONDARY_DATA
9713
Could not create DNS cache data.
DNS_ERROR_NO_CREATE_
CACHE_DATA
9714
DNS name does not exist.
DNS_ERROR_NAME_DOES_
NOT_EXIST
9715
Could not create pointer (PTR) record.
DNS_WARNING_PTR_
CREATE_FAILED
9716
DNS domain was undeleted.
DNS_WARNING_DOMAIN_
UNDELETED
9717
The Windows NT directory service is unavailable.
DNS_ERROR_DS_
UNAVAILABLE
9718
DNS zone already exists in Windows NT directory service.
DNS_ERROR_DS_ZONE_
ALREADY_EXISTS
9719
DNS server not creating or reading the boot file for the
directory service integrated DNS zone.
DNS_ERROR_NO_
BOOTFILE_IF_DS_ZONE
9751
DNS AXFR (zone transfer) complete.
DNS_INFO_AXFR_
COMPLETE
9752
DNS zone transfer failed.
DNS_ERROR_AXFR
9753
Added local WINS server.
DNS_INFO_ADDED_LOCAL_
WINS
9801
Secure update call must continue update request.
DNS_STATUS_CONTINUE_
NEEDED
Automation Engine
9851
TCP/IP network protocol not installed.
DNS_ERROR_NO_TCPIP
9852
No DNS servers configured for local system.
DNS_ERROR_NO_DNS_
SERVERS
127
10004 A blocking operation was interrupted by a call to
WSACancelBlockingCall.
WSAEINTR
10009 The file handle supplied is not valid.
WSAEBADF
10013 An attempt was made to access a socket in a way forbidden
by its access permissions.
WSAEACCES
10014 The system detected an invalid pointer address in attempting
to use a pointer argument in a call.
WSAEFAULT
10022 An invalid argument was supplied.
WSAEINVAL
10024 Too many open sockets.
WSAEMFILE
10035 A non-blocking socket operation could not be completed
immediately.
WSAEWOULDBLOCK
10036 A blocking operation is currently executing.
WSAEINPROGRESS
10037 An operation was attempted on a non-blocking socket that
already had an operation in progress.
WSAEALREADY
10038 An operation was attempted on something that is not a
socket.
WSAENOTSOCK
10039 A required address was omitted from an operation on a
socket.
WSAEDESTADDRREQ
10040 A message sent on a datagram socket was larger than the
internal message buffer or some other network limit, or the
buffer used to receive a datagram into was smaller than the
datagram itself.
WSAEMSGSIZE
10041 A protocol was specified in the socket function call that does
not support the semantics of the socket type requested.
WSAEPROTOTYPE
10042 An unknown, invalid, or unsupported option or level was
specified in a getsockopt or setsockopt call.
WSAENOPROTOOPT
10043 The requested protocol has not been configured into the
system, or no implementation for it exists.
WSAEPROTONOSUPPORT
10044 The support for the specified socket type does not exist in
this address family.
WSAESOCKTNOSUPPORT
10045 The attempted operation is not supported for the type of
object referenced.
WSAEOPNOTSUPP
10046 The protocol family has not been configured into the system
or no implementation for it exists.
WSAEPFNOSUPPORT
10047 An address incompatible with the requested protocol was
used.
WSAEAFNOSUPPORT
10048 Only one usage of each socket address (protocol/network
address/port) is normally allowed.
WSAEADDRINUSE
10049 The requested address is not valid in its context.
WSAEADDRNOTAVAIL
10050 A socket operation encountered a dead network.
WSAENETDOWN
128
Chapter 4 External Error Codes
10051 A socket operation was attempted to an unreachable
network.
WSAENETUNREACH
10052 The connection has been broken due to keep-alive activity
detecting a failure while the operation was in progress.
WSAENETRESET
10053 An established connection was aborted by the software in
your host machine.
WSAECONNABORTED
10054 An existing connection was forcibly closed by the remote
host.
WSAECONNRESET
10055 An operation on a socket could not be performed because the WSAENOBUFS
system lacked sufficient buffer space or because a queue
was full.
10056 A connect request was made on an already connected
socket.
WSAEISCONN
10057 A request to send or receive data was disallowed because
the socket is not connected and (when sending on a
datagram socket using a sendto call) no address was
supplied.
WSAENOTCONN
10058 A request to send or receive data was disallowed because
the socket had already been shut down in that direction with
a previous shutdown call.
WSAESHUTDOWN
10059 Too many references to some kernel object.
WSAETOOMANYREFS
10060 A connection attempt failed because the connected party did
not properly respond after a period of time, or established
connection failed because connected host has failed to
respond.
WSAETIMEDOUT
10061 No connection could be made because the target machine
actively refused it.
WSAECONNREFUSED
10062 Cannot translate name.
WSAELOOP
10063 Name component or name was too long.
WSAENAMETOOLONG
10064 A socket operation failed because the destination host was
down.
WSAEHOSTDOWN
10065 A socket operation was attempted to an unreachable host.
WSAEHOSTUNREACH
10066 Cannot remove a directory that is not empty.
WSAENOTEMPTY
10067 A Windows Sockets implementation can have a limit on the
number of applications that can use it simultaneously.
WSAEPROCLIM
10068 Ran out of quota.
WSAEUSERS
10069 Ran out of disk quota.
WSAEDQUOT
10070 File handle reference is no longer available.
WSAESTALE
10071 Item is not available locally.
WSAEREMOTE
10091 WSAStartup cannot function at this time because the
underlying system it uses to provide network services is
currently unavailable.
WSASYSNOTREADY
10092 The Windows Sockets version requested is not supported.
WSAVERNOTSUPPORTED
Automation Engine
129
10093 Either the application has not called WSAStartup, or
WSAStartup failed.
WSANOTINITIALISED
10101 Returned by WSARecv or WSARecvFrom to indicate the
remote party has initiated a graceful shutdown sequence.
WSAEDISCON
10102 No more results can be returned by
WSALookupServiceNext.
WSAENOMORE
10103 A call to WSALookupServiceEnd was made while this call
was still processing. The call has been canceled.
WSAECANCELED
10104 The procedure call table is invalid.
WSAEINVALIDPROCTABLE
10105 The requested service provider is invalid.
WSAEINVALIDPROVIDER
10106 The requested service provider could not be loaded or
initialized.
WSAEPROVIDERFAILEDINIT
10107 A system call that should never fail has failed.
WSASYSCALLFAILURE
10108 No such service is known. The service cannot be found in
the specified name space.
WSASERVICE_NOT_FOUND
10109 The specified class was not found.
WSATYPE_NOT_FOUND
10110 No more results can be returned by
WSALookupServiceNext.
WSA_E_NO_MORE
10111 A call to WSALookupServiceEnd was made while this call
was still processing. The call has been canceled.
WSA_E_CANCELED
10112 A database query failed because it was actively refused.
WSAEREFUSED
11001 No such host is known.
WSAHOST_NOT_FOUND
11002 This is usually a temporary error during hostname resolution
and means that the local server did not receive a response
from an authoritative server.
WSATRY_AGAIN
11003 A non-recoverable error occurred during a database lookup.
WSANO_RECOVERY
11004 The requested name is valid and was found in the database,
but it does not have the correct associated data being
resolved for.
WSANO_DATA
11005 At least one reserve has arrived.
WSA_QOS_RECEIVERS
11006 At least one path has arrived.
WSA_QOS_SENDERS
11007 There are no senders.
WSA_QOS_NO_SENDERS
11008 There are no receivers.
WSA_QOS_NO_RECEIVERS
11009 Reserve has been confirmed.
WSA_QOS_REQUEST_
CONFIRMED
11010 Error due to lack of resources.
WSA_QOS_ADMISSION_
FAILURE
11011 Rejected for administrative reasons - bad credentials.
WSA_QOS_POLICY_
FAILURE
11012 Unknown or conflicting style.
WSA_QOS_BAD_STYLE
11013 Problem with some part of the filterspec or provider-specific
buffer in general.
WSA_QOS_BAD_OBJECT
130
Chapter 4 External Error Codes
11014 Problem with some part of the flowspec.
WSA_QOS_TRAFFIC_CTRL_
ERROR
11015 General QOS error.
WSA_QOS_GENERIC_
ERROR
Automation Engine
131
5 SNMP Support
5.1 About SNMP
SNMP (Simple Network Management Protocol) is an industry standard for monitoring and controlling
systems, devices and components within a network environment. It has been defined by the IEFT
(Internet Engineering Task Force). The IETF engages itself as a working group for problems regarding
TCP/IP and the Internet.
During the monitoring and controlling of these net elements, SNMP management and SNMP agents are
generally distinguished. The SNMP agent runs on the computer, whose systems, devices and
components are monitored and controlled. Network Management Station (NMS) is a computer which can with an application - present current information on the monitored net elements as well as change the
parameters of these net elements.
NMS and SNMP agents communicate via the network protocol TCP/IP. This allows for two types of
communication. One type queries the Network Management Station conditions of the monitored net
elements by the SNMP agents or sets new parameters. For the second type of communication, the SNMP
agent sends changes of the conditions in its monitored net elements to the Network Management Station.
The report of such a condition change is called a trap or SNMP trap. In order to clearly recognize participating systems also worldwide, a standard address space MIB
(Management Information Base) has been implemented. In this MIB, an MIB ID can be found for each
monitored net element. The MIB ID consists of a series of numbers which are separated by dots. The
worldwide MIB depicts a large tree with branches of the individual components and systems.
SNMP works on the basis of UDP (User Datagram Protocol). This simple protocol not uses an error
monitor or confirmation of transferred information. SNMP uses Port 161 for queries to the SNMP agents
and Port 162 as trap receiver.
5.2 UC4 and SNMP
SNMP can be used to monitor the various conditions which occur within a UC4 system. Its activities
include monitoring the availability of the UC4 Automation Engine and Agents, active Notifications or
blocking tasks. The following illustration explains the interaction of UC4 and SNMP:
132
Chapter 5 SNMP Support
With the SNMP connection being activated, the relevant UC4 system monitoring values are sent to the
UC4 SNMP Subagent. It stores this information in its MIB and makes it available for the
SNMP Masteragent. The MIB content is write protected, the UC4 SNMP Subagent prevents values from
being modified with the SNMP command SET.
For applications (e.g. HP OpenView Operations), there are two methods to obtain information:
l
l
The applications can periodically request information via the SNMP Masteragent which
communicates with the UC4 SNMP Subagent in order to obtain the relevant values.
Events of special importance which occur in the UC4 system trigger SNMP traps. The UC4 SNMP
Subagent immediately forwards them to the SNMP Masteragent to ensure that the applications can
directly obtain the required information.
In particular situations, the UC4 Automation Engine generates predefined traps. You can also send traps
using the script statement :SEND_SNMP_TRAP.
Specify in the UC4 SNMP Subagent's INI file whether the MIB should be loaded and/or traps be sent.
By default, both is done. UC4 recommends deactivating MIB loading if you intend to use traps only in
order to avoid unnecessary performance loads.The corresponding parameter processing= is available
in the section [SNMP].
Masteragent Mode On
The UC4 SNMP Subagent under UNIX is able to act as SNMP Masteragent with the advantage being that
no SNMP service must be configured.
See also:
Automation Engine
133
MIB Structure
Installing the UC4 SNMP Subagent (UNIX)
Installing the UC4 SNMP Subagent (Windows)
UC4 SNMP-Subagent's Glossary and FAQ
Requirements - Checklist
5.3 Agent Mode on UNIX
Under UNIX, the UC4 SNMP Subagent can run as Masteragent or Subagent.
Specify the mode in the INI-file parameter role= (section [SNMP]).
Masteragent (recommended)
Advantages:
l
l
l
There is no need to install Net-SNMP.
Improved performance
Improved error insulation
Disadvantages:
l
l
l
Only UC4 monitoring starts.
No other MIBs are available.
The variable SNMPCONFPATH must be set. It contains the directory with the file ucsnmp1.conf
(e.g: "export SNMPCONFPATH=./")
You can specify the same parameters in the file ucsnmp1.conf as in the net-SNMP Agent's
configuration file (snmpd.conf).
The UC4 SNMP Subagent uses the following parameters:
l
l
l
trapcommunity
trapsink
rocommunity
134
Chapter 5 SNMP Support
l
l
rwcommunity
master
An explanation of the individual parameters is available in the description of the snmp.conf provided by netSNMP.
Example for the file ucsnmp1.conf:
trapsink host1 trapsink host2 rocommunity public master agentx
In Masteragent mode, no other Subagents can establish a connection to the SNMP Subagent.
Subagent
The UC4 SNMP Subagent cooperates with an existing Masteragent:
l
l
l
A Masteragent which is able to deal with AgentX must be started.
The standard communication medium is a local socket file which is stored in the directory
/var/agentx/mastert. The Masteragent creates this file. The UC4 SNMP Subagent only requires the
right to access it.
The configuration file snmpd.conf contains some settings:
Example for the file ucsnmp1.conf:
trapsink
rocommunity
local
public
HP-UX The UC4 SNMP Subagent must operate on HP UX in Masteragent mode. The native Masteragent for the
HP-UX system is EMANATE. The UC4 SNMP Subagent uses the naaagt interface to communicate to it.
Automation Engine
135
The naaagt interface serves as SNMP proxy. It redirects SNMP queries to a different UDP port via a
registered OID. By default, the naaagt uses port 8161. Thus, the UC4 SNMP Subagent uses a different
port.
Further information about configuring the interface is provided in the naaagt documentation.
See also:
UC4 and SNMP
5.4 UC4 SNMP Subagent's FAQ and Glossary
This document includes frequently asked questions and important terms regarding the UC4 SNMP
Subagent.
Keywords:
l
l
l
l
SNMP - Simple Network Management Protocol
MIB - Management Information Base. Stores information in a tree structure. The MIB is part of the
SNMP Subagent.
Masteragent - SNMP service which communicates with SNMP Subagents in order to query MIB
information and forward it to the relevant applications.
Subagent - Stores information in the MIB and makes it available for the Masteragent.
Frequently asked questions:
What is an OID?
Each information module in the MIB has a unique OID (Object Identifier) which is used to read the MIB's
content. OIDs consist of a series of numbers which are separated from each other with dots. OIDS are
136
Chapter 5 SNMP Support
globally unique. The UC4 SNMP Subagent's MIB has the OID "1.3.6.1.4.1.2562.1.1". The individual MIB
content also has a number which is appended to the MIB's OID. The MIB's tree structure results in OIDs
whose structure reflects the MIB structure.
Example:
The OID of the UC4 Agent's version is: "1.3.6.1.4.1.2562.1.1.1.1.0 " The individual OID parts are:
1.3.6.1.4.1.2562.1.1 - MIB
1 - Agent Group
1.1.0 - UC4 Agent version
What is a trap?
A trap is an asynchronous message which the UC4 Automation Engine sends to the UC4 SNMP
Subagent. Traps are not stored in the MIB but are directly forwarded to the Masteragent. This means that
the applications immediately obtain important information.
How can I send a trap?
In particular situations, the UC4 Automation Engine automatically sends predefined traps. You can also
send individual traps using the script statement :SEND_SNMP_TRAP.
Are traps stored in the MIB table?
Traps are immediately forwarded to the Masteragent. There is no need to store them in the MIB.
What can be the reason for lost traps?
There can be various causes:
l
l
l
Check the value specified in the UC4 SNMP Subagents INI-file parameter processing=. Value "1"
has the effect that no traps are sent to the Masteragent.
The computer on which the Masteragent runs must be the trap destination. Under Windows, the
computer name must be specified in the Windows SNMP service. Under UNIX, it must be
specified in the file snmpd.conf or ucsnmp1.conf.
The community name specified in the UC4 Subagent's INI-file parameter community= must
comply with the community specified in the Masteragent.
What is Net SNMP?
Net SNMP is an open source SNMP Server under UNIX.
Which SNMP versions does the UC4 SNMP Subagent support?
UNIX: SNMP V1, SNMP V2c and SNMP V3
Windows: SNMP V1 and SNMP V2c
Is it possible to install the UC4 SNMP Subagent subsequently?
Yes, refer to the corresponding installation guides (UNIX or Windows); they also describe the required
steps for subsequent installation.
How can I test that the UC4 SNMP Subagent installation was successful?
Use the SNMP Tool which is included in the supplied CD, directory Tools\no_supp in the file
snmptools.zip. It can be used to read the MIB, receive or send traps etc.
Note that the SNMP Tool is not supported.
Automation Engine
137
Why does the UC4 SNMP Subagent ignore Masteragent queries?
Possible reasons are:
l
l
The UC4 SNMP Subagent has not been started or the SNMP service is not active.
The community name specified in the UC4 SNMP Subagent's INI-file parameter community= must
comply with the community specified in the Masteragent.
Why is the MIB table incomplete?
The MIB's tree structure is dynamically created. If there are no blocked tasks or active Notifications, the
UC4 SNMP Subagent does not create structures for these areas.
Only the Agent Data Group and the Agent Work Group are created and filled with values if the UC4
Automation Engine is inactive.
What SNMP Server configurations are required (Net SNMP, Windows SNMP service or
Masteragent mode)?
l
l
l
l
l
Enter a community name.
This community must at least have a reading right.
Specify a destination for the traps (host name or IP address).
Ensure that the network grants access to the UDP port 161.
Access to the UDP port must also be granted if you want to receive traps.
What is a community name?
A community name is a group to which you can assign access rights. The default community name is
"public".
How can SNMP be used to monitor Jobs?
UC4 does not support a direct connection of Jobs to SNMP, but the script statement :SEND_SNMP_
TRAP can be used to monitor Jobs.
Example:
:SET
:SET
:SET
:SET
:SET
&NAME# = SYS_ACT_ME_NAME()
&ID# = SYS_ACT_ME_NR()
&JPNAME# = SYS_ACT_PARENT_NAME()
&CLIENT# = SYS_ACT_CLIENT()
&STATUS# = GET_UC_OBJECT_STATUS()
:IF &STATUS# < "1900"
: PRINT &STATUS#
: PRINT "Client: &CLIENT#, JOBNAME: &NAME#"
: PRINT &NAME#
: SEND_SNMP_TRAP 801450, "&CLIENT#", "&NAME#",, "Problems in processing!"
:ENIDF
The script function GET_UC_OBJECT_STATUS can be used to find out the Job's end status and react to
it accordingly. This solution can be implemented in the direct form of a script or in a reusable form as an
Include object.
See also:
UC4 and SNMP
138
Chapter 5 SNMP Support
5.5 Installation
5.5.1 Installing the UC4 SNMP Subagent (UNIX)
The following document guides you through the UNIX installation for UC4 SNMP Subagent.
Note that the UC4 SNMP Subagent must be installed on a computer on which at least one of the UC4
Automation Engine's work processes is available.
Requirements
l
l
The UC4 SNMP Subagent and Net SNMP must have been installed and activated on the UC4
Automation Engine computer.
Exception: HP UX. The UC4 SNMP Subagent must operate as SNMP Masteragent in order to use
EMANATEvia naaagt. (naaagt configuration http://docs.hp.com/en/B2355-90692/naaagt.1M.html)
Supplied files
The UC4 SNMP-Subagent files are stored in the appropriate platform's subfolder in CD:SNMP\UNIX.
File name
Description
ucsnmp1
UC4 SNMP Subagent.
ucsnmp1.ini
INI file of the UC4 SNMP Subagent.
UC4Vers2-MIB.mib
MIB description.
ucsnmp1.conf
Masteragent mode configuration file.
naaacnf
Configuration file for the naaagt interface (only HP UX).
Installation
1.
l
l
Unpack the UC4 SNMP Subagent's TAR file.
Copy the unpacked files to any directory of your choice or to the UC4 Automation Engine's folder.
2.
l
l
l
Installation of files
Configuration of INI files
Activate the SNMP connection in the UC4 Automation Engine's INI file UCSRV.INI using the
parameter snmp=1 (section [GLOBAL]). Also set the parameters snmp= and snmpreconnect=
(section [TCP/IP].
End and restart the UC4 Automation Engine's communication and work processes on all
computers. No restart is necessary if the UC4 Automation Engine's INI file is already adjusted.
Adjust the relevant parameters in the UC4 SNMP Subagent's INI file.
Automation Engine
3.
l
l
l
l
l
l
Masteragent mode
On HP UX, it is essential to specify Masteragent mode. On all other platforms, you can select
whether the UC4 SNMP Subagent should run as Masteragent.
Set the Masteragent mode in the UC4 SNMP Subagent's INI file using the parameter role=1.
Adjust the supplied configuration files naacnf and ucsnmp1.conf.
The variable SNMPCONFPATH must be set. It contains the directory with the file ucsnmp1.conf
(such as export SNMPCONFPATH=./).
It is not required to set the environment variables MIB and MIBDIR.
4.
l
139
Starting the UC4 SNMP Subagent
Start the UC4 SNMP Subagent and specify the INI file.
Note that the SNMP Subagent must start under the root user because otherwise the Automation
Engine cannot establish a connection.
For example:
./ucsnmp1 -i /home/UC4/Server/ucsnmp1.ini &
The following start parameters are available:
Start parameters
Description
-i INI-file path and
name
Path and name of the INI file to be used.
-h
Shows available parameters and usage.
-v
Shows the UC4 SNMP Subagent's version.
-crtini INI-file path
and name
Generates a standard INI file.
By default, the INI file is searched in the folder in which the
UC4 SNMP Subagent is stored.
By default, the INI file is searched in the folder in which the
UC4 SNMP Subagent is stored.
The order in which you start the UC4 Automation Engine and the SNMP Subagent is irrelevant. Note the
following: l
l
l
l
If the UC4 SNMP Subagent starts first, the UC4 Automation Engine can immediately connect to
the SNMP Subagent when it boots.
If the UC4 Automation Engine already runs with an active SNMP connection (UCSRV.INI), it
attempts to contact the SNMP Subagents in regular intervals (snmpreconnect=). The SNMP
service can be restarted subsequently even if the Automation Engine is running.
Note that traps and all SNMP events can only be sent to the SNMP Subagent when the SNMP
connection is active. All Events that should have been sent before the reconnection took place are
lost.
You can set the time interval for the reconnection in the Automation Engine's INI file using the
parameter snmpreconnect= (default value: 500 seconds).
Messages are output when the SNMP Agent starts. These messages are warnings and do not affect
the system's functionality (as opposed to error messages). The following message is always output
and can be ignored: "No log handling enabled - turning on stderr logging"
140
Chapter 5 SNMP Support
5.5.2 UC4 SNMP Subagent for UNIX
Structure of the file ucsnmp1.ini
Section/Parameter
Description
[SNMP]
community=
SNMP community name.
Default value: "public" The name is defined in the Masteragent. Enter the same community name in this
parameter. The community-name setting is found in the file snmp.con or
ucsnmp1.conf if the UC4 SNMP Subagent is used as Masteragent (see:
Installation Guide).
medium=
Means of transport that should be used for the communication between UC4
Automation Engine and UC4 SNMP Subagent. Possible value: "tcp" (default value), "pipe"
"tcp" - Communication via socket
"pipe" - Communication via pipe (downward compatibility of the SNMP
subagents: setting is only valid for UC4 systems of versions 5.00A and 6.00A).
stream_port=
Port number that the UC4 Automation Engine uses in order to connect to the
UC4 SNMP Subagent.
Note that the same port number must be specified in the UC4 Automation
Engine's INI-file parameter snmp= (section [TCP/IP]).
snmp_string=
If role=0 has been specified, you can specify the path to the AgentX socket for
Net-SNMP here.
processing=
Mode of the UC4 SNMP Subagent.
Allowed value: "1", "2" and "3" (default value)
"1" - The MIB is loaded but traps are not sent.
"2" - The MIB is not filled, traps are sent.
"3" - The MIB is loaded and traps are sent.
role=
Role of the UC4 SNMP Subagent
Allowed value: "0" (default value) and "1"
"0" - The UC4 SNMP Subagent starts as Subagent.
"1" - The UC4 SNMP Subagent starts as Masteragent. In Masteragent mode, no
other Subagent can establish a connection to it.
Note that on HP UX, the Masteragent mode is essential in order to establish
a connection to EMANATE via naaagent.
[LOG]
Automation Engine
141
Section/Parameter
Description
snmp=
Trace flag for the output of trace messages from the module that reads data from
the MIB table and sends it to the network.
Allowed values: "0" to "9"
Default value: "1"
Trace flags must only be used in close cooperation with UC4 Support.
stream=
Trace flag for the output of trace messages from the module that receives
information from the UC4 Automation Engine and stores it in the MIB table.
Allowed values: "0" to "9"
Default value: "1"
Trace flags must only be used in close cooperation with UC4 Support.
mib=
Trace flag for the output of trace messages from the module that administers the
MIB table.
Allowed values: "0" to "9"
Default value: "1"
Trace flags must only be used in close cooperation with UC4 Support.
file=
Path and name of the log file.
The number signs serve as placeholders for a series in numerical order. When
you start the UC4 SNMP Subagent, the log files are renamed so that the most
current log file is always the one with the number "00".
By default, the log file is stored in the folder from which the UC4 SNMP
Subagent starts. INI-file example
[SNMP]
community=public
medium=tcp
stream_port=2200
snmp_string=/var/agentx/master
processing=3
role=0
lib_path=.
[LOG]
snmp=1
stream=1
mib=1
file=ucsnmp_##.log
See also:
Notes for Configuration-File Adjustments
142
Chapter 5 SNMP Support
5.5.3 Installing the UC4 SNMP Subagent (Windows)
The following document guides you through the Windows installation for UC4 SNMP Subagent.
Requirements
l
l
The UC4 SNMP Subagent and the Windows SNMP service must be installed and activated on the
UC4 Automation Engine computer.
Install Windows Patch KB950923 if you cannot start the UC4 SNMP Subagent on Windows
Vista or Windows Server 2008 and the Windows Event log shows the error message "SNMP
Extension Agent has terminated. Event 2020, EvntAgnt".
Supplied Files
The UC4 SNMP-Subagent files are stored in the particular platform's subfolder on
CD:SNMP\WINDOWS.
File name
Description
UCSNMP1.DLL
UC4 SNMP Subagent
UCSNMP1.INI
INI file of the UC4 SNMP Subagent
UC4VERS2-MIB.MIB
MIB description
Installation
You can set up the UC4 SNMP Subagent when you install the UC4 Automation Engine or subsequently.
1.
l
l
Installation of files
Start the UC4 SNMP Subagent's setup program or instead, you can also copy the library
UCSNMP1.DLL and the INI file UCSNMP1.INI manually to the directory %WINDIR%\System32.
Register the library in the registry database as follows:
[HKEY_LOCAL_MACHINE\SOFTWARE\UC4\SnmpAgent\Vers1]
"Pathname"="UCSnmp1.dll"
[HKEY_LOCAL_
MACHINE\SYSTEM\CurrentControlSet\Services\SNMP\Parameters\ExtensionAgents]
"10"="SOFTWARE\\UC4\\SnmpAgent\\Vers1"
2.
l
Configuration of INI files
Activate the SNMP connection in the UC4 Automation Engine's INI file UCSRV.INI using the
parameter snmp=1 (section [GLOBAL]) . Also set the parameters snmp= and snmpreconnect=
(section [TCP/IP] ).
Automation Engine
l
l
l
l
End and restart theUC4 Automation Engine's communication and work processes on all
computers. No restart is necessary if the UC4 Automation Engine's INI file is already adjusted.
Configure the Windows SNMP service.
Adjust the relevant parameters in the UC4 SNMP Subagent's INI file.
The UC4 SNMP Subagent uses the path that is specified in the Windows system environment
variable UC_SNMP_INI in order to access the INI file. If this variable is not available, the Subagent
searches it in the directory in which the UC4 SNMP Subagent is installed. If the INI file is not
available here, the Subagent uses the default values.
3.
l
143
Starting the UC4 SNMP Subagent
Restart the Windows SNMP service. It automatically starts the UC4 SNMP Subagent.
The order in which you start the UC4 AutomationEngine and the SNMP Subagent is irrelevant.
Please note the following: l
l
l
l
When the UC4 SNMP Subagent starts first, the UC4 Automation Engine can immediately connect
to the SNMP Subagent when it boots.
When the UC4 Automation Engine already runs with an active SNMP connection (UCSRV.INI), it
attempts to contact the SNMP Subagents in regular intervals (snmpreconnect=). You can restart
the SNMP service subsequently even when the Automation Engine is running.
Note that the SNMP connection needs to be active to send traps and SNMP events to the SNMP
Subagent. All Events that should have been sent before the reconnection took place are lost.
You can set the time interval for the reconnection in the Automation Engine's INI file by using the
parameter snmpreconnect= (default value: 500 seconds).
The Masteragent (Windows service) is decisive for the SNMP-trap version.
5.5.4 UC4 SNMP Subagent for Windows
Structure of the file ucsnmp1.ini
Section/Parameter
Description
[SNMP]
community=
SNMP community name.
Default value: "public"
The name is defined in the Masteragent. Enter the same community name in
this parameter. The community-name setting is found in the SNMP service's
properties.
medium=
Means of transport that should be used for the communication between UC4
Automation Engine and UC4 SNMP Subagent.
Possible value: "tcp" (default value), "pipe"
"tcp" - Communication via socket.
"pipe" - Communication via pipe (downward compatibility of the SNMP
subagents: setting is only valid for UC4 systems of versions 5.00A and
6.00A).
144
Chapter 5 SNMP Support
Section/Parameter
Description
stream_port=
Port number that the UC4 Automation Engine uses in order to connect to the
UC4 SNMP Subagent.
Note that the same port number must be specified in the UC4
Automation Engine's INI-file parameter snmp= (section [TCP/IP]).
processing=
Mode of the UC4 SNMP Subagent.
Allowed value: "1", "2" and "3" (default value)
"1" - The MIB is loaded but traps are not sent.
"2" - The MIB is not filled, traps are sent.
"3" - The MIB is loaded and traps are sent.
[LOG]
snmp=
Trace flag for the output of trace messages from the module that reads data
from the MIB table and sends it to the network.
Allowed values: "0" to "9"
Default value: "1"
Trace flags must only be used in close cooperation with UC4 Support.
stream=
Trace flag for the output of trace messages from the module that receives
the information from the UC4 Automation Engine and stores it in the MIB
table.
Allowed values: "0" to "9"
Default value: "1"
Trace flags must only be used in close cooperation with UC4 Support.
mib=
Trace flag for the output of trace messages from the module that administers
the MIB table.
Allowed values: "0" to "9"
Default value: "1"
Trace flags must only be used in close cooperation with UC4 Support.
file=
Path and name of the log file
The number signs serve as placeholders for a series in numerical order.
When you start the UC4 SNMP Subagent, the log files are renamed so that
the most current log file is always the one with the number "00".
By default, the log file is stored in the folder from which the UC4 SNMP
Subagent starts.
Automation Engine
145
INI-file example
[SNMP]
community=public
medium=tcp
stream_port=2200
processing=3
[LOG]
stream=1
snmp=1
mib=1
file=ucsnmp_##.log
See also:
Notes for Configuration-File Adjustments
5.5.5 Windows SNMP Service Configuration
The following document describes the Windows SNMP Service configuration procedure.
Requirement
l
The Windows SNMP Service must have been installed.
Procedure
l
l
Open the properties of the Windows SNMP Service.
Switch to the Traps tab. Enter a community name and specify the computer on which the SNMP
Management has been installed.
146
Chapter 5 SNMP Support
l
Switch to the Security tab. Add the community name including a reading right.
Automation Engine
147
See also:
Installing the UC4 SNMP Subagent (Windows)
5.6 MIB
5.6.1 Structure of the MIB
The registered branch of the MIB subtree for UC4 and its product UC4 is 1.3.6.1.4.1.2562.1.1 =
iso.org.dod.internet.private.enterprises.sbb.uc4.vers1. This address is the root of the UC4 subtree.
148
Chapter 5 SNMP Support
The MIB ID's - which identify the information for UC4 - are specified in a "relative" form. The MIB ID 3.10.0
stands for the complete address 1.3.6.1.4.1.2562.1.1.3.10.0.
The UC4 subtree in the MIB includes several functional groups.
MIB ID
Description
1
Agent Data Group
2
Agent Control Group
3
Agent Work Group
4
System Group
5
Client Group
6
Server Group
7
Agent Group
8
Blocking Points Group
9
Notification Group
Some UC4 terms have been renamed starting with UC4 version 8.00A. This modification does not
appliy to the terms used in the MIB in order to avoid possible incompatibilities.
5.6.2 Agent Data Group
MIB ID
1
Indicator
Agent Data Group
Generated/Removed
This is a permanent group. Belongs to
UC4 SNMP Subagent
Description
This group serves as a description of the UC4 SNMP Subagent
MIB ID
1.1.0
Indicator
agentVersion
Type
DisplayString (SIZE (0..5))
Description
Version of UC4 SNMP Subagent.
MIB ID
1.2.0
Indicator
agentStartTime
Type
DisplayString (SIZE (0..30))
Description
Start time of the UC4 SNMP Subagent in the format "YYYYMMDD HHMMSS".
MIB ID
1.3.0
Automation Engine
Indicator
agentNumberOfServerTasks
Type
INTEGER
Description
Current number of active Server processes.
MIB ID
1.4.0
Indicator
agentConnectCounter
Type
Counter
Description Number of Server processes which already have a connection to the SNMP Subagent
(historical value).
5.6.3 Agent Control Group
MIB ID
2
Indicator
Agent Control Group
Not used at this time.
5.6.4 Agent Work Group
An Agent Work Group does not refer to Agents but to the UC4 SNMP Subagent.
MIB ID
3
Indicator
Agent Work Group
Generated/Removed This is a permanent group. Belongs to
UC4 System, indicated by agentWorkSysID.
Description
This group serves as the work area for generating SNMP traps. It contains the
values of the most recently generated traps.
MIB ID
3.1.0
Indicator
agentWorkSysID
Type
DisplayString (SIZE (0..8))
Description
Working variable for generating traps (internal subagent).
MIB ID
3.2.0
Indicator
agentWorkObject
Type
DisplayString (SIZE (0..255))
Description
Working variable for generating traps (internal subagent).
149
150
Chapter 5 SNMP Support
MIB ID
3.3.0
Indicator
agentWorkString1
Type
DisplayString (SIZE (0..255))
Description
Working variable for generating traps (internal subagent).
MIB ID
3.4.0
Indicator
agentWorkString2
Type
DisplayString (SIZE (0..255))
Description
Working variable for generating traps (internal subagent).
MIB ID
3.5.0
Indicator
agentWorkString3
Type
DisplayString (SIZE (0..255))
Description
Working variable for generating traps (internal subagent).
MIB ID
3.6.0
Indicator
agentWorkString4
Type
DisplayString (SIZE (0..255))
Description
Working variable for generating traps (internal subagent).
MIB ID
3.7.0
Indicator
agentWorkString5
Type
DisplayString (SIZE (0..255))
Description
Working variable for generating traps (internal subagent).
MIB ID
3.8.0
Indicator
agentWorkInteger1
Type
INTEGER
Description
Working variable for generating traps (internal subagent).
MIB ID
3.9.0
Indicator
agentWorkInteger2
Type
INTEGER
Automation Engine
Description
Working variable for generating traps (internal subagent).
MIB ID
3.10.0
Indicator
agentWorkInteger3
Type
INTEGER
Description
Working variable for generating traps (internal subagent).
MIB ID
3.11.0
Indicator
agentWorkInteger4
Type
INTEGER
Description
Working variable for generating traps (internal subagent).
MIB ID
3.12.0
Indicator
agentWorkInteger5
Type
INTEGER
Description
Working variable for generating traps (internal subagent).
5.6.5 System Group
MIB ID
4
Indicator
System Group
Generated/Removed The UC4 System starts when the first Server process of this system starts.
The UC4 System remains in the MIB until the SNMP Subagent gets reloaded
even if all Server processes are inactive.
Belongs to
UC4 SNMP Subagent
Description
This group contains the description of the UC4 Systems. There is an entry for
each UC4 System in the following table.
MIB ID
4.1
Indicator
systemTable
Type
SEQUENCE OF SystemEntry
Index
(sysSysID)
Description
This table contains all active UC4 Systems.
151
152
Chapter 5 SNMP Support
MIB ID
4.1.1
Indicator
systemEntry
Type
SystemEntry
Generated/Removed Contains all connected UC4 Systems as long as the SNMP Subagent is active
on this computer.
MIB ID
4.1.1.1
Indicator
sysSysID
Type
DisplayString (SIZE (0..8))
Description
Name of the UC4 System.
Value of the parameter "System=" from the INI file of the UC4 Automation Engine.
MIB ID
4.1.1.2
Indicator
sysStartTime
Type
DisplayString (SIZE (0..19))
Description
Starting time of the first Server process of this system.
MIB ID
4.1.1.3
Indicator
sysDbmsName
Type
DisplayString (SIZE (0..30))
Description
Product name of the UC4 database (Oracle 7, Microsoft SQL Server 7 etc.).
MIB ID
4.1.1.4
Indicator
sysDbVersion
Type
DisplayString (SIZE (0..30))
Description
Version of the UC4 database.
MIB ID
4.1.1.5
Indicator
sysDbName
Type
DisplayString (SIZE (0..30))
Description
Name of the database which is provided with the supplied software package.
MIB ID
4.1.1.6
Indicator
sysEMS
Type
INTEGER
Automation Engine
Contents
1 = BMC Patrol
2 = HP NNM
3 = BMC Patrol + HP NNM
4 = Tivoli
5 = BMC Patrol + Tivoli
6 = BMC Patrol + HP NNM
7 = all
Description
A bit-vector to show the available licenses.
153
5.6.6 Client Group
MIB ID
5
Indicator
Client Group
Description This group contains the description of clients in all UC4 Systems. There is an entry for
each client of an existing system in the following table. MIB ID
5.1
Indicator
clientTable
Type
SEQUENCE OF ClientEntry
Index
(cliSysID, cliClient)
Description
This table contains all existing clients.
MIB ID
5.1.1
Indicator
clientEntry
Type
ClientEntry
Generated/Removed When a UC4 Server starts, a table entry for each client is created. If a client
should be added or deleted or if the status of a client changes (cliState), the table
is deleted and recreated with the existing client.
Belongs to
UC4 System cliSysID
MIB ID
5.1.1.1
Indicator
cliSysID
Type
DisplayString (SIZE (0..8))
Description
Name of the UC4 System to which the client belongs.
MIB ID
5.1.1.2
154
Chapter 5 SNMP Support
Indicator
cliClient
Type
INTEGER (0..9999)
Description
Number of the client.
MIB ID
5.1.1.3
Indicator
cliLastModifyTime
Type
DisplayString (SIZE (0..19))
Description
Time of the last update of this table entry.
MIB ID
5.1.1.4
Indicator
cliState
Type
INTEGER {run(1), stop(2)}
Contents
1 = active
2 = stopped
Description Indicates whether the automatic processing of tasks is active (system status GO) or has
been stopped (system status STOP).
MIB ID
5.1.1.5
Indicator
cliMonitoring
Type
INTEGER {yes(1), no(2)}
Contents
1 = Monitoring of a client's activities
2 = No monitoring of the client's activities
Description Indicates whether the client's activities are being monitored. For an active client, all
Notifications and blocked Workflows are monitored in this way. MIB ID
5.1.1.6
Indicator
cliInfo
Type
DisplayString
Is not currently used.
5.6.7 Server Group
MIB ID
6
Indicator
Server Group
Generated/Removed There is an entry for each Server process in an existing UC4 System in the
following table. Stopped Server processes (Status = STOPPED) remain in the
MIB until the SNMP Subagent is reloaded onto the computer.
Description
This group contains the description of the Server process in all UC4 Systems.
Automation Engine
MIB ID
6.1
Indicator
serverInstanceTable
Type
SEQUENCE OF serverInstancEntry
Index
(srvSysID, srvName)
Description
This table contains all existing Server processes.
MIB ID
6.1.1
Indicator
serverInstanceEntry
Type
ServerInstanceEntry
Generated/Removed Starts a Server process - a table entry is created for this. The entry will then no
longer be deleted.
Belongs to
UC4 System coSysID and client coClient.
MIB ID
6.1.1.1
Indicator
srvSysID
Type
DisplayString (SIZE (0..8))
Description
Name of the UC4 System to which the Server process belongs.
Value of the parameter "system=" from the INI file of the UC4 Server.
MIB ID
6.1.1.2
Indicator
srvName
Type
DisplayString (SIZE (0..8))
Description
Name of the primary work process.
MIB ID
6.1.1.3
Indicator
srvLastModifyTime
Type
DisplayString (SIZE (0..19))
Description
Time of the last update of this table entry.
MIB ID
6.1.1.4
Indicator
srvVersion
Type
DisplayString (SIZE (0..5))
Description
Version of the UC4 Automation Engine.
155
156
Chapter 5 SNMP Support
MIB ID
6.1.1.5
Indicator
srvStartTime
Type
DisplayString (SIZE (0..19))
Description
Start time of the Server process.
MIB ID
6.1.1.6
Indicator
srvState
Type
INTEGER {run(1), ended(2), abnormal(3)}
Contents
1 = running
2 = Ended normally
3 = Canceled or no connection to the SNMP Subagent
Description
Status of the Server process.
MIB ID
6.1.1.7
Indicator
srvSrvConnect
Type
INTEGER
Description Number of Server processes which are connected to this Server process (Entries are only
available at the primary Server process).
MIB ID
6.1.1.8
Indicator
srvExeConnect
Type
INTEGER
Description Number of Agents which are connected to the Server process (Entries are only available
at the primary Server process).
MIB ID
6.1.1.9
Indicator
srvDiaConnect
Type
INTEGER
Description Number of UserInterfaces are connected to the Server process (Entries are only available
at the primary Server process).
MIB ID
6.1.1.10
Indicator
srvBusyMin
Type
INTEGER (0..100)
Description Average workload (in percent) of the Server process within the last minute before the
updating (statistical value).
Automation Engine
MIB ID
6.1.1.11
Indicator
srvBusy10Min
Type
INTEGER (0..100)
157
Description Average workload (in percent) of the Server process within the last ten minutes before the
updating (statistical value).
MIB ID
6.1.1.12
Indicator
SrvBusyHour
Type
INTEGER (0..100)
Description Average workload (in percent) of the Server within the last hour before the updating
(statistical value).
MIB ID
6.1.1.13
Indicator
SrvRunMode
Type
INTEGER {primary(1), normal(3), cp(4)}
Contents
1 = Primary work process
3 = Work process
4 = Communication process Description
Indicates the run mode of the Server process.
MIB ID
6.1.1.14
Indicator
SrvDBState
Type
INTEGER {online(1), offline(2)}
Contents
1 = UC4 Automation Engine is connected to the UC4 database
2 = UC4 Automation Engine is not connected to the UC4 database
Description
Indicates if the UC4 Automation Engine has a connection to the UC4 database.
MIB ID
6.1.1.15
Indicator
SrvSDBState
Type
INTEGER (1)
Contents
1 = SDB working correctly
Description
Gives information on the availability of the status database (SDB).
5.6.8 Agent Group
MIB ID
7
Indicator
Agent Group
158
Chapter 5 SNMP Support
Generated/removed There is an entry in the following table for each Agent in a UC4 System. If there is
more than one server within the system, the entries of the Agents for each of
these Server processes are completed in this way.
Description
This group contains the description of the Agents in all UC4 Systems.
MIB ID
7.1
Indicator
exekutorTable
Type
SEQUENCE OF exekutorEntry
Index
(exeSysID, exeSrvName, exeName, exeType)
Description
This table contains all Agents.
MIB ID
7.1.1
Indicator
exekutorEntry
Type
ExekutorEntry
Generated/Removed Starts a Server process - a table entry is created for each Agent known to the
system. If Agents are added or removed, or if their status changes (exeState),
the table is completely deleted and recreated for every existing Agent in the
system.
Belongs to
UC4 System exeSysID and UC4 Server exeSrvName.
MIB ID
7.1.1.1
Indicator
exeSysID
Type
DisplayString (SIZE (0..8))
Description
Name of the UC4 System to which the Agent has established a connection.
Value of the parameter "system=" from the INI file of the UC4 Server.
MIB ID
7.1.1.2
Indicator
exeSrvName
Type
DisplayString (SIZE (0..8))
Description
Name of the primary work process with which the Agent is connected.
MIB ID
7.1.1.3
Indicator
exeName
Type
DisplayString (SIZE (0..8))
Automation Engine
Description
Name of the Agent.
Value of the parameter "name=" from the INI file of the Agent.
MIB ID
7.1.1.4
Indicator
exeType
Type
DisplayString (SIZE (0..8))
Description
Type of Agent (EX_JOB).
MIB ID
7.1.1.5
Indicator
exeLastModifyTime
Type
DisplayString (SIZE (0..19))
Description
Time of the last update of this table entry.
MIB ID
7.1.1.6
Indicator
exeHost
Type
DisplayString (SIZE (0..8))
Description
Name of the Agent.
Value of the parameter "name=" from the INI file of the Agent.
MIB ID
7.1.1.7
Indicator
exeVersion
Type
DisplayString (SIZE (0..5))
Description
Version of the Agent.
MIB ID
7.1.1.8
Indicator
exeHardware
Type
DisplayString (SIZE (0..20))
Description
CPU type which the Agent determines from the system environment variables.
MIB ID
7.1.1.9
Indicator
exeSoftware
Type
DisplayString (SIZE (0..20))
Description
Operating system which the Agent determines from the system environment variables.
159
160
Chapter 5 SNMP Support
MIB ID
7.1.1.10
Indicator
exeSoftwareVers
Type
DisplayString (SIZE (0..20))
Description Version of the operating system which the Agent determines from the system environment
variables.
MIB ID
7.1.1.11
Indicator
exeJCLTyp
Type
DisplayString (SIZE (0..8))
Description
Job Control Language (JCL) used for Job generation.
Value of the parameters "UC_HOST_JCL_VAR" from the INI file of the Agent.
MIB ID
7.1.1.12
Indicator
exeConnTime
Type
DisplayString (SIZE (0..19))
Description
Time of the Agent's last connection setup to the Server process.
MIB ID
7.1.1.13
Indicator
exeState
Type
INTEGER {run(1), ended(2), lost(3), timeout(4)}
Index
1 = Running
2 = Ended normally or not yet started
3 = Connection to the Server process canceled
4 = No answer despite existing connection
5 = Agent object was deleted
Description
Status of the Agent at the time of the last update.
MIB ID
7.1.1.14
Indicator
exeLastPing
Type
DisplayString (SIZE (0..19))
Description
Time of the last sign of life from the Agent.
MIB ID
7.1.1.15
Indicator
exeMonitoring
Type
INTEGER {yes(1), no(2)}
Index
1 = Availability of the Agents is monitored.
2 = Availability of the Agent is not monitored.
Automation Engine
161
Description Indicates if the availability of the Agent is being monitored. Monitoring of productive
Agents is important.
MIB ID
7.1.1.16
Indicator
exeInfo
Type
DisplayString
Description
Not currently used.
5.6.9 Blocking Points Group
MIB ID
8
Indicator
Blocking Point Group Generated/Removed There is an entry for each blocked task in the following table. The table entry
exists until the block is released or the Workflow is canceled.
Description
This group contains the description of all blocked tasks. The description contains
information on the task which caused the block as well as information on the
Workflow which has been consequently blocked.
MIB ID
8.1
Indicator
blockingPointsTable
Type
SEQUENCE OF blockingPointEntry
Index
(blkSysID, blkClient, blkJPRunNr, blkJPLNR)
Description
This table contains all blocked tasks in the UC4 System.
MIB ID
8.1.1
Indicator
blockingPointEntry
Type
BlockingPointEntry
Generated/Removed The entry is created if a task blocks and stays supported until the task continues
or is canceled.
Description
UC4 System in blkSysID
MIB ID
8.1.1.1
Indicator
blkSysID
Type
DisplayString (SIZE (0..8))
Description
Name of the UC4 System in which the blocking occurs.
162
Chapter 5 SNMP Support
MIB ID
8.1.1.2
Indicator
blkClient
Type
INTEGER (0..9999)
Description
Number of the client in which the blocking occurs.
MIB ID
8.1.1.3
Indicator
blkJPRunNr
Type
INTEGER
Description
RunID of the Workflow in which the blocking occurs.
MIB ID
8.1.1.4
Indicator
blkJPLNR
Type
INTEGER
Description
Number of line in which the blocked task is found within the Workflow.
MIB ID
8.1.1.5
Indicator
blkLastModifyTime
Type
DisplayString (SIZE (0..19))
Description
Time of the last update of this table entry.
MIB ID
8.1.1.6
Indicator
blkJPName
Type
DisplayString (SIZE (0..200))
Description
Name of the blocked Workflow.
MIB ID
8.1.1.7
Indicator
blkObjTyp
Type
DisplayString (SIZE (0..8))
Description
Object type of the task which triggered the block.
MIB ID
8.1.1.8
Indicator
blkObjName
Type
DisplayString (SIZE (0..200))
Description
Name of the task which triggered the block.
Automation Engine
MIB ID
8.1.1.9
Indicator
blkObjRunNr
Type
INTEGER
Description
RunID of the task which triggered the blocking.
5.6.10 Notification Group
MIB ID
9
Indicator
Notification Group
Generated/Removed
The table entry exists until the Notification has been acknowledged.
Description
This table contains all active Notifications.
MIB ID
9.1
Indicator
NotificationTable
Type
SEQUENCE OF NotificationEntry
Index
(coSysID, coClient, coRunNr)
Description
This table contains all active Notifications.
MIB ID
9.1.1
Indicator
NotificationEntry Type
NotificationEntry
Generated/Removed
When UC4 sends a Notification trap, an entry is created.
If the status of the Notification changes, the entry is updated.
The entry is removed if the Notification is acknowledged. Description
UC4 System coSysID and Client coClient.
MIB ID
9.1.1.1
Indicator
coSysID
Type
DisplayString (SIZE (0..8))
Description
Name of the UC4 System in which the Notification has been activated.
MIB ID
9.1.1.2
163
164
Chapter 5 SNMP Support
Indicator
coClient Type
INTEGER (0..99)
Description
Number of the client in which the Notification has been activated.
MIB ID
9.1.1.3
Indicator
coRunNr Type
INTEGER
Description
RunID of the Notification.
MIB ID
9.1.1.4
Indicator
coLastModifyTime Type
DisplayString (SIZE (0..19))
Description
Time of the last update of this table entry.
MIB ID
9.1.1.5
Indicator
coName Type
DisplayString (SIZE (0..200))
Description
Name of the Notification.
MIB ID
9.1.1.6
Indicator
coTyp Type
INTEGER {question(1), message(2), alarm(3)}
Contents
1 = Request
2 = Message
3 = Alert
Description
Type of Notification.
MIB ID
9.1.1.7
Indicator
coText Type
DisplayString (SIZE (0..255))
Description
Message text of the Notification.
MIB ID
9.1.1.8
Indicator
coState Type
INTEGER
Automation Engine
Contents
1542 = Calling - Calling the Notification
1556 = Escalated - Notification is escalated
1553 = Accepted - Call Operator accepted
Description
Current status of the Notification.
165
5.6.11 Generated SNMP Traps
SNMP Traps with fixed trap codes are generated by UC4 so that the management system actively informs
about status changes or special conditions of UC4. In addition to the Trap, the UC4 Server for Windows
can generate an event which is displayed in the application log of the Windows Event Viewer. This
requires the parameter snmp=2 to be set in the UC4 INI file. Overview of Traps
Trap Code
Description
3400
UC4 Server started
3401
UC4 Server terminated
3410
UC4 Server ended abnormally
3536
Serious error when accessing the UC4 database. Access no longer possible.
3538
Connection to the UC4 Database re-established
11603
Shutting down an Agent
11604
Cold start of an Agent
11622
Warm start of an Agent
11650
Connection to an Agent disconnected
11652
SAP Agent not longer connected to SAP system
11662
SAP Agent is reconnected to SAP system
11801
System error of the UC4 Server
11818
Primary server has changed
801450
Message of a Notification
xxxxxx
User-defined SNMP Traps
Description of Traps
The individual SNMP Traps and their parameters are described below.
Trap Code
3400
Description
UC4 Server started
AgentWorkSysID
Name of the UC4 System
AgentWorkObject
"Name of the UC4 System"."Name of the UC4 Server"
166
Chapter 5 SNMP Support
AgentWorkInteger1
Status of the UC4 Server:
1 = running
AgentWorkInteger2
Run mode of the UC4 Server:
1 = Primary
3 = Normal
4 = Communication process
Trap Code
3401
Description
End of a work of dialog process (regardless of the reason) or normal end of the
primary work process
AgentWorkSysID
Name of the UC4 System
AgentWorkObject
"Name of the UC4 System"."Name of the UC4 Server"
AgentWorkInteger1 Status of the UC4 Server:
2 = Ended normally
AgentWorkInteger2 Run mode of the UC4 Server:
1 = Primary
3 = Normal
4 = Communication process
Trap Code
3410
Description
Primary work process (PWP) ended abnormally
Note
In addition to the Trap, an event is always generated in the application log of the
Windows Event Viewer. This entry to the application log is even made when
snmp=2 has been defined.
AgentWorkSysID
Name of the UC4 System
AgentWorkObject
"Name of the UC4 System"."Name of the UC4 Server"
AgentWorkInteger1 Status of the UC4 Server:
2 = Signal for abnormal end received
3 = any other abnormal termination
AgentWorkInteger2 Run mode of the UC4 Server:
1 = Primary
3 = Normal
4 = Communication process
Trap Code
3536
Description
Serious error when accessing the UC4 database. Access no longer possible.
Note
This Trap is sent every 10 seconds until the database re-connects.
AgentWorkSysID
Name of the UC4 System
AgentWorkObject
"Name of the UC4 System"."Name of the UC4 Server"
AgentWorkString1
Error text of the ODBC driver
Automation Engine
Trap Code
3538
Description
Connection to UC4 database re-established
AgentWorkSysID
Name of the UC4 System
AgentWorkObject
"Name of the UC4 System"."Name of the UC4 Server"
Trap Code
11603
Description
Shutting down an Agent
AgentWorkSysID
Name of the UC4 System
AgentWorkObject
"Name of UC4 the System"."Name of the UC4 Server"."Name of the
Agent"."Type of the Agent"
AgentWorkString1
Name of the Agent
167
AgentWorkInteger1 Run mode of the UC4 Server:
1 = Primary
3 = Normal
4 = Communication process
Trap Code
11604
Description
Cold start of an Agent
AgentWorkSysID
Name of the UC4 System
AgentWorkObject
"Name of the UC4 System"."Name of the UC4 Server"."Name of the
Agent"."Type of the Agent"
AgentWorkString1
Name of the Agent
AgentWorkInteger1 Run mode of the UC4 Server:
1 = Primary
3 = Normal
4 = Communication process
Trap Code
11622
Description
Warm start of an Agent
AgentWorkSysID
Name of the UC4 System
AgentWorkObject
"Name of the UC4 System"."Name of UC4 the Server"."Name of the Agent"."Type
of the Agent"
AgentWorkString1 Name of the Agent
Trap-Code
11650
Description
Ends connection to an Agent
AgentWorkSysID
Name of the UC4 System
168
Chapter 5 SNMP Support
AgentWorkObject
"Name of the UC4 System"."Name of the UC4 Server"."Name of the
Agent"."Type of the Agent"
AgentWorkString1
Name of the Agent
AgentWorkInteger1 Run mode of the UC4 Server:
1 = Primary
3 = Normal
4 = Communication process
Trap-Code
11652
Description
SAP Agent not longer connected to SAP system
AgentWorkSysID
Name of the UC4 System
AgentWorkObject
"Name of the UC4 System"."Name of the UC4 Server"."Name of the
Agent"."Type of the Agent"
AgentWorkString1
Name of the Agent
AgentWorkInteger1 Run mode of the UC4 Server:
1 = Primary
3 = Normal
4 = Communication process
Trap-Code
11662
Description
SAP Agent reconnected to SAP system
AgentWorkSysID
Name of the UC4 System
AgentWorkObject
"Name of the UC4 System"."Name of the UC4 Server"."Name of the
Agent"."Type of the Agent"
AgentWorkString1
Name of the Agent
AgentWorkInteger1 Run mode of the UC4 Server:
1 = Primary
3 = Normal
4 = Communication process
Trap Code
11801
Description
System error of the UC4 Server
AgentWorkSysID
Name of the UC4 System
AgentWorkObject
"Name of UC4 System"."Name of the UC4 Server"."Name of the kernel function"
AgentWorkString1
Text of the error message
AgentWorkInteger1 Number of the error message
Trap-Code
11818
Description
Primary Server has changed
Automation Engine
Note
UC4 Version 3.01C and later
AgentWorkSysID
Name of the UC4 System
AgentWorkObject
"Name of UC4 System"."Name of the UC4 Server"
AgentWorkInteger1
Previous mode
AgentWorkInteger2
New mode
Trap Code
801450
Description
Message of a Notification
AgentWorkSysID
Name of the UC4 System
AgentWorkObject
"Name of the UC4 System"."Client"."RunID"
AgentWorkString1
Name of the Notification
AgentWorkString2
Message text of the Notification
AgentWorkInteger1
Status of the Notification (as in the message file UC.MSL):
1542 = Calling
1553 = Accepted
1556 = Escalated
1800 = ENDED_NOT_OK - Aborted
1850 = ENDED_CANCEL - Canceled.
1852 = Rejected
1856 = ENDED_ESCALATED - Aborted by Escalation.
1900 = ENDED_OK - Ended normally.
1901 = Confirmed
169
Aside from the SNMP Traps generated by the system, user-defined Traps can be generated with the script
statement :SEND_SNMP_TRAP. Trap codes generated by UC4 and the UC4.Connect for HP OpenView
NNM (Trap codes: 10000 - 10010) cannot be used as user-defined SNMP Traps!
Trap Code
xxxxxx
Description
User-defined SNMP Traps
AgentWorkSysID
Name of the UC4 System
AgentWorkObject
"Name of the UC4 System". "Name of the UC4 Server"
AgentWorkString1
User-defined
AgentWorkString2
User-defined
AgentWorkString3
User-defined
AgentWorkString4
User-defined
AgentWorkString5
User-defined
AgentWorkInteger1
User-defined
AgentWorkInteger2
User-defined
AgentWorkInteger3
User-defined
AgentWorkInteger4
User-defined
AgentWorkInteger5
User-defined
170
Chapter 5 SNMP Support
5.7 Net-SNMP License
Various copyrights apply to this package, listed in various separate parts below. Please make sure that
you read all the parts. Up until 2001, the project was based at UC Davis, and the first part covers all code
written during this time. From 2001 onwards, the project has been based at SourceForge, and Networks
Associates Technology, Inc hold the copyright on behalf of the wider Net-SNMP community, covering all
derivative work done since then. An additional copyright section has been added as Part 3 below also
under a BSD license for the work contributed by Cambridge Broadband Ltd. to the project since 2001. An
additional copyright section has been added as Part 4 below also under a BSD license for the work
contributed by Sun Microsystems, Inc. to the project since 2003.
Code has been contributed to this project by many people over the years it has been in development, and a
full list of contributors can be found in the README file under the THANKS section.
---- Part 1: CMU/UCD copyright notice: (BSD like) ----Copyright 1989, 1991, 1992 by Carnegie Mellon University
Derivative Work - 1996, 1998-2000
Copyright 1996, 1998-2000 The Regents of the University of California
All Rights Reserved
Permission to use, copy, modify and distribute this software and its documentation for any purpose and
without fee is hereby granted, provided that the above copyright notice appears in all copies and that both
that copyright notice and this permission notice appear in supporting documentation, and that the name of
CMU and The Regents of the University of California not be used in advertising or publicity pertaining to
distribution of the software without specific written permission.
CMU AND THE REGENTS OF THE UNIVERSITY OF CALIFORNIA DISCLAIM ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL CMU OR THE REGENTS OF THE
UNIVERSITY OF CALIFORNIA BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM THE LOSS OF USE, DATA OR
PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
SOFTWARE.
---- Part 2: Networks Associates Technology, Inc copyright notice (BSD) ----Copyright (c) 2001-2003, Networks Associates Technology, Inc
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that
the following conditions are met:
l
l
l
Redistributions of source code must retain the above copyright notice, this list of conditions and the
following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and
the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the Networks Associates Technology, Inc nor the names of its contributors can
be used to endorse or promote products derived from this software without specific prior written
permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
Automation Engine
171
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
---- Part 3: Cambridge Broadband Ltd. copyright notice (BSD) ----Portions of this code are copyright (c) 2001-2003, Cambridge Broadband Ltd.
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that
the following conditions are met:
l
l
l
Redistributions of source code must retain the above copyright notice, this list of conditions and the
following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and
the following disclaimer in the documentation and/or other materials provided with the distribution.
The name of Cambridge Broadband Ltd. cannot be used to endorse or promote products derived
from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
---- Part 4: Sun Microsystems, Inc. copyright notice (BSD) ----Copyright © 2003 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A.
All rights reserved.
Use is subject to license terms below.
This distribution can include materials developed by third parties.
Sun, Sun Microsystems, the Sun logo and Solaris are trademarks or registered trademarks of Sun
Microsystems, Inc. in the U.S. and other countries.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that
the following conditions are met:
l
l
l
Redistributions of source code must retain the above copyright notice, this list of conditions and the
following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and
the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the Sun Microsystems, Inc. nor the names of its contributors can be used to
endorse or promote products derived from this software without specific prior written permission.
172
Chapter 5 SNMP Support
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
---- Part 5: Sparta, Inc copyright notice (BSD) ----Copyright (c) 2003-2006, Sparta, Inc
All rights reserved
Redistribution and use in source and binary forms, with or without modification, are permitted provided that
the following conditions are met:
l
l
l
Redistributions of source code must retain the above copyright notice, this list of conditions and the
following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and
the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Sparta, Inc nor the names of its contributors can be used to endorse or promote
products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
---- Part 6: Cisco/BUPTNIC copyright notice (BSD) ----Copyright (c) 2004, Cisco, Inc and Information Network Center of Beijing University of Posts and
Telecommunications.
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that
the following conditions are met:
l
l
l
Redistributions of source code must retain the above copyright notice, this list of conditions and the
following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and
the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Cisco, Inc, Beijing University of Posts and Telecommunications, nor the
names of their contributors can be used to endorse or promote products derived from this software
without specific prior written permission.
Automation Engine
173
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
---- Part 7: Fabasoft R&D Software GmbH & Co KG copyright notice (BSD) ----Copyright (c) Fabasoft R&D Software GmbH & Co KG, 2003
oss@fabasoft.com
Author: Bernhard Penz
Redistribution and use in source and binary forms, with or without modification, are permitted provided that
the following conditions are met:
l
l
l
Redistributions of source code must retain the above copyright notice, this list of conditions and the
following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and
the following disclaimer in the documentation and/or other materials provided with the distribution.
The name of Fabasoft R&D Software GmbH & Co KG or any of its subsidiaries, brand or product
names cannot be used to endorse or promote products derived from this software without specific
prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
174
Chapter 6 UC4 and Target Systems
6 UC4 and Target Systems
6.1 UC4 and BS2000
6.1.1 BS2000 Text Archive
Initial Situation
It happens now and then that BS2000 files should be transported with other means than BS2000 data
carriers. Means such as disks, CDs and in particular the electronic transfer would be appropriate. Text
files (SAM, record length max. 255) can in the meantime easily be transported because a text-file transfer
is usually available between PC and BS2000 (in the worst case via EDP file transfer) in each BS2000
installation.
Nevertheless, transporting binary files (LMS libraries, programs etc.) is very problematic. FTP can be used
to transport programs in binary mode but unfortunately, they then consist of 2 additional PAM pages (they
function, though). LMS libraries such as ISAM files and the like cannot be transferred because the FCB is
not restored. Furthermore, FTP in BS2000 is liable to costs (TCP/IP-AP). This topic has become important
for UC4 because the BS2000 files are supplied on CD.
The Solution: BS2000 Text Archive
Integration into BS2 TOOLS
Starting with BS2 TOOLS Version 2.00W files can now be assumed to a text archive and text archives
unpacked.
l
Assuming any file (especially a binary file) to a text archive:
l
Action Code "C+" in front of the binary file
Select the target text archive using the K3 key.
Select "Overwrite=E" for enlarging the text archive (several files in a text archive).
This process can take a while when large files are concerned.
Unpacking a text archive:
Action Code "TAR" in front of a text archive generates the files in the own user ID.
Program BS2 TAR
This program unpacks a text archive to the own User ID. It is required for all transfers made in the form of
text archives.
No license is required for the program BS2 TAR (FREEWARE). It is supplied in the MUSTERLIB of all
existing systems. It can also be obtained from all Sales Partners.
The supplied TAR files whose names include "NK4" are for NK4 pubsets and can also be unpacked using
the program BS2 TAR.
Automation Engine
l
175
Unloading a text archive:
/FILE from file, LINK=TAR
/EXEC BS2-TAR
UC4 Installation CD
The program BS2 TAR can be obtained in two ways from the folder CD:TOOLS\BS2_TAR :
BS2-TAR.BIN
The file BS2-TAR.BIN contains the program BS2 TAR. This program was transferred via FTP in binary
mode and can also be re-transferred to BS2000 via FTP:
FTP
OPENBS2000 computer
user id (TSOS)
password
account
BIN
PUT BS2-TAR.BIN
BYE
In BS2000:
/CAT BS2-TAR.BIN,BS2-TAR,STATE=U,SHARE=YES,ACCESS=READ
BS2-TAR.TAR
The latest version of the program BS2 TAR in TAR format.
This version requires BS2 TAR already been installed on BS2000 computer.
The file is transferred to BS2000 in text mode using any file transfer and unpacked in BS2000 with BS2
TAR:
/FILE BS2-TAR.TAR,LINK=TAR
/EXEC BS2-TAR
6.1.2 UC4 Automation Engine/Agent - BCIN for Connection
Set Up
A TCP/IP connection of a BS2000 Agent with another component requires this component's IP address to
be known in the BS2000 Agent.
l
Communication between a UC4 Automation Engine and a BS2000 Agent is carried out via TCP/IP
connection.
Information and internal protocol are exchanged.
The IP address of the server computer be made known to the BS2000 with /BCIN!
l
If a file transfer is initiated to/from a BS2000 Agent, the participating Agents set up a TCP/IP
connection between each other.
BS2000 must recognize the file transfer of the BS2000 Agents.
Define the IP address of the Host (Computer of the file transfer partners) with /BCIN.
176
Chapter 6 UC4 and Target Systems
6.1.3 BS2000 Agent - FileTransfer Support
The BS2000 Agent supports all file transfer functions such as the transfers of text and binary files or file
transfers with wildcard characters.
File Attributes for Destination
When defining a FileTransfer object, you can also specify file attributes for the destination in the
FileTransfer tab. All file attributes which comply with the file command can be used. They are entered in a
separate text field. Several file attributes need to be separated with commas:
Text mode:
FCB=SAM,LINK=UCEXSAM,SPACE=(300,300)
Binary mode:
SPACE=(300,300),BLKSIZE=STD,BLKCTRL=NO,FCB=PAM
Specified attributes replace default values or are added to the command.
Specifying an attribute means that the default-file command in the Agent is overwritten. The
specification of SPACE= would result in a SAM file with RECFORM=FIX, for example. In this case,
the attribute RECFORM is also required if you use RECFORM=V.
The Siemens FT BS2000 can also be used to create ISAM files. Example:
FCB=ISAM,BLKCTRL=DATA,RECFORM=V,KEYPOS=5,KEYLEN=8
Example
RECSIZE=50,VOLUME=PRIVATE,SPACE=(100,100)
Library Elements As Source and Destination
Elements of LMS libraries (PLAM) can be a file transfer's source and destination.
l
l
l
Library elements can be transferred between two LMS libraries.
A library element can be transferred as a file to any destination system.
Text files can be transferred to an LMS library from any destination system.
The element should be specified in the following form:
*LIB(Library,Element(Version),Type)
The element version is optional. The highest version is read (source) or an element is written with version
"@" (target) if no version has been specified.
Examples
*LIB($RS.LMS.LIB,MY.ELEMENT,S)
*LIB($RS.LMS.LIB,MY.*,S)
Automation Engine
177
Keeping the original attributes
To assume the attributes of source files to destination files, use the option Keep original file attributes in
the FileTransfer tab. This setting is only considered if source and destination Agent are of a UC4 version
9.00A or later (newFileTransfer protocol). Source and destination platform must comply with each other.
The following file attributes can be preserved in BS2000 FileTransfers:
Attributes Catalog Macro
l
l
l
l
l
l
l
l
l
l
l
l
l
l
Attributes File Macro
ACCESS
ACLPROT
BACKUP
BASACL
CCS
DESTROY
EXDATE
GROUPAR
GUARDS
LARGE
OTHERAR
OWNERAR
RETPD
SHARE
l
l
l
l
l
l
l
l
l
l
BLKCTRL
BLKSIZE
DUPEKY
FCBTYPE
KEYLEN
KEYPOS
RECFORM
RECSIZE
RETPD
SPACE
Note that the FileTransfer must not include additional attributes for the destination file if this setting is
used. Otherwise, an error will occur.
Limitations to FileTransfers with PAM Files
Keep the following limitations in mind:
l
l
The BS2000 Agent sends the file: If the PAM file is available in Non-Key (NK) format without an end
being marked, the last page is ignored and the file is read to the file size.
The BS2000 Agent receives the file: When writing a PAM file, an end marker (additional logical
block) is attached. This block can occasionally disturb (in particular cases even destroy) file
structures.
6.1.4 Utility for RFC Tasks
The supplied files for the BS2000 Agent include the utility UCYBRFC? for RFC tasks.
The INI file of the Agent contains the section "[RFC]" with the parameter "LOGON". If this parameter is set
to "1", the Agent generates a batch job with the specified User ID when executing a file transfer with a
specified User ID. In this batch job, the service program UCYBRFC? is called. It connects to TCP/IP via
the port that has been defined in the section [RFC] with the parameter "PORT". This connection enables
the Agent to check the specified user's access rights for the particular file. As this method causes a
performance loss for the Agent, the RFC tasks are kept available for further file transfers. Only if an RFC
task has received no queries for a specified period of time (parameter TIMEOUT=), it ends automatically.
When the Agent ends, all the corresponding RFC tasks end as well.
The file UCYBRFC? must be shareable when the RFC mechanism is activated.
178
Chapter 6 UC4 and Target Systems
6.1.5 Agent - Freely Defined Port Numbers
Free port number are usually supplied in the DCSOF with the parameter "Freeport". By default, the first
free port number is 4096.
The BS2000 Agent does not work with a fixed port number which is written in to its INI file. The Agent
requests a free port number when it establishes a connection to the UC4 Automation Engine.
If the BS2000 Agent is automatically loaded after a successful test start of the host, please make sure
that its required free port number is not in conflict with other settings.
Example:
The test results in the following constellation:
1. An application which uses the port number 4096 via /BCMAP command is already running.
2. The BS2000 Agent is started manually and obtains the next free port number (e.g.: 4097).
3.Result: Both, the application and the Agent work correctly.
After the tests, the BS2000 Agent starts automatically and is loaded before the application.
1. The BS2000 Agent obtains the first free port number 4096.
2. The application to which this port number has been assigned on a fixed basis via a /BCMAP command
cannot start.
6.1.6 BS2000 Console Command
The creation, the forming up and the processing of a data sequence is a complex process whereby script
functions and statements as well as special objects cooperate closely.
The following example shows the necessary definitions for the involved objects and the corresponding
script statements and their reference.
The example is kept small and clear to show the principles. It demonstrates how a BS2000 Console
Command is executed from a Job and how the result is written line-by-line to the Job's activation report.
To execute a BS2000 Console Command the utility UCYEBXXZ must be installed on the host.
Job: SC.PROCESS.BS2000UCON
Automation Engine
179
The script of the Job calls the function PREP_PROCESS which prepares the processing of the data
sequence. The following parameters are passed:
l
l
l
l
l
Name of the computer on which an Event job shall be executed - in this case: C70.
Type of the Event job, that shall be executed - in this case BS2000UCON.
By specifying BS2000UCON, the job EVENT.BS2000UCON will be executed.
By default, the Event jobs EVENT.BS2000.CMD, EVENT.BS2000UCON, EVENT.UNIXCMD,
EVENT.UNIXFS and EVENT.WINCMD are supplied with client 0000. They can be used as they
are or as a template for your own Event jobs.
The third function parameter was omitted. This means that by using the default value "*" as filter, all
output lines from the console command will be taken into account.
The script variable &CMD of the Event job is supplied with the value BCDISP DISP=O.
The Event job should execute this command on the console and thus list all active applications.
The Job EVENT.BS2000UCON will then be started.
Job: EVENT.BS2000UCON
180
Chapter 6 UC4 and Target Systems
The job EVENT.BS2000UCON from client 0000 is supplied by default.
It is important that in its Attributes tab, the check box "Attribute dialog" is checked. That way the Include
object ATTRDIA.BS2000 is read, which normally causes the start of the Attribute Dialog.
Include: ATTRDIA.BS2000
Automation Engine
181
All attributes listed in the script of the Include can be supplied this way. The Attribute Dialog is not
displayed because passing the variable contents is done internally.
Job: EVENT.BS2000UCON
Now the Job can log on and the console command can execute.
l
l
l
l
The UC4 utility UCYEBXXZ starts in the signature $UC4.
The utility tries to establish one of the specified console connections.
The command BCDISP DISP=O will be executed after the connection has been established
successfully.
The completion message of the console command or the specified timeout of 120 seconds will
close the connection.
The outfile is transferred to the UC4 Automation Engine by using the file transfer and is then available as a
data sequence. The execution of the Job EVENT.BS2000UCON is completed.
Job: SC.PROCESS.BS2000UCON
182
Chapter 6 UC4 and Target Systems
The function PREP_PROCESS returns a value which is a handle for information on the data sequence
that will be processed.
This value is passed to the statement :PROCESS as a start parameter. :PROCESS and
:ENDPROCESS then form a processing loop which, in this case, will be cycled until the end of the data
sequence is reached. During each iteration, a new line of the data sequence is fetched from memory. The
function GET_PROCESS_LINE can - by using the current value - retrieve the contents of the current line.
In the example, the current console line is written to the activation protocol.
The :STOP statement interrupts the execution and displays this activation report.
6.1.7 BS2000 Operating System Command
The creation, forming up and processing of a data sequence is a complex process whereby script
functions and statements, as well as special objects, cooperate closely.
The following example shows the necessary definitions for the involved objects and the corresponding
script statements and their reference.
The example is kept small and clear to show the principles. It demonstrates how a BS2000 Command is
executed from a Job and how the result is written line-by-line to the Job's activation report.
Job: SC.PROCESS.BS2000CMD
Automation Engine
183
The script of the Job calls the function PREP_PROCESS which prepares the processing of the data
sequence. The following parameters are passed:
l
l
l
l
l
Name of the computer on which an Event job shall be executed - in this case: C70.
Type of the Event job to be executed - in this case BS2000CMD.
By specifying BS2000CMD, the Job EVENT.BS2000CMD will be executed.
By default, the Event jobs EVENT.BS2000.CMD, EVENT.BS2000UCON, EVENT.UNIXCMD,
EVENT.UNIXFS and EVENT.WINCMD are supplied with client 0000. They can be used as they
are or as a template for your own Event jobs.
The third function parameter was omitted. This means that by using the default value "*" as a filter,
all output lines from the console command will be taken into account.
The script variable &CMD of the Event job is supplied the value /STA P.
The Event job executes this command using the Login object UC4ADMIN.
The job EVENT.BS2000CMD will then be started.
Job: EVENT.BS2000CMD
184
Chapter 6 UC4 and Target Systems
This is the job EVENT.BS2000CMD from client 0000 supplied by default.
It is important that in its Attributes tab, the check box "Attribute dialog" is checked. That way, the Include
object ATTRDIA.BS2000 is read which normally causes the start of the Attribute Dialog.
Include: ATTRDIA.BS2000
Automation Engine
185
All attributes listed in the script of the Include can be supplied. The Attribute Dialog is not displayed
because passing of the variable contents is done internally.
Job: EVENT.BS2000CMD
Now the job can log on and the console command can execute.
l
l
The scheduled command /STA P is stored in the script variable &CMD.
SYSOUT is redirected to an output file and the command is executed.
The outfile is transferred to the UC4 Automation Engine by using the file transfer and is then available as a
data sequence. The execution of the Job EVENT.BS2000CMD is completed.
Job: SC.PROCESS.BS2000CMD
186
Chapter 6 UC4 and Target Systems
The function PREP_PROCESS returns a value which is a handle for information on the data sequence
that will be processed.
This value is passed to the statement :PROCESS as a start parameter. :PROCESS and
:ENDPROCESS then form a processing loop which in this case, will be cycled until the end of the data
sequence is reached. During each iteration, a new line of the data sequence is fetched from the memory.
The function GET_PROCESS_LINE can retrieve the contents of the current line by using the current
value.
In the example, the current console line is written to the activation protocol.
The :STOP statement interrupts the execution and displays the activation report.
6.2 UC4 and Databases
6.2.1 Database Agent
One of UC4's components is an Agent that can be used to establish connections to databases. It
facilitates the execution of SQL statements in these databases without an external command line tool
being required. In doing so, security is increased and database administration simplified. In addition to
typical SQL statements such as SELECT or UPDATE, the Agent can process database-specific
commands and stored procedures in the database.
The Job object includes an editor that makes it easy to specify SQL statements. Additionally it
displays database tables and columns.
The result of the SQL statements are stored in a job report which can be read using the script statement
PREP_PROCESS_REPORT. If an error occurs during job execution or if the job aborts, the Agent
cancels all SQL statements until the last COMMIT. The job object provides many possible ways to
configure the execution of SQL statements.
Automation Engine
187
The UC4.Agent for Databases currently supports Oracle, MSSQL, DB2 and MySQL.
See also:
Form tab
6.2.2 Connection to Oracle Databases
The Database Agent can connect either to an Oracle Database instance or to Oracle RAC nodes.
Single instance Oracle connections
This is the standard connection method. The Database can only connect to an Oracle Database instance.
The Job object contains the relevant connection data.
The Database Agent's INI-file parameter useOraClient= (section [SQL]) must be set to the value "0".
Oracle RAC connections
The Database Agent can connect itself to Oracle RAC nodes. The Oracle file tnsnames.ora contains the
relevant connection data. It is not necessary to fill in the field "Server" in the Job object's SQL tab.
The following steps are required in addition to installing the Database Agent:
1. Set the Database Agent's INI-file parameter useOraClient= to the value
"1".
2. Install the Oracle Client or the Oracle Instant Client on the Database Agent's computer. Several
packages are available for the Oracle Instant Client. The Database Agent requires the "Basic" package.
3. When using the Oracle Instant Client, set two environment variables. Include the Oracle Instant Client's
installation directory in the environment variable PATH (for Windows) or LD_LIBRARY_PATH (for UNIX).
The environment variable TNS_ADMIN must point to the directory in which the file tnsnames.ora is stored.
Example for the file tnsnames.ora:
APPL_DB = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = db-server01)
(PORT = 1521)) (ADDRESS = (PROTOCOL = TCP)(HOST = db-server02)(PORT =
1521)) (LOAD_BALANCE = yes) (CONNECT_DATA = (SERVER = DEDICATED) (SERVICE_
NAME = APPLDB.CUSTOMER.COM) ) )
For this example, the name "APPL_DB" must be specified in the Job object's field Database.
6.2.3 Stored Procedures in Sybase
The execution of stored procedures requires an additional command.
Use the following lines to call a stored procedure:
execute sp_procxmode 'procedure name','anymode';
execute procedure name;
188
Chapter 6 UC4 and Target Systems
The following error message is displayed if an attempt is made to execute a stored procedure directly:
"Stored procedure 'procedure name' can be run only in unchained transaction mode. The 'SET CHAINED
OFF' command will cause the current session to use unchained transaction mode."
The command "SET CHAINED OFF" cannot be called because of the JDBC driver. Use the command
sp_procxmode instead.
6.2.4 Stored Procedures in MS SQL Server
The UC4 Database Agent can be used to process Stored Procedures for MS SQL.
RETURN
The statement RETURN can return a number. This return code can then be written to the job report (see
example below). The name of the stored procedure is ANGTEST.
SQL_SET_STATEMENT_TERMINATOR TERM='!';
DECLARE @result int;
EXEC @result = ANGTEST;
select @result;!
A separator other than the semicolon is automatically used because this character has already been
used within the statement.
The job ends normally regardless of its return code. If you intend to change a job's end status, you can
read the corresponding value in the job report and react to it using :MODIFY_STATE.
PRINT
The statement PRINT facilitates the output of messages to a user (example: DBCC CHECKDB). These
messages are also written to the job report. Job execution continues as usual.
RAISE ERROR
Causes the job to be aborted. The error message is written to the activation report.
See also:
Form tab
Process tab
PREP_PROCESS_REPORT
6.2.5 ILM - Partition Key Turnaround
Partitioning the UC4 Database by using ILM results in a very specific situation when the maximum RunID
(tasks, statistical records) is reached. How quickly this limit is reached depends on the number of tasks
Automation Engine
189
that are started on a regular basis. To solve this problem, the system executes a special procedure in such
a situation which is referred to as Partition Key Turnaround.
General Information
Statistical entries (for executed tasks) are stored in the AH table which also includes the corresponding
RunIDs in the AH_Idnr column. From a technical point of view, this column's values are 32-bit numbers
and the maximum value that can be reached is 2,147,483,647. All numbers below 1,000,000 are reserved
for specific processes.
Therefore, the allowed values for the RunIDs of statistical records range from: 1,000,000 to 2,147,483,647.
You will rarely ever reach this limit in UC4 systems that include a low number of regularly executed tasks.
By using a huge number of daily activities (~1,000,000), you can already reach this limit after a few years.
Partition Change
For general information about ILM and partition changes click here.
The database always keeps a certain number of partitions online. You can determine this number by
specifying the setting ONLINE_PARTITIONS in the UC4 Variable UC_ILM_SETTINGS.
Using UC4 with ILM means that each partition is limited by a maximum key value. Only the current
partition is open ended and not limited by a maximum value. This partition uses a specific virtual value:
NULL for MS SQL Server and MAXVALUE for Oracle databases.
A partition change means that a new partition is inserted in the current partition's (virtual) upper limit and
the oldest partition is deleted. In Oracle, you can directly delete the partition; the MS SQL Server needs a
staging table for this purpose.
Partition Key Turnaround Mode
The system automatically and regularly checks the maximum RunID usage of all the existing partitions
and stores the result in the MAX_ENTRIES key of the UC4 Variable UC_ILM_SETTINGS. For a partition
change, the system checks the currently highest RunID and calculates whether less than three times the
specified value of MAX_ENTRIES can be used until the limit is reached. If so, the system automatically
activates Partition Key Turnaround Mode.
With this special mode active, the new partitions are now inserted in the lower number range (starting with
1,000,000) and numbering starts from the beginning. This specific mode remains active until all partitions
that include the upper number ranges have been removed and a constant value range up to 2,147,483,647
has become available again.
Partitioning in Oracle differs from partitioning in MS SQL Server databases, and therefore their Partition
Key Turnaround patterns are also different. Thus the processes are written per database type.
Oracle
Base scenario:
Maximum usage (MAX_ENTRIES): 1,000,000
Currently highest RunID: 2,145,000.000
Online partitions: 4
Partition Upper limit
P11
2,142,483,647
190
Chapter 6 UC4 and Target Systems
P12
2,143,483,647
P13
2,144,483,647
P14
MAXVALUE
Technically, P11 ranges from 1,000,000 to 2,142,483,647, but logically it ranges from 2,141,483 647 to
2,142,483,647 because only data records are written to this UC4 section.
The partition should now be changed. The difference between the currently highest RunID (2,145,000,000)
and the maximum value (2,147,483,647) is less than three times the value of MAX_ENTRIES (1,000,000);
therefore, the system switches to Partition Key Turnaround Mode:
The oldest partition (P11) is split and a new partition (P15) is inserted in the lower number range (starting
with 1,000,000). The upper limit of the new partition is three times the maximum value. In our case, the
new partition's (P15) upper limit is 4,000,000.
When P15 has been inserted, the system removes the oldest partition P11 and four partitions are then
online again.
This procedure is repeated when the next partition change takes place:
The new partition's upper limit is again three times the maximum value with the upper limit of P15 being the
starting point for the calculation. The currently oldest partition P12 is split at the value 7,000,000. In doing
so, the new partition P16 is created and P12 is removed.
This procedure is repeated until no more partitions are available in the upper number range. In our case,
this will happen after one further partition change (P17).
Deleting the open-ended partition P14 now has the effect that the system does not split the partition but it
inserts a new open-ended partition (P18) instead.
This ends Partition Key Turnaround Mode and the normal mode is activated again. The RunIDs are now
allocated starting with the lower number range.
Automation Engine
191
The following applies:
l
l
l
A further partition change is required if the Partition Key Turnaround Mode is active.
The old partitions must still be deleted in order to ensure that the ones that include the upper number
ranges are removed and the system can switch back to normal mode.
UC4 recommends monitoring the RunId usage in order to ensure that the limit of three times the
maximum value is not exceeded. The partition must be changed ahead of schedule if this limit
cannot be kept.
SQL Server
Base scenario:
Maximum usage (MAX_ENTRIES): 1,000,000
Currently highest RunID: 2,145,000,000
Online partitions: 4
Partition Upper limit
P1
2,142,483,647
P12
2,143,483,647
P13
2,144,483,647
P14
NULL
Because a lower limit is defined in MS SQL Server, the lowest partition P1 is empty. Technically, you can
use it, but logically it is empty because UC4 does not use it. It is not shown in the System Overview.
Therefore, the lowest logical partition is P12.
The last partition P14 is open ended.
The partition should now be changed. Partition Key Turnaround Mode is activated because the difference
between the highest RunID and the maximum limit lies below three times the value of MAX_ENTRIES.
192
Chapter 6 UC4 and Target Systems
MS SQL Server defines a lower limit. Therefore, the lowest partition P1 is split at 1,000,000 so that the
lower area also includes a partition. This lower area remains partition P1 and is reserved for the values
below 1,000,000. It is still not used. The split creates the new partition P15 which inherits the upper limit of
the previously smallest partition.
Technically, P15 now ranges from 1,000,000 to 2,142,483,647. However, this limit will continuously
change because of the partition changes that will take place.
The oldest partition P12 is then deleted, whereby P15 automatically inherits this partition's upper limit.
Technically, P15 now ranges from 1,000,000 to 2,143,483,647.
The next partition change splits the partition 15: P15 obtains the actual maximum usage value of 1,000,000
as its upper limit with the calculation starting at P1's upper limit. As a result, P15's upper limit is 2,000,000.
The oldest partition P13 is now deleted.
Technically, the new partition P16 ranges from 2,000,000 to 2,144,483,647 because it inherits the upper
limit of P13.
The current situation is:
With the last partition change, P16 obtains the actual maximum usage value and is split at 3,000,000.
Partition P14 is deleted and the new partition P17 is open ended. Partition Key Turnaround Mode ends and
the system runs in normal mode again.
The following applies:
l
Make sure that the partitions are changed on a regular basis if the maximum usage value of
2,147,483,647 is almost reached.
Automation Engine
193
6.3 UC4 and GCOS 8
6.3.1 GCOS8 Agent - FileTransfer Support
The GCOS Agent provides FileTransfer support for files with a particular format and specific attributes.
GFRC File Format
[GFRC] [UFF sequential] [UFF relative] [UFF indicated]
l
l
l
Sequential file organization
Sequential access mode
Processing modes: input, output or extend
Syntax
Input mode:
GFRC=media code[,RSZ=record length]
Output mode:
GFRC=media code[,RSZ=record length][,VLREC_NO/VLREC_SEG]
File attribute
(UFAS
attributes)
Description
GFRC=media
code
Enforces file organization in sequential GFRC format
Allowed values for the media code:
l
l
l
l
l
RSZ=record
length
"00" - no media conversion record or no printer slew controls
"01" - binary card image
"02" - BCD card image
"06" - GFRC format ASCII (format used by the Time Sharing System)
"10" - Time Sharing System information record
Maximum number of characters for read or written records.
Target platform GCOS8: default value for non-partitioned records is 80, for partitioned
ones it is 84.
Default values for all other platforms:
l
l
l
l
Media-Code 0: 16384
Media-Code 2: 1272
Media-Code 6: 16384
Media-Code 10: 1272
VLREC_NO
Enforces the use of records of a fixed length
VLREC_SEG
Variable record length that can be partitioned via one or several physical blocks
194
Chapter 6 UC4 and Target Systems
Example
GFRC=06,RSZ=70
UFF sequential File Format
[GFRC] [UFF sequential] [UFF relative] [UFF indicated]
l
l
l
l
Sequential file organization
Sequential access mode
Processing modes: input, output or extend
Variable record length by default
Syntax
Input mode:
UFF_SEQ[,RSZ=record length]
Output mode:
UFF_SEQ[,RSZ=record length][,VLREC_NO/VLREC_SEG][,CISZ=size]
File
Description
attribute
(UFAS
Attributes)
UFF_SEQ
Enforces file organization in sequential UFF format
RSZ=
record
length
Maximum number of characters for read or written records. This value affects the size of
the Control Intervals (CI) which is selected for output files. A CI size of 1K is used if the
maximum record size is 2000 or less. Record sizes above 2000 cause the creation of CIs
with a record length of 4K. The default value is 80.
VLREC_
NO
Enforces the use of records of a fixed length
VLREC_
SEG
Variable record length that can be partitioned via one or several physical blocks
CISZ=size
Sets the size of the Control Intervals (in Bytes)
Example
UFF_SEQ,RSZ=100
UFF relative File Format
[GFRC] [UFF sequential] [UFF relative] [UFF indicated]
l
l
l
l
Relative file organization
Sequential or random access mode
Processing modes: input, output or extend
Fixed record lengths
Automation Engine
195
Syntax
Input mode:
UFF_REL[,RSZ=record length]
Output mode:
UFF_REL[,RSZ=record length][,CISZ=size]
File attribute
Description
(UFAS Attributes)
UFF_REL
Enforces file organization in relative UFF format
RSZ=record length Maximum number of characters for read or written records. The default value is 80.
CISZ=size
Sets the size of the Control Intervals (in Bytes)
Example
UFF_REL,RSZ=120,CISZ=8192
UFF indicated File Format
[GFRC] [UFF sequential] [UFF relative[UFF indicated
l
l
l
l
Indicated file organization
Sequential or random access mode
Processing modes: input, output or extend
Fixed record lengths
Separate the two names for the file and the index file with a semi-colon.
Syntax
Input mode:
UFF_IND[,KEY=(duplicates,offset,length)][,KNR=key number][,RSZ=record length]
Output mode:
UFF_IND,KEY=(duplicates,offset,length)[,RSZ=record length][,CISZ=size]
File attribute
(UFAS attributes)
Description
UFF_IND
Enforces file organization in indicated UFF format
RSZ=record length
Maximum number of characters for read or unwritten records. The default value
is 80.
196
Chapter 6 UC4 and Target Systems
KEY=(
Defines a key for the inidicated files:
duplicate,offset,length
l
Duplicates - show whether duplicate keys are allowed for the key
)
definition.
l
l
Allowed values:
"0" - the key does not contain duplicates
"1" - the key can contain duplicates
Offset - offset in records (Bytes)
Length - key length (Bytes)
It is possible to define more than one key. The first entry is the primary key.
Set the parameter "duplicate" to 0 in order to avoid the use of double keys.
The entries ranging from the second to the nth one stand for the n-1 varying
keys. Using this attribute is obligatory.
KNR=key number
Defines the key that is used as reference key when searching the record to be
read. This entry corresponds to the key definition's array element (basis 1) in
the KEY_DESC structure which is used to open the file. The default value is 1 i.e. the primary key.
CISZ=size
Sets the sizes of the Control intervals (in Bytes).
Example
UFF_IND,KEY=(0,0,20)
See also:
FileTransfer tab
6.3.2 Monitoring Abnormal Job-Messenger Ends
The following description includes information about the GCOS8 Job messenger and how an abnormal
Job-messenger end can be identified.
The GCOS8 Agent uses three job messengers to obtain information about job states:
1. Start messenger (for job starts)
2. End messenger (for job ends)
3. Report messenger (for job reports)
If available, the report messenger is generated by the RSM system. GCOS8 jobs are finished after the job
report has been created. The RSM system retrieves the report from the SYSOUT, then the Agent is
informed that the job report is ready to be transported to the UC4 system.
Messenger programs are vital for the execution of jobs. UC4 can be used to react to an abnormal jobmessenger ending.
The program Switch Word (PSW) is used to send information about an abnormal job messenger end. This
program has a 36-bit memory area. The bits between 0 and 17 are reserved for the GCOS8 system. The
remaining bits from 18 to 35 can be used in any which way. In order to display its status, the job
messenger uses only one bit. This bit is defined using the parameter SW=bit number. Set the selected bit
Automation Engine
197
with the JCL statement $SET. With this configuration the job messenger is able to check whether the bit is
in status ON. It sets it to OFF as soon as it is able to end normally. If the status remains ON, the job
messenger has ended abnormally.
Ensure that no other applications already use the selected bit.
Procedure
The following descriptions use bit number 18. However, you can use any bit between 18 and 35 that has
not yet been used. Proceed as follows to activate job messenger monitoring.
Start messenger:
1. Open the Header-Include object HEADER.GCOS8.
2. Insert the $SET statement and the job-messenger parameter SW=. The illustration below shows
the relevant areas in a red frame.
3. The area where the bit status is checked is also shown in a frame. The start messenger has ended
abnormally if it is still set; therefore, the job will be canceled. Additional statements can also be
inserted.
End messenger:
198
Chapter 6 UC4 and Target Systems
1. Open the Trailer-Include object TRAILER.GCOS8.
2. Use the same configuration as for the start messenger. Insert the $SET statement and the jobmessenger parameter SW=. The illustration shows these areas in a red frame.
Report messenger:
Refer to the RSM Documentation for detailed information about how to adjust the report messenger.
6.4 UC4 and Java EE/JMX
6.4.1 Java EE/JMX Agent
Java Management Extensions (JMX) is a technology which provides the instruments required for
managing and monitoring applications, devices and networks. The UC4 Automation Platform supplies an
Agent for Java EE/JMX which facilitates the integration of Java applications in enterprise-wide processes.
A connection can be established via an MBean Server, a function used to access MBeans.
There are two methods in establishing a connection. First, the Java EE/JMX Agent can be run as a Web
application within the Java Virtual Machine and access an MBean Server of the same computer.
Automation Engine
199
The second available method is to specify a Job in a way that it can access MBean Servers on a different
computer via the MX Remote API (JSR 160). The URL of the MBean Server can be specified in the Job
object. In this case, the MBean Server computers must have a Connection Server.
The connection to the MBean Server can be defined in the Host tab of JMX Jobs.
If the JMX Agent is used for SAP, it creates an additional log file in SAP format. This file is
automatically created in the Agent's sub-folder "log" in the installation directory and can easily be
processed with SAP Tools.
See also:
UC4 JCL for JMX
200
Chapter 6 UC4 and Target Systems
6.4.2 Generating MBeans from Web Services
Guideline for the creation of MBeans based on Web services.
Knowledge of Java and Web services is required in order to be able to fully understand this guideline.
UC4 provides support neither for Web services nor for MBeans.
General
The UC4 Automation Platform supports Web services through the usage of MBeans in combination with
the JMX Agent. Many vendors offer Web services rather than MBeans as interfaces that provide access to
their applications. This guideline describes step by step how an MBean is generated from an existing Web
service. The Web service "CurrencyConvertor" which is provided by Generic Objects Technologies Ltd
serves as an example. It supplies currency exchange rates.
Requirements:
l
l
l
JMX Agent
Access to the Web service (WDSL, URL, parameters)
Apache Axis (freely available)
MBeans can only be created for synchronous Web services. Using asynchronous Web services is
much more difficult and must be handled individually.
Thoroughly test the generated MBean.
Installation
1.
l
Download the Apache Axis files from http://ws.apache.org/axis. Install them as described in the
Apache Axis documentation.
2.
l
Setting up Apache Axis
Generating Java classes for calling the Web service
Start the Apache Axis tool "WSDL2Java". This is a Web service wrapper generator. You can also
use Eclipse as your development environment. Specify the WSDL address
http://www.webservicex.com/CurrencyConvertor.asmx?wsdl" as the input parameter.
Automation Engine
l
As a result, the following Java classes are generated:
3.
l
l
201
Creating an MBean for using the Java classes
This step describes the creation of an MBean that uses the generated Java classes to call the Web
service via JMX.
A few initiatory notes on MBeans programming guidelines:
l
A standard MBean pattern consists of an interface and a class which implements it. l
The interface has the same name as the class plus the ending "MBean".
In the following example, the class is called "Converter" and the interface "ConverterMBean.java".
Create both files in the package "com.uc4.ws". This is followed by the full interface code and class:
ConverterMBean.java:
package com.uc4.ws;
import java.rmi.RemoteException;
import javax.xml.rpc.ServiceException;
202
Chapter 6 UC4 and Target Systems
public interface ConverterMBean {
double convertCurrency(String fromCurrency, String toCurrency)
throws ServiceException, RemoteException, IllegalArgumentException;
}
Converter.java:
package com.uc4.ws;
import
import
import
import
import
java.rmi.RemoteException;
javax.xml.rpc.ServiceException;
NET.webserviceX.www.Currency;
NET.webserviceX.www.CurrencyConvertorLocator;
NET.webserviceX.www.CurrencyConvertorSoap;
public class Converter implements ConverterMBean {
public double convertCurrency(String fromCurrency, String toCurrency)
throws ServiceException, RemoteException, IllegalArgumentException {
CurrencyConvertorLocator locator = new CurrencyConvertorLocator();
CurrencyConvertorSoap soap = locator.getCurrencyConvertorSoap();
return soap.conversionRate(
Currency.fromString(fromCurrency),
Currency.fromString(toCurrency));
}
}
The method "convertCurrency" contains the Web service call. Therefore, it uses the generated
Java classes. It creates a service-locator instance and calls the method
"getCurrencyConvertorSoap" in order to obtain a SOAP stub. This pattern (locator-stub) is
described in the Apache Axis documentation.
The stub calls the Web service. The parameters are converted from "java.lang.String" to
"NET.webserviceX.www.Currency" objects because only simple data types can be used in
MBeans. The supplied result is the current currency conversion rate.
4.
l
Creating the MBean's JAR file and the Java classes
Create a common JAR file for the two files of the MBean and the generated Java classes using an
ant script. The following example shows how the file "exampleMBean.jar" is generated.
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<project name="uc4" default="exampleMBean.jar">
<property name="classes_dir" value="bin" />
<target name="exampleMBean.jar" description="Web Service MBean">
<jar jarfile="exampleMBean.jar" basedir="${classes_dir}"/>
</target>
</project>
No ant script is required in development environments such as Eclipse. Here you can generate the
JAR file via menu command.
5.
l
Starting the JMX Agent using an MBean
Include the generated JAR file and the Apache Axis JAR files in the JMX Agent's classpath. The
call for starting the JMX Agent under Windows is shown below:
Automation Engine
203
Java -cp axis.jar;commons-discovery-0.2.jar;commons-logging-1.0.4.jar;
wsdl4j-1.5.1.jar;saaj.jar;exampleMBean.jar;ucxjjmx.jar;jaxrpc.jar
com/uc4/ex/jmx/UCXJMX
UNIX: use a colon (":") instead of a semicolon (";").
The JMX Agent does not require an application server but can run independently. It is sufficient to
install the Java version 5 as it contains the required JMX packages of version 1.2.
Usage
1.
l
l
l
Creating a JMX job
Log on to the UC4 system using the UserInterface.
Create a JMX job and select the JMX Agent which contains the MBean in its Attributes tab. Select
a suitable Login object.
Switch to the Form tab. Click the
button in order to insert a new line. Register the MBean on the
MBean Server by double-clicking the function "Register MBean" in the category "MBean Server".
The function JMX_CREATE_MBEAN creates an MBean instance and registers it on the local
MBean Server.
l
l
Enter the MBean's full class name in the field "class". In this example it is
"com.uc4.ws.Converter".
Enter the term which should be assigned to the MBean in the field "Object name". This name must
be unique in the MBean Server. It consists of two parts which are separated by a colon ":". The first
part refers to the domain name and the second one to the key properties. This example uses the
name "com.uc4:name=CurrencyConverter".
The domain name must not include the characters ":", "*" and "?". In order to avoid collisions
between the MBeans of different vendors, UC4 recommends using the DNS name of your
company backwards as the domain name.
The key properties assign a unique name to the MBeans within the domain. They are separated
by commas ",". A key property is structured as follows: Properties=Value. The property must
not correspond to an attribute of the MBean. The number of key properties is not limited and the
order is irrelevant. A key property must not contain inverted commas, commas or ":", "=", "*"
and "?". Specify at least one key property.
l
Activate the setting "End normally if already registered".
204
Chapter 6 UC4 and Target Systems
l
Store the JMX job and process it. By doing so, the MBean is registered on the MBean Server and is
visible in the MBean browser (see step 2).
2.
l
Using the MBean
The MBean can be addressed and used via its operations. Click the button
in the JMX job's
Form tabin order to insert a new line. Double-click the function "Execute operation" in the category
"Operations".
The function JMX_INVOKE calls an operation of an MBean.
l
l
l
l
l
Click the "Search..." button in order to open the MBean browser.
Select the MBean "CurrencyConverter" on the left. The table on the right shows the available JMX
operations for the MBean.
Highlight the operation "convertCurrency" and Click OK tab. The fields "MBean Name" and
"Operation" are automatically filled with the correct values.
Enter two currency codes in the field "Parameter" and separate them with a comma. Example:
"USD,EUR" has the effect that the MBean returns the exchange rate for US Dollars to Euro.
Execute the JMX job. The conversion rate is output in a report.
Read the report using the script function PREP_PROCESS_REPORT so that the values
supplied by the MBeans can be used for further processing. The Sample Collection contains a
description of the required steps.
Automation Engine
205
6.4.3 Java EE/JMX Agent and IBM WebSphere
There are several ways of using the Java EE/JMX.
Stand alone outside of IBM WebSphere:
1. With SOAP
Deployed in IBM WebSphere:
1. With SOAP
2. With SOAP or RMI
The stand-alone method is best used if the Java EE/JMX Agent addresses several IBM WebSphere
Servers with the intention of using their MBeans. The Agent is installed in an IBM WebSphere cell and
connects to the Deployment Manager's (DMGR) MBean Server which controls the individual IBM
WebSphere Application Servers.
See also:
Setting up the Stand-alone Agent for Java EE/JMX (IBM WebSphere) with SOAP Connector
Setting up the Agent for Java EE/JMX (IBM WebSphere) with SOAP Connector
Setting up the Agent for Java EE/JMX (IBM WebSphere) with RMI Connector
6.4.4 Sending an SOAP Message with an MBean
Below is an example for an SOAP message which polls stock prices.
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<ns1:getQuote
soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:ns1="urn:xmethods-delayed-quotes">
<symbol xsi:type="xsd:string">IBM</symbol>
</ns1:getQuote></soapenv:Body>
</soapenv:Envelope>
The following SOAP action should be used to send the SOAP message: "urn:xmethods-delayedquotes#getQuote".
URL of the webservice: http://services.xmethods.net/soap
An MBean can be used to send this SOAP message. This MBean requires at least Java version 5. Add
the MBean to the Agent's classpath:
1. Copy the file soapmbean.jar into the folder of the JMX Agent.
2. Start the JMX Agent with the file soapmbean.jar in the classpath.
java -cp soapmbean.jar;ucxjjmx.jar com/uc4/ex/jmx/UCXJMX
Create a JMX job and insert the following line in the Process tab:
206
Chapter 6 UC4 and Target Systems
JMX_CREATE_MBEAN
EXISTS="IGNORE",CLASSNAME="com.uc4.ex.jmx.soap.SOAP",NAME="uc4.com:name=SOA
P"
Start the job. The MBean "SOAP" is now listed in the MBean Browser.
In the next step, determine the JCL for using the SOAP MBean:
JMX_CREATE_MBEAN
EXISTS="IGNORE",CLASSNAME="com.uc4.ex.jmx.soap.SOAP",NAME="uc4.com:name=SOA
P"
JMX_COMPOSITE_ADD KEY="1",VALUE='<?xml version="1.0" encoding="UTF8"?>',NAME="s"
JMX_COMPOSITE_ADD KEY="2",VALUE='<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" ',NAME="s"
JMX_COMPOSITE_ADD
KEY="3",VALUE='xmlns:xsd="http://www.w3.org/2001/XMLSchema" ',NAME="s"
JMX_COMPOSITE_ADD
KEY="4",VALUE='xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance">',NAME="s"
JMX_COMPOSITE_ADD KEY="5",VALUE="<soapenv:Body><ns1:getQuote ",NAME="s"
JMX_COMPOSITE_ADD
KEY="6",VALUE='soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encod
ing/" ',NAME="s"
JMX_COMPOSITE_ADD KEY="7",VALUE='xmlns:ns1="urn:xmethods-delayedquotes">',NAME="s"
JMX_COMPOSITE_ADD KEY="8",VALUE='<symbol
xsi:type="xsd:string">IBM</symbol>',NAME="s"
JMX_COMPOSITE_ADD
KEY="9",VALUE="</ns1:getQuote></soapenv:Body></soapenv:Envelope>",NAME="s"
JMX_INVOKE
OPERATIONNAME="sendSOAP",MBEAN="uc4.com:name=SOAP",PARAMS='s,"urn:xmethodsdelayed-quotes#getQuote",http://services.xmethods.net/soap'
The first line ensures that the MBean exists or loads it if necessary. The statements JMX_COMPOSITE_
ADD insert the SOAP message line by line with the parameter KEY= containing the line number. After the
SOAP message has been composed, it is assigned to the operation "sendSOAP" (JMX_INVOKE) as its
first parameter. The second parameter contains the SOAP action, and the third one the URL to which the
SOAP request should be sent.
Execute the job. The job report shows the response message.
An XPath expression can be used to read an individual value. Do so by inserting a new script line using the
script element JMX_COMPOSITE_ADD with the statement "XPATH" for KEY= and the searched value
for VALUE= (see second script line). The script now looks as shown below:
JMX_CREATE_MBEAN
EXISTS="IGNORE",CLASSNAME="com.uc4.ex.jmx.soap.SOAP",NAME="uc4.com:name=SOA
P"
JMX_COMPOSITE_ADD KEY="XPATH",VALUE="//Result",NAME="s"
JMX_COMPOSITE_ADD KEY="1",VALUE='<?xml version="1.0" encoding="UTF8"?>',NAME="s"
JMX_COMPOSITE_ADD KEY="2",VALUE='<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" ',NAME="s"
JMX_COMPOSITE_ADD
KEY="3",VALUE='xmlns:xsd="http://www.w3.org/2001/XMLSchema" ',NAME="s"
JMX_COMPOSITE_ADD
KEY="4",VALUE='xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance">',NAME="s"
JMX_COMPOSITE_ADD KEY="5",VALUE="<soapenv:Body><ns1:getQuote ",NAME="s"
JMX_COMPOSITE_ADD
Automation Engine
207
KEY="6",VALUE='soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encod
ing/" ',NAME="s"
JMX_COMPOSITE_ADD KEY="7",VALUE='xmlns:ns1="urn:xmethods-delayedquotes">',NAME="s"
JMX_COMPOSITE_ADD KEY="8",VALUE='<symbol
xsi:type="xsd:string">IBM</symbol>',NAME="s"
JMX_COMPOSITE_ADD
KEY="9",VALUE="</ns1:getQuote></soapenv:Body></soapenv:Envelope>",NAME="s"
JMX_INVOKE
OPERATIONNAME="sendSOAP",MBEAN="uc4.com:name=SOAP",PARAMS='s,"urn:xmethodsdelayed-quotes#getQuote",http://services.xmethods.net/soap'
Based on the sample script, the job report now shows a value.
Parts of the SOAP message can also be supplied with values via script variables. The following example
reads a value via a :READ mask:
Pre-Process tab:
:READ &SYMBOL#,"IBM,SAP,ORCL","Please choose one","IBM"
Process tab:
The script variable &SYMBOL# is used in the 10th line:
JMX_CREATE_MBEAN
EXISTS="IGNORE",CLASSNAME="com.uc4.ex.jmx.soap.SOAP",NAME="uc4.com:name=SOA
P"
JMX_COMPOSITE_ADD KEY="XPATH",VALUE="//Result",NAME="s"
JMX_COMPOSITE_ADD KEY="1",VALUE='<?xml version="1.0" encoding="UTF8"?>',NAME="s"
JMX_COMPOSITE_ADD KEY="2",VALUE='<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" ',NAME="s"
JMX_COMPOSITE_ADD
KEY="3",VALUE='xmlns:xsd="http://www.w3.org/2001/XMLSchema" ',NAME="s"
JMX_COMPOSITE_ADD
KEY="4",VALUE='xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance">',NAME="s"
JMX_COMPOSITE_ADD KEY="5",VALUE="<soapenv:Body><ns1:getQuote ",NAME="s"
JMX_COMPOSITE_ADD
KEY="6",VALUE='soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encod
ing/" ',NAME="s"
JMX_COMPOSITE_ADD KEY="7",VALUE='xmlns:ns1="urn:xmethods-delayedquotes">',NAME="s"
JMX_COMPOSITE_ADD KEY="8",VALUE='<symbol
xsi:type="xsd:string">&SYMBOL#</symbol>',NAME="s"
JMX_COMPOSITE_ADD
KEY="9",VALUE="</ns1:getQuote></soapenv:Body></soapenv:Envelope>",NAME="s"
JMX_INVOKE
OPERATIONNAME="sendSOAP",MBEAN="uc4.com:name=SOAP",PARAMS='s,"urn:xmethodsdelayed-quotes#getQuote",http://services.xmethods.net/soap'
208
Chapter 6 UC4 and Target Systems
6.5 UC4 and Micro Focus JES
6.5.1 Jobs in Micro Focus JES
The Mainframe Transaction Option (MTO) is a Micro Focus Enterprise Server (MF ES) component. This
JES engine facilitates the execution of z/OS Jobs (JES Jobs) under Windows and Unix.
The UC4 Automation Platform can be used to start Jobs in Micro Focus JES and process JCL files. These
are then stored in the Server's file system. Jobs are started using the program CASSUB.
A UC4.Agent for Windows processes the Jobs in MF JES.
Creating a Job
1. Click the button in the toolbar. A window opens which lists all the available object types
including the objects for the individual platforms. Select JOBS.WIN.
2. Assign a suitable name for the Job object and open it. Now click the Notification tab
3. A Windows Agent executes the Job. Select the Agent which runs on the computer on which MF ES
is available.
4. In order to execute the Job, the Agent requires login information. This data is stored in the form of
Login objects. Select the suitable one in "Login".
5. Now click the Windows tab. In the upper left area, you can define how the generated job report
should be handled. You can store it in the database or as a file.
6. Specify type COM.
7. The command that should be specified indicates the path to program CASSUB. Use the start
parameters -r and -j to specify the JCL Server environment and the complete path to the JCL file.
The JCL Server Region Name describes the MF MTO Services. This value is available in the MF
Enterprise Server Administration.
Automation Engine
209
8. Store and close the Job object after having completed your configuration. The Job object can now
be integrated in your processing.
Architecture
The job starts via CASSUB in the Micro Focus Enterprise Server. An exit is called when the job starts and
during its execution. It writes the synchronization files for the Agent (*.log, *.inf and *.can files).
210
Chapter 6 UC4 and Target Systems
Agent Variables in Micro Focus JES
The following environment variables are available in the user environment under which the JES Server has
started:
Environment Variable
Description
UC4_MF_JES_
OUTPUT=
Path in which the exit should write the control files for the Agent or
communicates with the Agent (*.log, *.inf, *.can).
Ensure that the variable UC4_MF_JES_OUTPUT contains one single
path which is defined with a closing backslash "\". Otherwise, there is no
functioning communication between Agent and Exit. Examples:
Correct: UC_MF_JES_OUTPUT = c:\uc4\Agent\Microfocus\temp\
Incorrect: UC_MF_JES_OUTPUT = c:\uc4\Agent\Microfocus\temp
Incorrect: UC_MF_JES_OUTPUT = c:\uc4\temp\;c:\temp
UC4_MF_TRACE=
Trace which the exit writes in the tracefile with open extend (specified in
UC4_MF_TRACE_FILE)
Possible values:
Y = The exit writes a trace.
N = No trace is written.
UC4_MF_TRACE_
FILE=
Complete file name of the trace file
Automation Engine
UC4_MF_DELAY=
211
Delay in seconds the EXIT waits if the *.INF file cannot be found.
Note that the default value is 500 ms.
It is important that the specified value is as low as possible because it
affects ALL JES jobs and not only those started with UC4. If there are
jobs in UC4 that do not end, the exit was too quick and the Agent had no
time to create the *.INF file after job start. It cannot be created before
because the JobID results from the job start. UC4 recommends
specifying value 100.
Example for a JES-Exit trace file
2007.12.14/13:53:58.95->MFJUXIT
2007.12.14/13:53:58.95->MFJUXIT
2007.12.14/13:53:58.95->MFJUXIT
2007.12.14/13:53:58.95->MFJUXIT
2007.12.14/13:53:58.95->MFJUXIT
000005000
2007.12.14/13:53:59.11->MFJUXIT
2007.12.14/13:53:59.17->MFJUXIT
2007.12.14/13:53:59.20->MFJUXIT
2007.12.14/13:53:59.20->MFJUXIT
2007.12.14/13:53:59.23->MFJUXIT
2007.12.14/13:53:59.23->MFJUXIT
2007.12.14/13:53:59.25->MFJUXIT
2007.12.14/13:53:59.26->MFJUXIT
2007.12.14/13:53:59.26->MFJUXIT
2007.12.14/13:53:59.26->MFJUXIT
2007.12.14/13:53:59.30->MFJUXIT
2007.12.14/13:53:59.31->MFJUXIT
2007.12.14/13:53:59.31->MFJUXIT
2007.12.14/13:53:59.33->MFJUXIT
2007.12.14/13:53:59.34->MFJUXIT
2007.12.14/13:53:59.34->MFJUXIT
2007.12.14/13:54:05.26->MFJUXIT
EC = 01 Jobnum = 01406 Jobname = ????????
UC4_MF_JES_OUTPUT = C:\uc4\
UC4_MF_TRACE_FILE = c:\trc.txt
UC4_MF_DELAY = 5000
UC4_MF_DELAY (converted to number) =
EC = 25 Jobnum = 01406 Jobname = JCLTEST
EC = 03 Jobnum = 01406 Jobname = JCLTEST
EC = 08 Jobnum = 01406 Jobname = JCLTEST
EC = 09 Jobnum = 01406 Jobname = JCLTEST
EC = 10 Jobnum = 01406 Jobname = JCLTEST
EC = 08 Jobnum = 01406 Jobname = JCLTEST
EC = 09 Jobnum = 01406 Jobname = JCLTEST
EC = 10 Jobnum = 01406 Jobname = JCLTEST
EC = 08 Jobnum = 01406 Jobname = JCLTEST
EC = 09 Jobnum = 01406 Jobname = JCLTEST
EC = 10 Jobnum = 01406 Jobname = JCLTEST
EC = 08 Jobnum = 01406 Jobname = JCLTEST
EC = 09 Jobnum = 01406 Jobname = JCLTEST
EC = 10 Jobnum = 01406 Jobname = JCLTEST
EC = 05 Jobnum = 01406 Jobname = JCLTEST
inf-file not found waiting 000005000 ms
EC = 02 Jobnum = 01406 Jobname = JCLTEST
The Micro Focus Enterprise Server serves administrative purposes; jobs are maintained, started and
stopped in JES.
212
Chapter 6 UC4 and Target Systems
The following example describes how to start a JES job in batch mode without the Agent; the CASSUB is
manually set:
C:\Documents and Settings\Ni\My Documents\Micro Focus\Net Express
5.0\WORKAREA>cassub -lUC4 -jC:\es-jcldemo\jclbatch.jcl
JCLCM0901I JOB01407 ???????? Event-job-ready action is: 0 (Continue).
12:59:10
JCLCM0925I JOB01407 JCLTEST Event-job-stmt-info action is: 0 (Continue).
12:59
:10
JCLCM0187I JOB01407 JCLTEST JOB SUBMITTED (JOBNAME=JCLTEST,JOBNUM=01407)
12:59
:10
JCLCM0180I JOB01407 JCLTEST Job ready for execution. 12:59:10
Processed "C:\es-jcldemo\jclbatch.jcl"
C:\Documents and Settings\Ni\My Documents\Micro Focus\Net Express
5.0\WORKAREA>
The Exit creates the *.inf file for the Agent which checks it and writes to the log file. This does not
happen if a job is started in batch mode.
6.6 UC4 and MPE
6.6.1 Agent - Interaction between UC4 and MPE
The MPE Agent works together with the UC4 system via a TCP/IP interface.
The MPE Agent provides the following functions:
Automation Engine
l
l
l
213
Job Processing
Execution of FileTransfers
Event Handling
Job Processing
In UC4 Jobs are defined and maintained in the form of objects that include various tabs. The JCL is stored
in the Process tab. Its logic can be very complex if you make use of UC4's script elements. You can use #
as the prompt character in the JCL because the characters ! and : introduce comment lines and script
statements in UC4 Script. You can also start JCL lines by using the script statement :DATA. In doing so,
you can keep ! and : as prompt characters.
See: User Guide - Job and Job - Execution
In UC4, you can start Jobs either manually or via control mechanisms such as Workflows or Schedules.
The UC4 Automation Engine then generates an executable Job and sends it to the MPE Agent via a
FileTransfer.
See: Inside UC4 Guide - Executing Objects
The MPE Agent reads the Job and passes it to the MPE Job queue.
The Job notifies the Agent about the beginning and end of an execution. The Agent then passes this
information on to the UC4 Automation Engine.
The Agent monitors the Job's status in regular intervals. This ensures that an abnormal end can be
determined if a Job vanishes (fatal error or ABORTJOB). The Job's return code is available in UC4.
The Job report ($STDLIST) is stored in the file that is specified by the UC4 Automation Engine. If specified
in the Job, the Agent transfers the report to the UC4 Automation Engine which stores it in the UC4
Database. The Agent copies the Job output from the Spooler. Therefore, you must use an OUTCLASS of
priority 1.
Executing FileTransfers
In UC4, FileTransfers are defined and maintained in the form of objects that include various tabs. They are
executed with the character conversions that are defined in these tabs (such as UC_CODE).
See: User Guide - FileTransfer
Event Handling
In UC4, Events are defined and maintained in the form of objects that include various tabs.
Only Events of type File System are currently supported.
See: User Guide - Event
214
Chapter 6 UC4 and Target Systems
6.7 UC4 and NSK
6.7.1 Architecture of the UC4 Agent for the HP NonStop
Server
This document explains a Job run procedure on an HP NonStopServer via a UC4 NSK Agent.
Description of Internal Procedures:
1. Job Start
Job start is initiated by the UC4 Automation Engine which sends the information that the job has started to
the UC4 NSK Agent. The UC4 Agent then creates an entry in the UC4 Status File.
Automation Engine
215
The UC4 NSK Agent sends a message to the UC4 Output Collector (via IPC), which contains the
following information:
l
l
l
l
l
l
user of the Job,
Job file that is to be used,
the virtual terminal that is to be used (if necessary),
priority of the job,
file name of the Job report,
name of the UC4 macro file etc.
The following information is retrieved:
l
l
l
# Location of the UC4 Output Collector, which is to be used as the output file of the Job that is to be
started.
The UC4 Output Collector writes all outputs that were received in this # Location to the
corresponding report file.
Flag whether a re-usable TACL process is available or a new TACL process needs to be started by
the Agent and
The information whether the default user (assumed by the TACLs after the Job has ended) is still
valid.
If required, the Agent starts a new TACL process. This process then logs on to the UC4 Output Collector
(because it has been specified as the output device).
The Output Collector generates the report file. Then, it configures the Job's TACL (setting user, priority
etc). Finally, Job file is assigned to the TACL of the Job as Obey file and commences to process the Job.
2. Job Run
While the Job is running, all the Job-generated outputs are sent to the UC4 Output Collector and written to
the Job reports. If an entry is expected and a terminal has been configured for the Job, the respective entry
is then taken from the terminal.
The connection between the Job report and the Job is established via the # Location which is used by the
Jobs to address the Output Collector.
Hence, outputs of Location $UC4OC.#AAL can be written to the report file $DATA.REPORTS.FFXX, and
outputs of $UC4OC.#AAM to the report file $DATA.REPORTS.FFXY.
Names of # Locations and the report files are assigned by the Agent or the Output Collector.
3. Job End
The Output Collector recognizes that the Job has ended when the TACL process of the Job requires an
entry or closes the Output Collector (if an error occurs). When the Job has ended, the Output Collector
writes this information to the Job's status file and sends the corresponding message to the Agent (via
IPC). Finally, the Agent reports the Job to the Server as finished.
Notes:
1. Meaning of the Status File
The Job's status file facilitates improved Job recovery when the Agent or the Output Collector fails. The
context is then retrieved from the Job's status file in order to restart the troubled process. Many Jobs can
so overcome these troubles and undisturbed processing can be continued. Jobs that have ended during
216
Chapter 6 UC4 and Target Systems
the time of the Agent/Output Collector failure are identified and registered. Hence, the UC4 Automation
Engine always shows a correct image of the system status.
2. Mutual Monitoring
Agent and Output Collector monitor themselves mutually. If one of these two processes ends
unexpectedly (unplanned stop, CPU failure, software failure etc), the surviving process automatically
restarts the failed process. If the CPU of the failed process is not available (anymore), another available
CPU is selected (with preference given to one that differs from the CPU of the surviving process). This
ensures that the system tolerates various errors.
See also:
Agent - Combining UC4 and NSK
6.7.2 Executing Jobs on NSK
UC4 broadly supports HP NonStop systems.
Processes are possible in the following areas:
l
l
l
Guardian - TACL commands
OSS - UNIX commands (osh Shell)
NetBatch - NBEXEC scripts
As these commands differ from each other, 3 types of NSK Jobs are provided. The type of Job object is
selected in the Guardian/NSK tab. It can be read with the script function GET_ATT.
NBEXEC script lines and UC4 Script start with a colon. Therefore, an empty space must be inserted at
the beginning of each -NBEXEC-processing line.
See also:
Guardian/NSK tab
Architecture of the UC4 Agent for the HP NonStop Server
6.7.3 Automated Handling of Input Prompts
Input prompts are often required to drive processing forward. The NSK Agent provides an opportunity to
react to these prompts automatically.
In each individual NSK job, you can specify predefined inputs for particular prompts. If job execution
reaches a prompt, the Agent searches for a predefined input. Processing continues automatically if it finds
one. If prompt handling has not been defined, further processing depends on the specifications that are
made in the Job object. If a virtual terminal has been specified in the Guardian/NSK tab, the prompt is
redirected to it and manual intervention is required. If a terminal has not been determined, the Agent
assigns an EOF input to the prompt.
This function is only supported for NonStop Agent environments and TACL.
Automation Engine
217
Usage
Prompt inputs can be defined using the function UC4_AUTO_ANSWER. In a NSK job script, this function
can be used once or several times. Definitions only apply for one particular job. The syntax is:
UC4_AUTO_ANSWER "Prompt description" "Input"
The first parameter describes the prompt. You can either use the full name or specify wildcards using the
characters ? and *. The latter one serves to use the same input on several prompts without having to enter
an extra script line.
Add the character \ if \, ? or * should be read as normal characters.
The second parameter represents the input that is automatically assigned to the prompt. Enter a string, a
script variable or a TACL expression. You can also use <EOF!> in order to respond to the prompt with an
EOF input (Ctrl Y).
Note that both parameters must not include inverted commas.
The Agent uses the input definitions which already occurred in the script. The search is made in strict
rotation; the first definition that complies with the prompt description is used.
Use the function UC4_AUTO_ANSWER_CLEAN to invalidate all input definitions that occurred in the
script so far. The Agent then searches all definitions starting with this script line. You can use this function
to separate script sections in which different prompt handling should apply. UC4_AUTO_ANSWER_
CLEAN does not have parameters.
The function UC4_AUTO_ANSWER_TRACELEVEL can be used if you require more detailed information
about the search for prompt input definitions. Depending on the specified level, more detailed messages
are written to the job report and the virtual terminal. Its syntax is:
UC4_AUTO_ANSWER_TRACELEVELLevel
Enter a number between 0 and 3 for the level.
0 - No output is made about prompt comparison (default value).
1 - A message is sent for each coinciding prompt comparison.
2 - A message is sent for each non-coinciding prompt comparison.
3 - Output of level 2 and 3 messages
Examples
Example 1
The PURGE statement requires the specification of Y or N. The following script example shows an
automated form of input handling:
UC4_AUTO_ANSWER "PURGE * (y/[n])?" y
PURGE *
UC4_AUTO_ANSWER_CLEAN
The first line defines y as the response to the prompt for the PURGE statement. In doing so, the PURGE
call in the next line is automatically filled with y. Due to UC4_AUTO_ANSWER_CLEAN, this input
definition does not apply for the job's remaining script.
Example 2
Job report abstract of a script which uses the function UC4_AUTO_ANSWER_TRACELEVEL.
UC4_AUTO_ANSWER "*is no prompt*" "Answer 1"
UC4_AUTO_ANSWER "*is a prompt*" "Answer 2"
218
Chapter 6 UC4 and Target Systems
UC4_AUTO_ANSWER "*is what*" "Answer 3"
UC4_AUTO_ANSWER "*is nothing*" "Answer 4"
run $data01.uc4.prompt
This is a prompt>Answer 2
Answer to the prompt received: Answer 2
UC4_AUTO_ANSWER_TRACELEVEL 1
run $data01.uc4.prompt
*** Pattern checked: "*is a prompt*", matched, answer generated: "Answer 2"
This is a prompt>Answer 2
Answer to the prompt received: Answer 2
UC4_AUTO_ANSWER_TRACELEVEL 3
run $data01.uc4.prompt
*** Pattern checked: "*is no prompt*", no match
*** Pattern checked: "*is a prompt*", matched, answer generated: "Answer 2"
This is a prompt>Answer 2
Answer to the prompt received: Answer 2
6.7.4 Agent - Interaction between UC4 and NSK
The NSK Agent works together with the UC4 system via a TCP/IP interface.
The NSK Agent provides the following functions:
l
l
l
Job Processing
Execution of FileTransfers
CallAPI
Processing Jobs
In UC4, Jobs are defined and maintained in the form of objects which include various tabs. Commands
and statements are stored in the Process tab. It can be provided with a complex logic using the UC4 script
elements.
See: User Guide - Job and Job Execution
Depending on the type of command (Guardian, NetBatch and OSS), several sub-types are available for
NSK Jobs.
In UC4, Jobs can start either manually or via control mechanisms such as Workflows or Schedules. Thus,
an executable Job is generated and transferred to the NSK Agent via FileTransfer.
See: Inside UC4 Guide - Executing Objects
Jobs are processed with the Login information (Group name.User name) specified in the Login object
which can be selected in the Attributes tab.
The table below lists password requirements for the Login object.
Agent's User ID
Entry in Login object
Automation Engine
GROUP.USER
A password is required if the Job runs under another group name.user name
GROUP.255
A password is required if the Job runs under another group name
255.255 No password is required
219
Recommended Configuration:
l
l
l
l
Start the NSK Agent with the User ID. SUPER.SUPER is usually not required. User settings must
be adjusted to working requirements.
Define group name.user name in Login objects.
Set parameter logon=1 in the INI file of the NSK Agent.
Specify the default user ERP_LOGIN in the client 0000. Use a valid User ID/password combination
but make surel to select a User who has been assigned very few rights. This User only serves to
equip TACL processes intended to be reused with as few rights as possible. These TACL
processes are then very safe and less error-prone).
Each Job notifies the Agent about the beginning and end of an execution. The Agent then passes this
information on to the UC4 Automation Engine. The Job's return code can be accessed in UC4 via Headers
and Trailers.
Header and Trailer contents are automatically added to the script defined in the Job. The variable
"RETCODE" is defined in an NSK-specific Header. The content of this variable is transferred to the UC4
Automation Engine when the Job ends. This value is the Job's return code. It can be used to define
dependencies between individual Jobs in a Workflow.
The following user-defined Header and Trailer can be used to set the "RETCODE" to "1" if a syntax error
occurs in the script: HEADER.NSK.USER.HEAD, TRAILER.NSK.USER.HEAD and RESTART.NSK
The Agent creates files for Job reports (if specified at the object) and the Jobs on the computer. Their
names are structured as shown in the table below:
Description
Job file
<UC_EX_PATH_TEMP>J<RunID>
Job-report file
<UC_EX_PATH_JOBREPORT>O<RunID>
UC_EX_PATH_TEMP and UC_EX_PATH_JOBREPORT are Agent Variables. The RunID is a string
consisting of 7 to 10 digits which can be used in the Statistics search or converted to the appropriate
number using the script functionALPHA2RUNNR.
Execution of FileTransfers
In UC4, FileTransfers are defined and maintained in the form of objects which include various tabs. They
are executed with their defined character conversion (e.g. "UC_CODE").
Peculiarities: The NSK Agent handles each FileTransfer order with an extra process if the new
FileTransfer protocol is used. The Agent has an additional listener port to provide this function. This port
has the next higher number when compared to the Agent port.
You can specify additional attributes for the target file in the FileTransfer object (target - attributes) or
assume the source file's attributes (option "Keep original file attributes"). The original attributes can be
overwritten with additional definitions in the FileTransfer object. The following NSK file attributes are
supported:
Attribut
Description
220
Chapter 6 UC4 and Target Systems
CREATE_OPTS
Options for file creation, bit mask
(<15> is the lowest bit of a 2-byte
word):
<10>Refresh EOF - has the effect
that the file label is immediately
written to the hard disk.
<11> Index compression - entries in
the index block of key sequenced
files are compressed. For other file
types, use the value 0.
<12> Data compression - keys of
entries in the data blocks of key
sequenced files are compressed.
Value 0 is required for other file types.
<13> Audit compression - data of
audited files is compressed.
<14> Audited - checks the file in the
Transaction Management Facility
(TMF) subsystem. Systems without
TMF require value 0.
<15> Odd unstructured - number of
I/O transfers of unstructured files.
With this option not being set, the
transfers are rounded to an even byte
limit. Other file types require the value
0.
File format
This attribute is automatically set,
based on the file's current size.
1 - for files below 2GB, 2 - for all other
files
FILECODE
Not relevant if only text and binary
files are transferred.
FILETYPE
0 - unstructured
1 - relative
2 - entry sequenced
3 - key sequenced
Not relevant if only text and binary
files are transferred.
KEY_LEN
Not relevant if only text and binary
files are transferred.
KEY_OFFS
Not relevant if only text and binary
files are transferred.
MAXEXT
Maximum number of extents for the
file.
PEXT
Number of 2k pages for the primary
extent.
RECLEN
Not relevant if only text and binary
files are transferred.
Automation Engine
SEXT
221
Number of 2k pages for secondary
extents.
See: User Guide - File Transfer
Call Interface
The CallAPI enables you to execute calls in UC4 from your own programs. You can also use a CallAPI
without any programming being required if you use a utility which you can call from the command line of the
OS or from an executable file, for example.
See also:
User Guide - CallAPI
Inside UC4 - Architecture of the UC4 Agents for the HP NonStop Server
6.7.5 EMS Template File
EMS template files can be used to edit messages in a system compliant way. In doing so, you can define
the SSID (subsystem ID). By default, it is uc4.1.1.
Procedure:
1.) The DDL file (uc4.ddl) must be compiled to a dictionary.
Ensure that within this dictionary, the $SYSTEM.ZSPIDEF.ZSPIDDL and
$SYSTEM.ZSPIDEF.ZEMSDDL have already been compiled.
2.) The TMPL file (uc4.tmpl) must refer to this created dictionary.
Content of the uc4.ddl
CONSTANT zspi-val-uc4 VALUE IS "UC4
".
* Defines subsystem no. part of UC4 subsystem ID
CONSTANT zspi-ssn-uc4 VALUE IS 1.
* Defines version part of Pathway subsystem ID
CONSTANT zuc4-val-version VALUE IS VERSION " 1".
* Defines the structure for the Pathway subsystem ID
* and initializes its parts
DEFINITION ZUC4-VAL-SSID TACL SSID.
02 Z-FILLER TYPE CHARACTER 8 VALUE IS ZSPI-VAL-UC4.
02 Z-OWNER REDEFINES Z-FILLER TYPE ZSPI-DDL-CHAR8.
02 Z-NUMBER TYPE ZSPI-DDL-INT VALUE IS ZSPI-SSN-UC4.
02 Z-VERSION TYPE ZSPI-DDL-INT VALUE IS ZUC4-VAL-VERSION.
END
Content of the uc4.tmpl
VERSION: "UC4 NSK Executor Version 3.02B002 0040 AAD"
DICT:
$DATA01.UC4DICT
SSID:
ZUC4-VAL-SSID
SSNAME: "UC4" , "UC4"
MSG:
ZSPI-TKN,0
"DUMMY"
222
Chapter 6 UC4 and Target Systems
6.7.6 Configuration of NSK-specific Parameters
The NSK Agent can be used to specify NSK-specific parameters in jobs (e.g. the TACL to be used or the
user under which the job report should be created).
Specify the parameters in the following format:
== Parameter=Value
The Agent searches the script for these lines and sets the parameters to the values you specified. TACL
handles these lines as comments.
The following parameters are supported:
Parameter
Description
UC4_TACL_
PROGRAM
Alternative TACL (Shell)
You can specify a different TACL if the standard TACL loads an environment which
should not be used for UC4 jobs. This parameter is also helpful if several clients
access a nonstop machine and require different TACL environments.
The Agent uses the standard TACL if the specified TACL cannot be used and logs
an error message.
UC4_TACL_
TACL process name
PROCESSNAME
UC4_REPORT_
USERNAME
User under which the job report should be created.
UC4_REPORT_
SECURITY
NonStop security string for the Job report
The value "DEFAULT_USER" can also be specified. In this case, the job report is
created for the user under which the job runs.
Use this parameter carefully. An incorrect security string can have the effect
that the Agent cannot read or delete the job report.
Examples:
==
==
==
==
UC4_TACL_PROGRAM=$SYSTEM.SYS03.TACL
UC4_TACL_PROCESSNAME=$CAT2
UC4_REPORT_USERNAME=SQLCMP.SMITH
UC4_REPORT_SECURITY=NNNN
This is an optional function. The Agent uses the particular default values for parameters which have not
been set in the script.
6.8 UC4 and Oracle Applications
6.8.1 UC4 and Oracle Applications
Oracle Applications are e-business solutions for enterprises. These solutions are based on Oracle
databases and include especially designed programs and reports which mostly run in the form of batch
Automation Engine
223
processing in the background. The Agent for Oracle Applications can be used to start and monitor
processes in Oracle Applications, and to assume logs to UC4.
Below is a list which describes the terms which are important in the interaction between UC4 and Oracle
Applications. Detailed information is available in Oracle's user guides.
Terms for Oracle
Term
Description
PL/SQL
PL/SQL is the default language for Oracle databases.
PL/SQL Packages
Packages for PL/SQL can be used in every Oracle database. Additional
packages for Oracle Applications are supplied.
SQL*Plus
Command-line program from Oracle for database access.
Terms for Oracle Applications
Term
Description
Concurrent Processing
Execution of programs and reports in the background.
Oracle Applications provides special software components for "Concurrent
Processing".
Concurrent Manager
System component for the execution and monitoring of tasks in the
background.
Compared to other Enterprise Business Solutions, there can be several
"Concurrent Managers". They can be responsible for various applications or
control the load distribution.
Concurrent Process
Individual instance of a "Concurrent Program". Corresponds to an OS
process.
Concurrent Program
Definition of the "Concurrent Process".
Comparable to the Job definition. This definition contains the reference to the
"Concurrent Program Executable" which should be executed, parameter
definitions and incompatibilities. Incompatibilities are conditions for the
execution such as "Concurrent Program A cannot run at the same time as
Concurrent Program B".
Concurrent Program
Executable
The actual program.
Concurrent Request
Request to the Concurrent Manager to execute a Concurrent Program.
Submit
Concurrent Request
Function which generates a request for the execution of a Concurrent
Process.
Phase
Phase during the execution of a Concurrent Process.
The program can be available as a file or a stored procedure.
Possible phases: PENDING, RUNNING, COMPLETE, INACTIVE
224
Chapter 6 UC4 and Target Systems
Status Particular processes can occur in every phase of a Concurrent Process.
Example: States of the phase PENDING are NORMAL, SCHEDULED or
STANDBY. 6.8.2 Return Codes for OA Jobs
The Agent logs all errors in the job's activation report.
Depending on the stage of job execution, it also sets one of the return codes shown below:
Return
code
Description
0
No error occurred
4
Concurrent Request ended on phase=COMPLETE and status=WARNING.
10
An error occurred when adding specifications using the function OA_ADD_PRINTER, OA_
ADD_LAYOUT or OA_ADD_NOTIFICATION.
100
The script contains an unknown JCL command.
102
An error occurred while processing the statement OA_SUBMIT_REQUEST.
1000
An OCI error occurred.
Use the Job object's Runtime tab to define the return code as of which the job should be canceled.
See also:
About the JCL of Oracle Applications
6.9 UC4 and OS/400
6.9.1 Agent - Interaction between UC4 and OS/400
The OS/400 Agent works together with the UC4 System via a TCP/IP interface.
The OS/400 Agent provides the following functions:
l
l
l
l
l
Job Processing
Remote Status Capturing and Tracking
Execution of FileTransfers
Event Hhandling
CallAPI
Job Processing In UC4, Jobs are defined and maintained in the form of objects that include various tabs. The JCL (CMD,
CL or REXX) is stored in the Process tab. Its logic can be very complex if you make use of UC4's script
Automation Engine
225
elements.
See: User Guide - Job and Job - Execution
In UC4, Jobs start either manually or via control mechanisms such as Workflows or Schedules.The UC4
Automation Engine then generates an executable Job and sends it to the OS/400 Agent via a FileTransfer.
See: Inside UC4 Guide - Executing Objects
In OS/400, you can start Jobs start by using the SBMJOB commandwhich calls the UC4 Job Shell
(IRSTRJOB program in the supplied library). Among other information, the Job Shell obtains the following
parameters - the Job's name that is generated by the UC4 Automation Engine, and the name of the file
member under which the Job has been stored. Depending on the Job type, it executes the following:
l
l
l
CMD
The Job Shell executes every line of the file member. If an error occurs in a particular line, the
severity code is set as the Job's return code and only the Job messenger is called at the Job's end.
ILE CL
The Job Shell converts the file member and creates a temporary CL program. If the conversion is
successful, the Job Shell processes the CL program.
REXX
The Job Shell calls the REXX interpreter and assigns the name of the file member that includes the
REXX script.
Each Job notifies the Agent (Job messenger) about the beginning and end of an execution. The Agent then
passes this information on to the UC4 Automation Engine. The Job's return code is available in UC4.
The Agent monitors the Job's status in regular intervals. This ensures that an abnormal end can be
determined if a Job vanishes (ABEND or CANCEL). This Job is then considered lost within the UC4
system.
The states of Jobs that have been executed while the Agent was terminated are also retrieved. Doing so is
possible because of the start and end messenger outputs.
Note that on OS/400, the JCL is compiled to a program and then executed. An uncontrolled termination
can occur which could have the effect that the Job's status is not correctly displayed. Use the MONMSG
command in order to identify program terminations and to react to them. To use this command, you require
the Job setting "Type" - "ILE CL".
The following example monitors the execution of the JCL by using the MONMSG command and sets the
Job status accordingly:
Pre-Process tab:
! Activates the start and end messenger output for the status recovery.
:SET &UC_QPRINT = 10
! The OS/400 CL command monitors all exceptions and skips to the ERROR
label.
MONMSG CPF0000 (GOTO ERROR)
Process tab:
! Command to be executed by the Job. All active processes are shown in this
case.
wrkactjob *print
! Sets the Job's return code to the value 0.
CHGVAR &RETCODE '0'
! Calls the end messenger.
GOTO END
! The adequate return code is set if an error occurs.
ERROR:
CHGVAR &RETCODE '99'
226
Chapter 6 UC4 and Target Systems
The Job report (Spool) consists of the spool contents (depending on the Job definition only QPJOBLOG or
the entire contents). It is written to a file that is specified by the UC4 Automation Engine. If specified in the
Job, the Agent transfers the report to the UC4 Automation Engine which stores it in the UC4 Database.
Remote Status Capturing and Tracking
You may use the following SQL statement examples to check, if any OS/400 jobs have the status MSGW
(= waiting for messages):
List all jobs in MSGW status:
select count(*) from EH where EH_RemoteStatus = 2006018 AND EH_Client =
&$CLIENT#
Return all necessary information to perform actions on jobs, which are in MSGW status:
select EH_AH_Idnr, EH_RemoteStatus, EH_RemoteStatusIns, EH_Alias from EH
where EH_RemoteStatus = 2006018 AND EH_Client = &$CLIENT#
You may decrease the interval, in which the status of jobs is being checked by changing the value for
JOB_CHECKINTERVAL in the system Variable UC_HOSTCHAR_DEFAULT. Be aware, that a
decrease of this value will affect server performance.
Executing FileTransfers
In AE, FileTransfers are defined and maintained in the form of objects that include various tabs. They are
executed with the character conversions that are defined in these tabs (such as EBCDIC_00037).
For more information see: OS/400 Agent - File Transfer Support
Event Handling
In UC4, Events are defined and maintained in the form of objects that include various tabs. You can define
FileSystem Events that refer to the library file system (QSYS.LIB). The OS/400 Agent also supports
Events of type Console.
See: User Guide - Event
CallAPI
You can use the CallAPI with a utility that can be called by using a CL script, for example.
See: User Guide - CallAPI
6.9.2 OS/400 Agent - FileTransfer Support
There are some peculiarities that must be considered when you use FileTransfers with an OS/400 Agent.
Start OS/400 Agents of version 9.00A or later as a multi-threaded process in order to use the new
FileTransfer protocol. Doing so requires the Agent's JOBD parameter ALWMLTTHD to be set to "YES".
Note that IFS is only supported in combination with the new file transfer protocol.
Automation Engine
227
The new file transfer is handled in threads which includes that you can only use the following file
systems:
l
l
l
l
l
l
l
l
l
"Root" (/)
QOpenSys
User-defined
QNTC
QSYS.LIB
Independent ASP QSYS.LIB
QOPT
Network File System
QFileSvr.400
For the new FileTransfer protocol:
The OS commands CRTPF and ADDPFM are used for transferring the files. This includes that you can
now directly specify the CRTPF parameters in the FileTransfer's attributes.
CRTPF is used when you newly create a file. ADDPFM is processed when the file already exists and you
only want to add a member.
An error that occurs in a FileTransfer which is not clear for UC4 (such as: "CPF0001 - Error found on
ADDPFM command") could represent an error that occurred while these commands have been processed.
In this case, you will find more detailed information in the Job log which is directly stored in the OS.
File Specification
QSYS file system
The following syntax applies for file transfers:
Library name/file name(member name)
The wildcard characters * and ? can be used in file and member names. * stands for any number of
characters (even no character) and ? for exactly one character.
No member name must be indicated if wildcard characters are used in the file name.
Detailed information about wildcards is provided in the chapter that describes partially qualified
FileTransfers.
For example:
To transfer all file members of TEST:
UC4/TEST(*)
or
UC4/TEST()
To transfer all file members of TEST whose names start with the letter "A":
UC4/TEST(A*)
To transfer all file members of TEST whose names consist of 3 characters, start with an "A" and end on
"B":
UC4/TEST(A?B)
To transfer the file member ABC of TEST:
UC4/TEST(ABC)
To transfer all files whose names start with TEST:
228
Chapter 6 UC4 and Target Systems
UC4/TEST*
IFS file system
IFS (Integrated File System) is a UNIX-based file system. IFS files must always be specified with an
absolute path (starting from the root) and a final file name.
If the file specification includes a / character, the Agent assumes that an IFS file is concerned.
For example:
/home/uc4/test.txt
The wildcard characters * and ? can be used to process partially qualified FileTransfers. They can be used
as necessary within the path and/or file name.
In an individual FileTransfer, the path and file name are not case-sensitive. Therefore, the following two
specifications are identical:
/home/AbC.txt
/HOME/ABC.txt
Uppercase and lowercase letters are distinguished in wildcard FileTransfers. The following two
specifications differ from each other:
/home/AB*
/home/ab*
Attributes
Depending on the file system, you can specify all attributes that are supported by OS/400 for the
FileTransfer's destination. Note that you must separate several attributes with a comma. Invalid
specifications are ignored.
QSYS file system
The OS/400 Agent is able to transfer the file types *FILE and SAVF. Other ones such as *PGM, *RPG,
*CLLE must be collected in SAVF files before they can be transferred. The following applies for SAVF file transfers: l
l
Set the attribute reclen=528 in the FileTransfer object's source file.
Select the code page UC_CODE in source and destination file.
For all other files, the following applies:
l
l
If the destination file is not yet available, it will be created. The CRTPF command can be used for
this purpose. Therefore, the attributes that can be specified for the FileTransfer's destination are
parameters of this command.
If no attributes are specified, the file is created with a record length of 80 bytes (default). In wildcard
FileTransfers, MAXMBRS(*NOMAX) is set by default (this means that the file has no member
limit). In individual FileTransfers, the system's default value is used for MAXMBRS.
If the destination file already exists, its attributes can only be overwritten if the option "Keep original
file attributes" is set in the FileTransfer object. The CHGPF command is used for this purpose. You
can specify its parameters as the destination attributes in the FileTransfer object.
The option Keep original file attributes in the FileTransfer object can be used to transfer the source's file
attributes for the destination file(s). Doing so requires the source and destination Agent to have the same
Automation Engine
229
operating system (in this case OS/400) and UC4 version 9.00A (or later). Otherwise, this setting is
ignored.
The following file attributes can be used:
l
l
l
l
l
l
l
l
l
l
l
l
l
l
l
l
ACCPTHSIZ - Access path size
ALWUPD - Allow update operation (ALWUPD). If on, records are not allowed to be updated in the
file (*NO).
ALWDLT - Allow delete operation (ALWDLT). If on, records are not allowed to be deleted from the
file (*NO).
CCSID - Coded character set ID
EXPDATE - Expiration date for member
FRCACCPTH - Force keyed access path
FRCRATIO - Records to force a write
LANGID - Language ID
MAINT - Access path maintenance
MAXMBRS - Maximum members
PAGESIZE - Access path logical page size
RCDLEN - Record length, if no DDS, DDS contains the full record format (Keys, Fields, Relations,
etc.)
REUSEDLT - Reuse deleted records
SHARE - Share open data path
SIZE - Member size, Initial number of records, Increment number of records, maximum increments
TEXT - Text 'description'
The parameter order is irrelevant.
Examples:
This example creates a file with a record length of 256 bytes and enters the text 'FT File' as a description:
RCDLEN(256) TEXT('FT File')
The second example creates a file with a maximum number of members without a size limit and reuses
deleted records:
MAXMBRS(*NOMAX) SIZE(*NOMAX) REUSEDLT(*YES)
Additionally, you can use the specific parameter TRIM=YES in the Attributes field of the FileTransfer's
source. This option is not a real file attribute but a UC4-specific function. It automatically removes blanks
that are used at the beginning and end of each line of the files that should be transferred. This option cannot
be used in combination with the IFS file system.
IFS file system:
The following two original IFS file attributes can be used in the destination file(s):
l
l
l
ccsid - The CCSID used for the data in the file or the extended attributes of the directory.
codepage - The code page derived from the CCSID used for the data in the file or the extended
attributes of the directory.
readonly - Determines whether a read only file is created.
The following example creates a file with the codepage (ccsid) 550 which has the attribute READ-ONLY:
ccsid=550, readonly=YES
IFS: You can also pass the attributes of the original file on to the target file provided that this is defined in
the FileTransfer object. The attributes "readonly", "hidden", "system" and "archive" can also be used
across platforms or from Windows files. You can also override these attributes when you specify the target
file. The attributes "ccsid" and "codepage" only apply to OS/400 files.
230
Chapter 6 UC4 and Target Systems
See also:
FileTransfer tab
6.9.3 Agent - Commands
The Agent is supplied with additional programs and commands. They can be used to start or end the Agent
quickly and easily without creating a CL routine. A program for generating the message library is also
supplied. It is helpful if an error occurs.
Note that you must use the latest Agent of version 9.00A. The library that includes the program files
must have been added to the system's library list. See: Installation Guide of the OS/400 Agent.
Starting the Agent
Supplied objects:
Program: STRUCAGENT
Command: STRUCAGENT
Command for starting any UC4 Agent without creating a CL routine. The library that includes the Agent
must be specified for this purpose. The Agent's INI file must be specified either for the IFS or the QSYS
file system. It replaces the UCEX_RUN routine.
Parameters:
LIB(library)
MBR(QSYS INI file) or PATH(IFS path and INI-file name)
Examples:
STRUCAGENT LIB(UC4) FILE(UC4/INI) MBR(UCXJO41)
Starts the Agent from the UC4 library by using the INI file UC4/INI(UCXJO41).
STRUCAGENT LIB(UC4) PATH('/user/uc4/ucxjo41.ini')
Starts the Agent from the UC4 library by using the INI file ucxjo41.ini which is available in the IFS file path
/user/uc4/.
Ending the Agent
Supplied objects:
Program: ENDUCAGENT
Command: ENDUCAGENT
Ends the Agent that has been started from a particular library either immediately or in a controlled manner.
You can use it instead of the UCEX_END routine.
Parameters:
LIB(library)
OPTION(end)
Examples:
Automation Engine
231
ENDUCAGENT LIB(UC4) OPTION(*CNTRLD)
Ends the Agent that has been started from the UC4 library in a controlled manner. This command has the
effect that the Agent obtains an end signal which is processed soon.
ENDUCAGENT LIB(UC4) OPTION(*IMMED)
Cancels the Agent that has been started from the UC4 library. This command corresponds to the
ENDJOB command. The specified Agent is searched in the system and ends immediately.
Generating the message library
Supplied objects:
Program: MAKEMSL
Command: GENUCMSL
The command GENUCMSL can be used to convert an MSL file that is stored in the IFS file to a physical
message library. The Agent can then use the generated message library. This procedure is not necessary
for installing the Agent but it is helpful for updating or repairing the message library (if an error occurs).
Parameters:
PATH(IFS path and file name)
FILE(QSYS target file)
Examples:
GENUCMSL PATH('/tmp/uc.msl') FILE(UC4/MSL)
Converts the file uc.msl which is provided in the IFS path '/tmp/' to the file UC4/MSL. The number of
imported message records is output:
Processing completed.
Lines processed '34579'.
Imported '11607' english messages.
Imported '11607' german messages.
6.10 UC4 and PeopleSoft
6.10.1 Testing the PeopleSoft Connection
The pscitester program can be used to test the connection to the PeopleTools Application Server.
Pscitester is a PeopleSoft sample program that is supplied as a Java source. It is found in %PS_
HOME%/sdk/PSCOMPINTFC/src/java/samples. You can test it using this example if People Soft can be
accessed with the Java Object Adapter.
The building and testing process of this example program is described below.
Procedure
1.
Installing the Java SDK
232
Chapter 6 UC4 and Target Systems
l
Host
l
Install the Java SDK on a work station (can also be another one than the PeopleSoft server).
2.
l
Add the bin directory <SDK_HOME>\bin to the PATH environment variable. Enter "javac" in the
MS DOS prompt or the terminal to test if the installation was completed successfully. Javac is
output.
3.
l
l
Generating the Java Sources
Select a Component Interface in the Application Designer and click Build -> PeopleSoft APIs. The
Java classes that should be build can be selected now:
CompIntfc.USER_PROFILE
CompIntfc.USER_PROFILE_IDTypes
CompIntfc.USER_PROFILE_IDTypesCollection
CompIntfc.USER_PROFILE_Roles
CompIntfc.USER_PROFILE_RolesCollection
CompIntfc.USER_PROFILE_Roles_RouteControls
CompIntfc.USER_PROFILE_Roles_RouteControlsCollection
CompIntfc.USER_PROFILE_Attributes
CompIntfc.USER_PROFILE_AttributesCollection
CompIntfc.USER_PROFILE_SYNC
CompIntfc.USER_PROFILE_SYNCCollection
CompIntfc.USER_PROFILE_Collection
CompIntfc.CompIntfcPropertyInfo
CompIntfc.CompIntfcPropertyInfoCollection
Deactivate the checkbox for COM Type Library generation and select a folder in the field Java
classes in which the files can be generated. The Java files are generated in a selectable directory in
PeopleSoft/Generated/CompIntfc.
4.
l
Adjusting the PATH Variable
Creating the *.class Files
Create a folder and copy the file psjoa.jar, the directory pscitester and the directory PeopleSoft to it.
The PeopleSoft directory was specified while you created the Java classes. The directory is
structured as follows:
./psjoa.jar
./pscitester/pscitester.java
./PeopleSoft/Generated/CompIntfc/CompIntfcPropertyInfo.java
./PeopleSoft/Generated/CompIntfc/CompIntfcPropertyInfoCollection.java
./PeopleSoft/Generated/CompIntfc/ICompIntfcPropertyInfo.java
./PeopleSoft/Generated/CompIntfc/ICompIntfcPropertyInfoCollection.java
./PeopleSoft/Generated/CompIntfc/IUserProfile.java
./PeopleSoft/Generated/CompIntfc/IUserProfileIdtypes.java
./PeopleSoft/Generated/CompIntfc/IUserProfileIdtypesAttributes.java
./PeopleSoft/Generated/CompIntfc/IUserProfileIdtypesAttributesCollection.java
./PeopleSoft/Generated/CompIntfc/IUserProfileIdtypesCollection.java
./PeopleSoft/Generated/CompIntfc/IUserProfileRoles.java
./PeopleSoft/Generated/CompIntfc/IUserProfileRolesCollection.java
./PeopleSoft/Generated/CompIntfc/UserProfile.java
./PeopleSoft/Generated/CompIntfc/UserProfileIdtypes.java
Automation Engine
l
./PeopleSoft/Generated/CompIntfc/UserProfileIdtypesAttributes.java
./PeopleSoft/Generated/CompIntfc/UserProfileIdtypesAttributesCollection.java
./PeopleSoft/Generated/CompIntfc/UserProfileIdtypesCollection.java
./PeopleSoft/Generated/CompIntfc/UserProfileRoles.java
./PeopleSoft/Generated/CompIntfc/UserProfileRolesCollection.java
./PeopleSoft/Generated/CompIntfc/IUserProfileRolesRoutecontrols.java
./PeopleSoft/Generated/CompIntfc/IUserProfileRolesRoutecontrolsCollection.java
./PeopleSoft/Generated/CompIntfc/UserProfileRolesRoutecontrols.java
./PeopleSoft/Generated/CompIntfc/UserProfileRolesRoutecontrolsCollection.java
./PeopleSoft/Generated/CompIntfc/IUserProfileCollection.java
./PeopleSoft/Generated/CompIntfc/UserProfileCollection.java
./PeopleSoft/Generated/CompIntfc/UserProfileSync.java
./PeopleSoft/Generated/CompIntfc/UserProfileSyncCollection.java
Change to this directory by using the MS DOS prompt or the terminal and set the CLASSPATH:
l
For Windows: set CLASSPATH=.;psjoa.jar
For Unix: export CLASSPATH=psjoa.jar:.
Transmit the example with:
233
javac pscitester/pscitester.java
5.
l
l
l
Starting the Pscitester Program
Required is a running Application Server to which the program can connect.
Enter the JOLT port in the test program. It is found in the file %PS_
HOME%\APPSERV\<APPSERVERNAME>\psappsrv.cfg under [JOLT Listener].
Start the program:
java pscitester.pscitester
The following error message can be ignored:
java.lang.NullPointerException: PSProperties not loaded from file.
If this message should not be displayed, copy the file pstools.properties from the PeopleSoft server
to the current directory.
l
The following output displays if all entries were made correctly:
Application Server Connect Information...
Enter The Application Server Name: wgw2ksps2
Enter The Application Server Port Number[ 9000]:
Enter PeopleSoft UserID [PTDMO]: PS
Enter PeopleSoft UserID Password: [PTDMO]: ********
Connected to Appserver...
Get on Component Interface "USER_PROFILE" succeeded
Listing Component Interface property for field "UserID"
Long Label: User ID
Short Label: User
Is Collection: false
Type: 0
Format: 6
Is Key: true
Is Required: false
Is Xlat: false
234
Chapter 6 UC4 and Target Systems
Is YesNo: false
Is Prompt: false
6.10.2 Using Bind Variables
PeopleSoft processes can include bind variables. You can use UC4 in order to schedule these processes
and assign values to them.
The two functions PS_SET_BINDVAR and PS_RUN_PROCESS interact with each other and can be
used as described below:
l
l
PS_SET_BINDVAR replaces a value that you can either predetermine in UC4 Script or retrieve via
a Run Control ID.
Subsequently, you can call the script function PS_RUN_PROCESS in order to start and monitor a
process. In doing so, bind variable values are considered.
Using this function requires the PeopleTools database to be configured. The individual steps are explained
in the installation chapter.
UC4 strongly recommends extensive tests being made for Jobs that replace values for bind variables
before they are used in the production system. The values have a particular format (such as the date
format) that must be kept. Extensive testing is essential because the particular spelling can differ and
cannot be checked.
6.10.3 Changes in Run Controls
Most processes require parameters (e.g. a period) for execution. This information can be stored in Run
Controls (RUN_CONTROL_RECORDS). Processes retrieve their execution parameters from the
corresponding Run Control.
Usually, a Run Control is a single database record in the PeopleSoft database. It can also comprise
several data records. Unique Run-Control identification is guaranteed with the two keywords OPRID (User
ID) and RUN_CNTRL_ID.
Use
UC4 provides the function PS_MODIFY_RUNCONTROL which can be used to modify Run Controls.
Modification in this case refers to an individual data record. If several data records of Run Controls need to
be maintained, make an individual PS_MODIFY_RUNCONTROL call for each modification. The UC4
procedure differs from online maintenance in PeopleSoft.
Examples
Example 1
Automation Engine
235
A user wants to process the SQR report "Employee Turnover Analysis" and therefore creates the Run
Control "myRunControl". After adding the Run Control, the parameter fields required for the report are
entered and stored. The relevant fields are FROM_DATE and THRU_DATE.
UC4 can automate this modification by retrieving the user ID from the PeopleSoft job's Login object.
PS_MODIFY_RUNCONTROL RUNCONTROLID='myRunControl',RECORDNAME='RUN_CNTL_
HR',FIELDNAME='FROM_DATE',FIELDVALUE='20050306'
PS_MODIFY_RUNCONTROL RUNCONTROLID='myRunControl',RECORDNAME='RUN_CNTL_
HR',FIELDNAME='THRU_DATE',FIELDVALUE='20060306'
Example 2
The following example shows a Run Control for currency conversion. In this case, fields and values are
provided in list form (currency list).
In order to change currency values, a key must also be assigned when calling PS_MODIFY_
RUNCONTROL
PS_MODIFY_RUNCONTROL RUNCONTROLID='myRunControl',RECORDNAME='RUN_CNTL_CC2_
EO',FIELDNAME='RATE_MULT',FIELDVALUE='100',KEYNAME(1)='CURRENCY_
CD',KEYVALUE(1)='EUR'
The data of the currency list is provided in level 1. Thus, indicate the number 1 in the parameters
KEYNAME(1)= and KEYVALUE(1)=.
236
Chapter 6 UC4 and Target Systems
Risks and limitations
Keep the following recommendations in mind when changing Run Controls:
l
l
l
l
l
Assigned values are only occasionally checked. Thus, wrong values can exist in the PeopleSoft
database and cause one or several components to no longer work online. This error can only be
removed with SQL commands.
Although no inconsistency will arise in the data model, values can exist in the database which
cannot be recorded online. PeopleCode prohibits the collection of a running date from the previous
year, for example. Use the function PS_MODIFY_RUNCONTROL to enter this kind of data.
PS_MODIFY_RUNCONTROL does not create new Run Controls because the relevant database
table fields are also filled by PeopleCode and can depend on each other. Neither UC4 nor the
PeopleCode interfaces for UC4 recognize this dependency.
In fact, dependencies between the fields of a Run Control are not considered and can lead to
malfunctions in the PeopleSoft application.
Run Controls can write more than one data record. For example, the component RUN_CNTL_CC_
EO (Currency Conversion) writes to the tables PS_RUN_CNTL_CC1_EO and PS_RUN_CNTL_
CC2_EO. It is the user's personal responsibility to fill the data records with the correct names.
See also:
PS_MODIFY_RUNCONTROL
6.11 UC4 and SAP
6.11.1 SAP Solutions and Job Scheduling with UC4
If you are running SAP solutions and need an effective job scheduling solution, consider the UC4
Automation Platform. Enabling the fast, seamless integration of SAP applications into enterprise
scheduling, the UC4 Automation Platform supports all SAP applications, including SAP R/3, mySAP
Business Suite, and SAP NetWeaver, as well as industry-specific solutions for telecommunications,
banking and more. As a result, IT processes in any SAP application can be centrally managed and
monitored seamlessly alongside the rest of your global operation.
Because it is specially designed as an Enterprise Scheduler, UC4 does not require middleware
components such as a JAVA Application Server and provides top scheduling functionality for your whole
IT infrastructure. The system is directly linked to the SAP NetWeaver component SAP Web Application
Server, accelerating the design and implementation of jobs for SAP applications. Reports, variables, and
other necessary parameters are made available via the UC4 Automation Platform's easy-to-use, intuitive
graphical user interface (GUI). Problems resulting from manual errors, typos, or outdated report lists are
effectively eliminated. Jobs are created using a simple drag & drop functionality, and visualized graphically
to ensure clarity and simplify management and control.
In addition to offering SAP users total job scheduling automation, the UC4 Automation Platform further
increases the productivity of SAP business solutions. By centrally tracking and automating background
jobs and processes of SAP solutions, the UC4 Automation Platform ensures that performance is improved
by optimizing background processing and reducing system interruptions and errors.
Automation Engine
237
See also:
UC4 Automation Platform and SAP NetWeaver
6.11.2 SAP NetWeaver
UC4 Automation Platform and SAP NetWeaver
This documentation follows the SAP NetWeaver architecture and explains UC4 functions based on it.
Functions for business and custom solutions are also explained.
People Integration
This section about SAP NetWeaver is meant to support end users. This is done via user-friendly interfaces
which move responsibilities for process starts with correct parameters to the particular operating
departments.
UC4 functions
Integration in SAP Enterprise Portal (iViews)
WebInterface
Information Integration
Warehouse Management is the core of this section. Data loading processes and process chains are under
UC4 control and are even integrated in other platforms using superordinate processes. Automatic analysis
and display of the individual processes of a chain to the lowest level are taken for granted.
238
Chapter 6 UC4 and Target Systems
UC4 functions
Scheduling Data Loading Processes
Scheduling Process Chains
Scheduling Queries in Batch Mode
Process Integration
This section is about integrating business processes in the SAP Exchange Infrastructure (SAP XI). Being
the Integration Broker, messages can release and re-release processes directly via the SAP XI Standard
Adapter.
UC4 functions
Monitoring SAP XI Communication Channels
Application Platform
The application platform is the basis of all SAP applications. UC4 uses ABAP and Java in order to provide
useful functions.
UC4 functions
ABAP:
Executing Jobs in ABAP Stack (CCMS)
Child Processes
Intercepted Jobs
Evaluating the Application Return Code of SAP Steps
Variant Management
BDC Management
Spool Management
Handling Events
Transferring SAP Jobs
Transferring SAP Calendar Definitions
JAVA:
Java EE/JMX Agent for SAP NetWeaver
JMX in SAP NetWeaver
Executing Jobs in Java Stack (JXBP)
Lifecycle Management
This section provides the means for controlling and monitoring all solutions on the basis of the SAP
NetWeaver technology. UC4 can access all monitored data while also supplying it own data.
Automation Engine
239
UC4 functions
Monitoring Monitors
Monitoring SAP NetWeaver
Integrating UC4 in the SAP Solution Manager
Registering to System Landscape Directory
Switching Operation Modes
Viewing System Log and View Application Log
Application Development
UC4 also supports the development of applications in various ways.
UC4 functions
ABAP:
CallAPI for SAP
JAVA:
UC4.ApplicationInterface
People Integration
Integration in SAP Enterprise Portal (iViews)
Introduction
The UC4 iViews for Job Scheduling supply current information about Job Scheduling to the SAP
Enterprise Portal component of the SAP NetWeaver so that critical business processes can be started by
end users.
Tasks can be started and monitored directly from the SAP Enterprise Portal. End users can start important
processes and set the corresponding parameters if necessary. Not knowledge about Job Scheduling is
required. Each user can monitor the current status of the background processing via the SAP Enterprise
Portal. Started processes are then managed and monitored by the UC4 Automation Platform. The current
status is made available to the user via the iView technology.
See also:
Starting Tasks
Monitoring Activities
Starting Tasks
With the iView "ActivateObject", users can start executable objects in UC4. For that purpose, the name of
the object and the description of the task need to be specified in the personalization settings. It is also
240
Chapter 6 UC4 and Target Systems
important to indicate the system alias which must comply with the term the administrator defined in the
system settings.
Different UC4 systems can be accessed via system aliases.
The object can now be activated with the Start button. The iView shows the run number (RunID) of the
current or last execution. Follow the link "Detail" and the Detail Window provides further information upon
start time and return code, similar to the UserInterface.
The iView generates an input mask if user input is required for the execution of an object (e.g. if the script
element :READ is used). Red stars "*" symbolize mandatory fields.
See also:
Monitoring Activities
Automation Engine
241
Monitoring Activities
The iView "Activities" shows the activities of the UC4 system that were started by the particular user. As
in the UserInterface are task priorities, start times and states available.
Information about the activities can only be read. Changes such as canceling or editing tasks are not
possible via iView.
It is possible to adjust the view to your personal requirements by hiding some of the columns, for example.
Do so in the personalization settings and note that it is important to indicate the system alias. It must
comply with the term the administrator specified in the system settings.
See also:
242
Chapter 6 UC4 and Target Systems
Starting Tasks
Information Integration
Scheduling Data-Loading Processes
An InfoPackage is an object which describes the selection conditions for requesting data from a source
system. This object can be scheduled and then controls the data-loading process from the source system.
InfoPackages can be externally controlled using a standard interface. UC4 uses this interface.
6.11.3 UC4-JCL for SAP
Script Element
Description
BW_ACTIVATE_
INFOPACKAGE
Schedules one or more InfoPackages for immediate start.
BW_GET_
INFOPACKAGES
Reads InfoPackages from the BW system. Available InfoPackages are
stored in the activation report or a file.
BW_SET_
INFOPACKAGE_
SELECTION
Sets selection parameters which are used for reading the InfoPackages
from the BW system.
Scheduling Process Chains
Operations can be displayed in your BW system via process chains. A chain includes a start process,
individual application processes and collected processes. Including InfoPackages is also possible.
UC4 can be used to start and monitor process chains. The individual processes are then displayed in the
UserInterface's Activity Window. Process logs are stored in the report of the UC4 Job object.
Automation Engine
243
6.11.4 UC4 JCL for SAP
Script Element
Description
BW_ACTIVATE_
CHAIN
Starts a process chain, monitors its execution and stores the corresponding logs in
the activation report.
BW_GET_
CHAINS
Reads process chains from the BW system. Available process chains are stored in
the activation report or a file.
BW_RESTART_
CHAIN
Continues an aborted process chain.
244
Chapter 6 UC4 and Target Systems
Scheduling Queries in Batch Mode
The transaction RSCRM_BAPI can be used to create queries for your BW system. The result is stored
either in a table or a file. Use UC4 to make queries either regularly or upon request.
In the first step, log on to the BW system and call the transaction RSCRM_BAPI. Schedule the query to
be automated with UC4 once. Each query has its own batch ID. Open the batch monitor and copy this
number.
Now create a SAP job in your UC4 system. Use the Form tab or write the following function directly into
the Process tab:
R3_ACTIVATE_REPORT REP='RSCRMREPORT_BAPI'
Now change to the SAP tab and enter the copied BatchID in the field Job name.
Automation Engine
245
This Job object can now be integrated in your processing (e.g. in a Schedule object) and will process the
query at the point in time you define.
It is a SAP peculiarity that the batch monitor does not display all query executions but only the last one.
Process Integration
Monitoring SAP XI Communication Channels
SAP XI adapters are used to exchange data with the SAP Exchange Infrastructure. They transform
messages so that they can be forwarded via communication channels.
The SAP Agent provides functions which can be used to handle adapters:
l
l
l
Starting communication channels
Stopping communication channels
Querying information about communication channels
246
Chapter 6 UC4 and Target Systems
The functions XI_GET_CHANNEL and XI_SET_CHANNEL can be used in SAP jobs. Information about
communication channels is stored as an XML document in the job report. The script elements for XML
format this data.
Communication channels can also be monitored via Event objects of type "Console". An Event is triggered
whenever the status changes.
Activate the XI interface with the SAP Executor's INI-file parameters in the section [SAP_XI].
A Login object with valid login data is required for accessing the XI system. The XI user must be
authorized to control the XI communication channels. We recommend using different Login objects for
SAP and XI system if both are installed on the same host. Otherwise, the Login entry is not unique.
6.11.5 UC4 JCL for XI
Script elements
Description
XI_GET_CHANNEL
Lists communication channels
XI_SET_CHANNEL
Starts and stops communication channels
Application Platform
ABAP
Job Management
Automation Engine
247
6 Executing Jobs in ABAP Stack
(CCMS)
UC4 and its functions can be used in various ways in order to support processing in SAP. Job objects are
the basis for defining statements which should be processed in the SAP system.
The Form tab is the graphical interface that is connected to the SAP system and facilitates the definition
of processing statements through the direct selection of data (e.g. variants).
UC4 facilitates the execution of:
l
l
l
l
l
l
Jobs
Reports
External commands
External programs
Intercepted Jobs
etc.
The Activity Window in the UserInterface shows task states. Tasks can be restarted or canceled if
requested. Child processes are also displayed. When a task has ended in UC4, you can access its report
which also includes SAP system messages.
It is not only the Job object which facilitates processing in the SAP system. The object type
"RemoteTaskManager" can also be used to monitor and start jobs in SAP. It is especially useful for
Intercepted Jobs.
248
Chapter 6 Executing Jobs in ABAP Stack (CCMS)
6.11.1 UC4 JCL for SAP
Script Element
Description
R3_ACTIVATE_EXT_COMMAND
Executes an external command
R3_ACTIVATE_EXT_PROGRAM
Executes an external program
R3_ACTIVATE_INTERCEPTED_
JOBS
Executes Intercepted Jobs under UC4 control
R3_ACTIVATE_JOBS
Executes SAP-scheduled jobs under UC4 control
R3_ACTIVATE_REPORT
Executes the specified report
R3_GET_JOBS
Selects SAP jobs and lists the result in the activation report or
a file
R3_MODIFY_JOB
Modifies an ABAP step
R3_SCHEDULE_JOB_CANCEL
Resets a released SAP job to the status "Planned"
See also:
Child Processes
Intercepted Jobs
RemoteTaskManager
Automation Engine
249
6 Child Processes (JOBD)
SAP jobs can contain one or several subjobs (e.g. in process chains). UC4 can display these child
processes in its Activity Window. They have their own statistical records and reports.
The Parent-Child function can be activated in the transaction "SE38" using the program INITXBP2.
The object type of child processes is JOBD.
Set the parameter REPLICATE=YES in the relevant script elements to have the child processes
replicated in your UC4 system.
Note that child processes can also have child processes. These can be seen in the Parent column of
the Activity Window and the statistical overview.
The illustration below shows the execution of a process chain:
The item "Status text" in the Detail Window of child processes shows the SAP system's instance number.
Deactivating child processes is possible in the corresponding parent processes.
SAP jobs have a special tab called Child Post Process. It is processed when an individual child process
ends. In doing so, the result can immediately be analyzed.
A statistical record and a report are created for each child process. Both can be called via the statistical
overview of the parent process.
250
Chapter 6 Child Processes (JOBD)
The report is structured in the same way as the report of the top parent process but it contains only
information about the particular process step.
The job report settings are also valid for the top parent process (database, file, on error only). Additionally,
the report length can be specified using the parameters JOBLOG=, PROCESSLOG= and LONGTEXT= of
the script elements BW_ACTIVATE_CHAIN and BW_RESTART_CHAIN.
6.11.1 UC4 JCL for SAP
Script Element
Description
BW_ACTIVATE_CHAIN
Starts a process chain
BW_RESTART_CHAIN
Continues an aborted process chain
R3_ACTIVATE_INTERCEPTED_JOBS
Executes Intercepted Jobs under UC4 control
R3_ACTIVATE_JOBS
Executes SAP-scheduled jobs under UC4 control
R3_ACTIVATE_REPORT
Executes the specified report
See also:
Child Post-Process Tab
Automation Engine
251
6 Intercepted Jobs
Filter criteria can be defined in the table TBCICPT1 of SAP jobs. These criteria include the specification of
a client, job name and user. If a user indicated in this table starts a job which meets the specified filter
criteria, the job status changes to "Scheduled" regardless of the defined start mode (e.g. "Immediately").
The Intercept function can be activated in the transaction "SE38" using the program INITXBP2.
Click the
symbol in the "Form" tab of SAP jobs to access the table and maintain its entries (XBP 2.0)or
use the Criteria Manager (XBP 3.0).
Table entries can also be changed dynamically using the script element R3_MODIFY_
INTERCEPTION.
There are two ways of executing Intercepted Jobs:
1. Use the RemoteTaskManager to control and monitor Intercepted Jobs
2. Use R3_ACTIVATE_INTERCEPTED_JOBS
3. Use R3_GET_INTERCEPTION to read the table. The result is stored to a file which can be
accessed with PREP_PROCESS_FILE.
You can specify the maximum number of jobs which can run parallel when you start Intercepted Jobs
individually with a group being indicated as start type.
6.11.1 UC4 JCL for SAP
Script Element
Description
R3_ACTIVATE_
INTERCEPTED_JOBS
Executes Intercepted Jobs under UC4 control
R3_GET_INTERCEPTION
Reads the filter table for Intercepted Jobs and stores them in the
activation log or a file
R3_MODIFY_INTERCEPTION
Modifies the filter table for Intercepted Jobs
See also:
Form tab
252
Chapter 6 Evaluating the Application Return Code of SAP Steps
6 Evaluating the Application Return
Code of SAP Steps
A SAP job step can also have an application return code.
You can access it as described below:
6.11.1 Via a script element
R3_GET_APPLICATION_RC can be used to check the application return code of one or several job steps
and cancel the UC4 Job if required.
6.11.2 Via the step list report
This specific report type contains information about the steps plus the application return code. The return
code can be read using the XML script elements.
Example:
:SET &xmlreport# = XML_OPEN(REPORT,,SSTP)
! Reading the first element
:SET &job# = XML_GET_FIRST_CHILD(&xmlreport#)
:SET &name# = XML_GET_NODE_NAME(&job#)
:PRINT "First element: &name#"
! Reading the second element
:SET &child# = XML_GET_FIRST_CHILD(&step#)
! Reading the step's children
:WHILE &child# <> ""
:SET &name# = XML_GET_NODE_NAME(&child#)
! Reading the application return code
:IF &name# = "RC"
: SET &applrc# = XML_GET_NODE_TEXT(&child#)
: PRINT "Applicationreturncode: &applrc#"
:ENDIF
:SET &child# = XML_GET_NEXTSIBLING(&child#)
:ENDWHILE
:XML_CLOSE
6.11.3 Via the report
Information about SAP job steps is logged in the job report. This report also informs about the application
return code if you use the UC4 Interface.
"Appl-RC n/a" is written to the job report if a step has no application return code.
Use the script function PREP_PROCESS_REPORT to read and further process application return
codes.
In the following example, the ABAP ZZ_TEST_APPL_RC is called in a job once. Its application return
code should be read.
Automation Engine
253
! Select the line containing ABAP and the application return code.
:SET &HND# = PREP_PROCESS_REPORT(,,REP,"*ZZ_TEST_APPL_RC*Appl-RC*")
:PROCESS &HND#
:
SET &ZEILE# = GET_PROCESS_LINE(&HND#)
!
Find the exact position in a line where the "Appl RC" starts.
:
SET &POS_STR# = STR_FIND(&ZEILE#,"Appl-RC")
!
The application return code is located after 8 characters.
:
SET &POS_ARC# = ADD(&POS_STR#,8)
!
Read the application return code.
:
SET &ARC# = STR_CUT(&ZEILE#,&POS_ARC#)
!
Check if the step really supplies an application return code.
:
IF &ARC# <> "n/a"
!
The read value is a string and must therefore be converted to a
number.
:
SET &ARC# = CINT(&ARC#)
!
Beyond this point there are any script statements which further
process the application return code.
:
PRINT &ARC#
:
ENDIF
:ENDPROCESS
The application return code is not available with the XBP interface.
Variant Management
Variants facilitate processing in SAP as jobs can be processed with ready-set input values. UC4 supports
the use of variants by offering various functions for reading, copying or modifying variants. Deleting and
listing them are also possible.
It is important that variants are checked and set just before an ABAP program is processed in order to
exclude error sources.
6.11.4 UC4 JCL for SAP
Script Element
Description
R3_ACTIVATE_REPORT
Executes a report with a specified variant
R3_COPY_VARIANT
Copies a report variant
R3_CREATE_VARIANT
Creates a new variant
R3_DELETE_VARIANT
Deletes a report variant
R3_GET_VARIANT_CONTENTS
Shows the content of a variant
R3_GET_VARIANTS
Lists all available variants in the activation log
R3_MODIFY_VARIANT
Modifies a variant entry
254
Chapter 6 Evaluating the Application Return Code of SAP Steps
BDC Management
Batch input is a proven technique for transferring mass data from external systems to the SAP system.
The batch input sessions used contain one or several transaction calls including transaction data. UC4
can read, process and monitor these sessions until they end. UC4 can also directly call transactions
whose data has been defined in a UC4 Job (call transaction).
6.11.5 UC4 JCL for SAP
Script Element
Description
R3_ACTIVATE_
SESSIONS
Processes batch input sessions
R3_CALL_
TRANSACTION
Calls a SAP transaction
R3_GET_SESSIONS
Selects batch input sessions and lists the result in the activation report or
a file
R3_SET_BDCDATA
Defines BDC data
Spool Management
UC4 is able to handle and process job outputs. This is done via Job object specifications and script
elements.
The SAP tab in SAP jobs can be used to enter spool list recipients. All spool requests created by the job
are sent to the recipients specified in this tab.
Automation Engine
255
6.11.6 UC4 JCL for SAP
Many script elements have parameters which can be used to handle job outputs. The following functions
serve to handle spool requests:
Script Element
Description
R3_CREATE_OUTPUT_REQUEST
Creates a new output request for an existing spool request
R3_GET_JOB_SPOOL
Reads the spool list of a step of type "ABAP program".
Filter specifications are possible.
R3_GET_SPOOL_REQUESTS
Selects spool requests with predefined filters
R3_SEND_SPOOL_REQUEST
Sends an existing spool request
Event Management
Modern business applications demand that process management is event aware. Traditional predefined
and time-based process control systems do not meet the requirements of modern complex application and
system environments and their ever-increasing interdependencies.
With UC4.Event UC4 offers a sophisticated solution for event-aware process management. Processing
can be performed depending on a variety of real-time system conditions and events. UC4.Event offers this
functionality for a variety of OS and application platforms. Definition and modification of events takes
place centrally and is platform-independent, ensuring ease of use by the authorized user.
256
Chapter 6 Evaluating the Application Return Code of SAP Steps
The SAP background control also provides event control. Events can trigger appropriate SAP background
processes. SAP events are enhanced with a UC4 implementation, enabling maximum business process
flexibility and extended management functionality.
6.11.7 SAP Event
A SAP event is a flag that is defined in transaction SM62. A defined event can be triggered (manually, with
an OS job or an ABAP program), causing the execution of a background process.
There are two types of SAP events:
l
l
System events
Defined by SAP and automatically triggered if system events occur such as the activation of a new
operation mode. System events cannot be modified.
User events
Defined by users. These events must be triggered by ABAP or external programs. For example, an
external program can signal to the SAP background processing that external data is ready to be
imported to the SAP system.
6.11.8 UC4 support
UC4 supports SAP events and integrates them into its centralized process management. This solution
can be helpful if the SAP background control works with a large number of defined events and a conversion
to a UC4 implementation with Workflows and UC4.Event would be too complex and time-consuming.
For most applications it makes sense to replace SAP events with the UC4 solution.
UC4 can use SAP events for its process management. The execution of UC4 objects can depend on the
occurrence of a SAP event. For example, particular processes can depend on a successful data import.
UC4 can trigger SAP-defined events. The full UC4 functionality is available for defining trigger conditions
and points in time for a SAP event. Upon the occurrence of such an event the appropriate processes in the
SAP system are started.
It is also possible to use an Event object of type "Console". The Agent monitors the triggered SAP events
and forwards the information to the Console Events. Filters can be used to specify SAP events which
should trigger subsequent processing or an information message.
Automation Engine
257
6.11.9 UC4 JCL for SAP
Script Element
Description
R3_GET_EVENT
Waits for a SAP-triggered event
R3_RAISE_EVENT
Triggers a SAP-defined event
See also:
Monitoring SAP Events
Criteria Manager
The SAP Criteria Manager can be used to define conditions for the Event History, Event History Reorg and
Job Interception in the form of profiles.
You can directly access the Criteria Manager in the SAP job.
Functions: l
l
l
Creating and deleting profiles
Activating and deactivating profiles
Adding, modifying and removing conditions
In the Form tab, click on the button
to open the Criteria Administrator.
XBP 3.0 is required to access the SAP Criteria Manager.
258
Chapter 6 Evaluating the Application Return Code of SAP Steps
6.11.10 UC4 JCL for SAP
Script element
Description
R3_ACTIVATE_CM_
PROFILE
Activates a profile in the SAP Criteria Manager
R3_DEACTIVATE_
CM_PROFILE
Deactivates a profile in the SAP Criteria Manager
Transferring SAP Jobs
UC4 Job objects can be used to define new SAP Jobs and also to transfer existing SAP Jobs to UC4. The
advantage is clear: The job must only be created once.
Jobs can only be transferred if there is a UserInterface connection to the SAP system.
Open a Job object and select the Form tab. The upper left edge shows several buttons. Click the symbol
. A window opens in which you can enter filters for SAP Jobs such as name or job number etc.
Now click on the button Find. All Sap Jobs that correspond to the specified filter criteria are listed.
Highlight the Job to be transferred to UC4 and Click OK tab.
The Job object adopts the statements the job contains. Parameters such as the variant or output device
are automatically added as shown below:
Automation Engine
259
If jobs are transferred to UC4, they are not removed from the SAP system. Job settings are read and
copied to the UC4 Job object.
This method of transferring jobs is very useful if only a few jobs are affected. If many jobs are to be
transferred, UC4 recommends using the UC4.ApplicationInterface.
If you plan to transfer masses of jobs, do so carefully and get a general idea first. In most cases, the
number of jobs has increased in the course of time; they can often be reworked, simplified or even
replaced.
See also:
Transferring SAP Calendar Definitions
Assuming SAP Calendar Definitions
SAP provides the transaction SCAL for defining factory calendars. The UC4 interface contains an ABAP
program which can be used to export these calendars as XML files. These files can then be transferred to
your UC4 system. Special calendar definitions are considered.
The ABAP program "/SBB/UC4_CALE_GET" can be opened as soon as the UC4 Interface has been
imported (refer to the installation guide for SAP Agents). Enter the factory calendar's ID and information
concerning your UC4 system as shown below:
260
Chapter 6 Evaluating the Application Return Code of SAP Steps
The two checkboxes on bottom of the above form serve to determine whether the calendar definition
should be generated as a spool list or XML file. ln the latter case, a dialog opens in which the folder the can
be selected to which the XML file should be stored.
Import the XML file to your UC4 system. The factory calendar is now provided in the form of a Calendar
object.
Automation Engine
261
Script elements can also be used to assume Calendars automatically.
See also:
Calendar
Importing and Exporting Objects
UC4 JCL for SAP
JAVA
Java EE/JMX Agent for SAP NetWeaver
Java Management Extensions (JMX) is a technology that provides a series of instruments for handling and
monitoring applications, devices and networks.
The UC4 Automation Platform provides a JMX Agent that can be used to integrate Java applications into
enterprise-wide processes. Connections are established via an MBean Server and several functions
provide access to these MBeans.
SAP NetWeaver's standard supply contains more than 1600 MBeans that can directly be handled. Java
does not require predefined proprietary "jobs". No Scheduler is required within Java because UC4 takes
over this function. Due to this standard, this function is also executable on Java sources of other vendors.
262
Chapter 6 Evaluating the Application Return Code of SAP Steps
A Requirements Checklist in the documentation provides information about all supported application
servers.
UC4 script elements can be used to register, list and remove MBeans. MBean functions can be called, and
attributes and information can be read and set.
The Job object's Form tabprovides a graphical interface in which all functions are available.
See also:
Form (JMX) tab
About the JMX JCL
JMX in SAP NetWeaver
The UC4 JMX Agent facilitates using MBeans in SAP NetWeaver.
6.11.11 Monitoring the Java EE Engine
The status of the Java EE Engine can be queried via JMX. The output information is also displayed in the
Visual Administrator under Server -> Services -> Monitoring.
Automation Engine
263
All the Visual Administrator's functions are provided via MBeans and can also be used in UC4.
Limitation: UC4 cannot use JMX operations or attributes that use SAP-specific classes (for example,
com.sapmarkets.bam.application.User) or complex data structures such as lists, maps, or arrays.
The UC4 MBean Browser in the JXM Job displays a maximum of 300 MBeans. A search filter facilitates
the search for particular MBeans (right-click the tree structure -> apply filter...).
For example: The number of unsuccessful login attempt should be queried. The first illustration shows this
value below the node Security -> Aggregated Data. Therefore, you can filter for "*Security/Aggregated
Data/UnsuccessfulLogonAttemptsCount*" in the MBean Browser. Exactly one MBean is returned in the
UC4 environment.
Here you can select one of the following attributes: "Value", "MaxValue" or "MinValue". A UC4 Job can be
scheduled that queries the number of error messages periodically.
6.11.12 Starting and stopping a service
The Visual Administrator also configures, starts and stops services. As it also uses JMX MBeans, this
function is available via the Agent.
Services are listed in the Visual Administrator under Server -> Services:
For example: The Telnet service should be started or stopped.
You can filter "*SAP_Java EEServicePerNode*" in order to have all services displayed in the MBean
Browser. The returned MBeans correspond to the corresponding services.
264
Chapter 6 Evaluating the Application Return Code of SAP Steps
All services have a "start" and "stop" method. Select the entry "telnet" from the tree structure. Then select
the method "stop". Click OK to generate a UC4 Job that stops the Telnet service:
The modification is immediately visible in the Visual Administrator:
Automation Engine
265
Executing Jobs in Java Stack (JXBP)
UC4 provides the following opportunities for the handling of jobs in the SAP Java Scheduler:
l
l
l
l
Start jobs using parameters
Cancel jobs
Include the logs in the job reports
Monitor jobs via filter using the RemoteTaskManager
First, the Java job definition must be deployed in the Java Schedule to make it visible to the SAP Agent.
Subsequently, you can use a Job object to create an instance from an existing job definition.
A SAP Job object always belongs to exactly one Java job definition.
Create a SAP job object for Java Scheduler jobs and select a SAP Agent plus a Login object. Use the
Form tab to select the job definitions to be applied. The lower part of the tab automatically displays the
corresponding parameters.
The Job log tab contains the following options:
l
l
l
Delete after x days - The job log is deleted from the Java Scheduler after x days.
Do not remove - The job log is not removed from the Java Scheduler.
Use default settings - The period after which the job log is deleted from the Java Scheduler depends
on the settings made in the job definition.
The job log is always deleted together with the job instance.
266
Chapter 6 Evaluating the Application Return Code of SAP Steps
6.11.13 Report for Java statistics
A processed SAP Job object can also contain a report (SJJI) which includes information about the Java
job. Activate this function by checking the relevant checkbox in the area Optional reports in the Job
object's SAP tab.
6.11.14 Installation
Creating the external Schedulers in SAP:
1.
2.
3.
4.
5.
6.
Use the Web interface to log on to the SAP NetWeaver Administrator.
Select the Job tab.
Click the link "Java Scheduler" -> "External Scheduler".
Insert a new entry in the list of registered external Java Schedulers ("Add").
Complete the fields. Specify "UC4 Automation Platform" for the name and the description.
Click on Add.
Creating a Connection object in UC4:
1.
2.
3.
4.
5.
6.
7.
8.
9.
Log on to system client 0000.
Create a new Connection object for SAP.
Open the Connection object and select the connection type "Internet" in the Attributes tab.
Switch to the Internet tab and specify the connection data for the SAP Java Scheduler. Indicate the
user that was used to add UC4 as an external Scheduler.
Store and close the Connection object.
Switch to the folder HOST and open the SAP Agent's object.
Select the Connection object in the Agent tab in the field Java Basis.
Store and close the Agent object.
Restart the SAP Agent if it is currently running.
6.11.15 Special cases
In an environment of several nodes, the Java Scheduler jobs are processed on the node on which the
Scheduler Service is active. If this node is deactivated or fails, job processing continues on a different
node. The Agent periodically attempts to re-establish the connection to the Java Scheduler if it has been lost
during job execution. The job remains active in the UC4 system and obtains the status "Waiting for remote
system".
The job aborts if calling the Java Scheduler results in an error. In this case, there is no report about the
Java job's statistics. The error is logged in the Job object's report "Agent Log" and in the SAP Agent's log
file. The job aborts with return code 403.
Restarts are not possible. The complete Job starts in the Java Scheduler because there is no UC4 JCL.
Automation Engine
267
6.11.16 Return codes
SAP status
Job return code in UC4
COMPLETED
HOLD
RUNNING
SCHEDULED
STARTING
UNKNOWN
0
ERROR
501
CANCELED
502
Lifecycle Management
Monitoring SAP NetWeavers
Monitoring Monitors
SAP offers various monitors that can be used to monitor the SAP environment including corresponding
components. The function R3_GET_MONITOR reads the provided information and makes it available for
further processing.
The following example reads the monitor "All Monitoring Contexts" and stores its content to a text file:
R3_GET_MONITOR MONITOR_SET="SAP CCMS Technical Expert Monitors",
MONITOR="All Monitoring Contexts", FILE="C:\UC4_and_
SAP\AllMonitoringContexts.txt"
Use the script function PREP_PROCESS if only parts of the monitored information should be filtered.
Based on these filter specifications, the script function supplies a data sequence which can then be
processed. The SAP Agent lists the monitor's information in columns. The following example filters lines
with the content "Enqueue". Four columns are used for further processing:
:SET &HND# = PREP_PROCESS("SAP01","R3MONITOR","*Enqueue*","MONSET=SAP CCMS
Technical Expert Monitors","MONNAM=All Monitoring Contexts","COL=FILE","UC_
LOGIN=LOGIN.SAP")
:PROCESS &HND#
:
SET &Context# = GET_PROCESS_LINE(&HND#, CONTEXT)
:
SET &Name# = GET_PROCESS_LINE(&HND#, NAME)
:
SET &Value# = GET_PROCESS_LINE(&HND#, VALUE)
:
SET &Status# = GET_PROCESS_LINE(&HND#, STATUS)
:
PRINT "&Context# --- &Name#"
:
PRINT "Value: &Value#"
:
PRINT "Status: &Status#"
:
PRINT ""
:ENDPROCESS
The above example calls the function R3_GET_MONITOR in the background. Refer to the document that
describes the script function PREP_PROCESS for more detailed information.
The RemoteTaskManager object also provides monitoring functions in the SAP system. Depending on
the specified filter criteria, it displays jobs triggered by SAP.
268
Chapter 6 Evaluating the Application Return Code of SAP Steps
6.11.17 UC4 JCL for SAP
Script Element
Description
R3_GET_MONITOR
Reads the data of a SAP monitor
Monitoring SAP Events
Events are significant in SAP's background processing. Event objects of type "Console" can be used to
monitor SAP Events.
The Agent periodically polls the SAP system for occurred SAP Events and reports them to the active
Console Events in an interval the UC4 administrator has defined in the UC4 Variable UC_
HOSTCHAR_DEFAULT, key JOB_CHECKINTERVAL.
Filters are available which serve to define the SAP Events to be monitored. The statements defined in the
!Process tab initiate further processing steps as they are processed when an Agent reports a SAP Event.
Use the function GET_EVENT_INFO in the !Process tab. It supplies details about the SAP Event that
has occurred.
Several filter lines can be specified in the table in the tab's lower area. !Process is processed if a SAP
event is triggered which meets at least one filter specification. !Process is NOT processed several times if
several filter specifications are met.
Overlapping filters can occur if several Console events are used. The Agent would then notify all Console
events about the relevant SAP event.
UC4 does not only provide Console Events but also functions which can be used to handle SAP
Events via Job objects. R3_GET_EVENT waits for a SAP-triggered Event and R3_RAISE_EVENT
can be used to trigger a SAP-defined Event.
Automation Engine
269
6.11.18 Procedure
1. Create an Event object of type "Console".
2. Open it and switch to the Console tab. Specify the Agent that is connected to the SAP system and
the filter criteria for the SAP Events.
3. In the !Process tab, enter the script statement to be processed if a SAP Event occurs which meets
the specified filter criteria. The script function GET_EVENT_INFO supplies details about the SAP
Event.
4. If required, fill in the other tabs of the Console Event and store the object.
5. Now activate the Console Event in order to include SAP Events in your processing.
6.11.19 Notes
XBP 3.0 is required in order to monitor SAP Events of Event type "Console". The UC4 administrator
can specify the XBP 3.0 interface in the SAP Agent's INI file.
If the Agent loses its connection to the SAP system, SAP Events can accumulate as the Agent is not able
to forward them to the Console Events. As soon as the connection has been re-established, the Agent
checks if there are SAP Events and reports them to the affected Console Events.
Due to the fact that huge data amounts can be involved, the Agent does not read all SAP Events at
once. The UC4 administrator can define the required handling in the Agent's INI-file parameter
maxEventTimeSpan= .
The Agent cannot monitor SAP Events if it is terminated. After a restart, it retrieves the point in time when
it last monitored SAP Events and also reports SAP Events that occurred during its termination.
All Agents connected to the SAP system poll SAP Events. This means that each Agent reports all
SAP Events which occurred to the Console Events.
If the SAP system's time runs behind UC4's system time, the first SAP events cannot be received if
they occur in the gap between the two different times.
See also:
Event Management
Sample Collection - Reaction to External Events
SAP Adaptive Computing Controller
UC4 Supports SAP ACC
Adaptive Computing refers to the dynamic assignment of hardware resources with the aim of making them
available for services. The SAP Adaptive Computing Controller (ACC) is an application which is based on
the Java EE Engine of the SAP Web Application Server. It is used to start and stop services etc. UC4 is
able to establish a connection to SAP ACC and in doing so supports the handling of services. An MBean
provides this function which can be called via the UC4.Agent for Java EE/JMX.
The Agent must be installed in "stand alone" mode (without application server).
270
Chapter 6 Evaluating the Application Return Code of SAP Steps
Functions of the MBean "ACC":
l
l
l
Starting a service
Stopping a service
Moving a service
Users log on to the Adaptive Computing Controller from within the Job's Login object. The relevant
authorizations for using a service are required.
See also:
Using the MBean ACC
Using the MBean ACC
The MBean "ACC" is supplied with the JMX Agent. Installation is required.
MBean
Description
Name
UC4:name=ACC
Automation Engine
Attributes
271
"ACC_URL" - Address of the Adaptive Computing Controller in the format
http://Host:HTTP-Port/ACCGW/ACC or https://Host:HTTPS-Port/ACCGW/ACC
"ServiceID" - ID of the service
"Host" - Name of the physical host
"ForceStartOnSmallServers" - Indicates whether or not the service should also start on
hosts that do not meet service requirements. Allowed values: "YES" and "NO" (default
value)
"ReplyLog" - Indicates whether or not the complete log should be returned. Allowed values:
"YES" (default value) and "NO"
Operations "start" - Starts the service on the specified host. The ACC selects a suitable host if the
attribute "Host" has not been specified.
"stop" - Stops the service. The attribute "Host" is ignored because the ServiceID is unique.
"relocate" - Stops the service and starts it on the specified host.
6.11.20 Procedure
It is easy to use MBeans:
1. Register the MBean with JMX_CREATE_MBEAN.
2. Set attributes such as the ServiceID either using the function JMX_SET_ATTRIBUTE or JMX_
COMPOSITE_ADD. We recommend using the second function. If several JMX jobs run parallel, it
can happen that they access the MBean's instance and mutually overwrite values. JMX_
COMPOSITE_ADD may be used to define values in a list which is then assigned to the MBean in
collective form. In doing so values cannot be overwritten.
In the function JMX_COMPOSITE_ADD, the KEY= represents the attribute's name and the
VALUE= the attribute's value.
3. Now use the function JMX_INVOKE to select the required operation.
6.11.21 Examples
Starting a service
The service "MYSERVICE" should be started on PC01.
! Registering the MBean
JMX_CREATE_MBEAN
EXISTS="IGNORE",CLASSNAME="com.uc4.sap.ACC",NAME="UC4:platform=SAP,name=Ada
ptiveComputingController"
! Setting attributes
JMX_COMPOSITE_ADD NAME="attribute",KEY="ACC_
URL",VALUE="https://sap03:50001/ACCGW/ACC"
JMX_COMPOSITE_ADD NAME="attribute",KEY="ServiceID",VALUE="MYSERVICE"
JMX_COMPOSITE_ADD NAME="attribute",KEY="Host",VALUE="pc01"
JMX_COMPOSITE_ADD
NAME="attribute",KEY="ForceStartOnSmallServers",VALUE="YES"
! Calling the MBean
JMX_INVOKE MBEAN="UC4:name=ACC",OPERATIONNAME="start", PARAMS="attribute"
Stopping a service
272
Chapter 6 Evaluating the Application Return Code of SAP Steps
The service "MYSERVICE" should be stopped. The ServiceID is unique, therefore it is not necessary to
specify the host name.
! Registering the MBean
JMX_CREATE_MBEAN
EXISTS="IGNORE",CLASSNAME="com.uc4.sap.ACC",NAME="UC4:platform=SAP,name=Ada
ptiveComputingController"
! Setting the attributes
JMX_COMPOSITE_ADD NAME="attribute",KEY="ACC_
URL",VALUE="https://sap03:50001/ACCGW/ACC"
JMX_COMPOSITE_ADD NAME="attribute",KEY="ServiceID",VALUE="MYSERVICE"
! Calling the MBean
JMX_INVOKE MBEAN="UC4:name=ACC",OPERATIONNAME="stop", PARAMS="attribute"
Moving a service
The service "MYSERVICE" should be stopped and restarted on a different host. The relevant values are
defined using script variables.
! Registering the MBean
JMX_CREATE_MBEAN
EXISTS="IGNORE",CLASSNAME="com.uc4.sap.ACC",NAME="UC4:platform=SAP,name=Ada
ptiveComputingController"
! Setting the attributes
JMX_COMPOSITE_ADD NAME="attribute",KEY="ACC_URL",VALUE="&url#"
JMX_COMPOSITE_ADD NAME="attribute",KEY="ServiceID",VALUE="&service#"
JMX_COMPOSITE_ADD NAME="attribute",KEY="Host",VALUE="&host#"
! Calling the MBean
JMX_INVOKE MBEAN="UC4:name=ACC",OPERATIONNAME="relocate",
PARAMS="attribute"
6.11.22 Return codes
A JMX job aborts if an error occurs. It obtains a return code which refers to the error. The report contains
the corresponding error message and shows the log (unless the attribute "ReplyLog" has been set to
"NO").
l
l
l
l
l
l
l
l
l
l
l
l
l
l
0 - No error occurred
1 - Invalid ServiceID
2 - Invalid host name
3 - Invalid command
4 - Service has been locked, no operation possible
5 - Too many services on the selected host
6 - Request timeout
7 - The Server does not meet service requirements.
8 - The service cannot be started.
9 - The service cannot be stopped.
10 - The service exceeds the maximum instance limitation.
11 - Server has been locked, no operation possible
12 - Automatic Server selection: No Server is available or there is no Server which meets service
requirements.
97 - The CCI user does not have sufficient authorizations (see role concept which has been
introduced with SP4).
Automation Engine
l
l
273
98 - XML parser error
99 - Unknown error (see log entry for more details)
See also:
ACC Support
Analyzing System and Application Logs
UC4 can be used to read SAP application logs as well as the system log.
Both log types supply information about processing in general and possible error situations. UC4 provides
functions which serve to read the corresponding entries using filters, and store them in a report or file. The
result can be analyzed using PREP_PROCESS and PREP_PROCESS_FILE.
A particularity that applies to the system log is that aborted jobs can store their last system log lines in the
special SLOG report. This makes error analyses much easier. The number of lines to be kept as well as
other settings are defined in the SAP Agent's Connection object.
6.11.23 UC4 JCL for SAP
Script Element
Description
R3_GET_
APPLICATIONLOG
Retrieves messages from the application log and prints them in report or
file form
R3_GET_SYSTEMLOG
Reads the system log of a SAP system during a defined period of time
Integrating UC4 with the SAP Solution Manager
The SAP Solution Manager is supplied with all SAP systems starting from the Web Application Server
(WAS) 6.10. It is meant to become the central monitoring software for SAP systems, but also for external
applications. This should provide for the centralization of all services within a SAP environment.
With the SAP Agent, UC4 integrates the entire enterprise-wide process management in the SAP Solution
Manager.
6.11.24 Monitoring
The essential functionality of the SAP Solution Manager is centralized monitoring. The monitoring part
again distinguishes two main areas:
l
l
Operations
Business process monitoring
While the first one primarily deals with technical processes and system status, the area of business
process monitoring helps to design and monitor logical business processes in and around SAP systems.
274
Chapter 6 Evaluating the Application Return Code of SAP Steps
6.11.25 Operations monitoring
In the area of operations monitoring the SAP Solution Manager uses the existing monitoring infrastructure
within the CCMS (Computing Center Management Systems). The states of systems and processes are
displayed in a tree structure.
So far these monitors have been limited to SAP systems. Now SAP provides interfaces for external
applications for reporting status data to the Solution Manager and for displaying them in the monitoring
tree.
The SAP Agent uses such an interface in order to access the monitor structure in the CCMS. It uses a
Connection object for ABAP Basis. Several script elements can be used to create and modify attributes or
delete nodes:
Script Element
Description
R3_DELETE_NODE
Deletes a node
R3_SET_LOG_ATTR
Sets a log attribute
R3_SET_PERF_ATTR
Sets a performance attribute
R3_SET_STATUS_
ATTR
Sets a status attribute
R3_SET_TEXT_ATTR
Sets a text attribute
The Form tab of SAP jobs can be used to access nodes. A separate browser displays the monitor "All
Monitoring Contexts" of the monitor set "SAP CCMS Technical Expert Monitors". The node colors
represent the current alarm status.
Automation Engine
275
6.11.26 Business process monitoring
Business processes are based on individual IT processes and systems. Interdependencies can be defined
and graphically represented with the SAP Solution Manager. All data which is available in operations
monitoring can be used to model business processes.
UC4 centrally controls processes on all of an enterprise's systems and applications. The integration of
UC4 in the SAP Solution Manager provides the opportunity to represent and monitor enterprise-wide
business processes in a SAP system.
If an error occurs in a business process, the reason can be found immediately. The time for troubleshooting
is minimized, the business process can be restarted as quickly as possible.
6.11.27 Process management
The Solution Manager will also be able to manage background processes. Currently, this function is
available using the transactions SM36 and SM37.
UC4 comprehensively supports this function. UC4 centrally manages and monitors the entire SAP
background processing. UC4 also combines these SAP processes with processes of all the enterprise's
other systems and applications.
Registering to System Landscape Directory
SAP's System Landscape Directory (SLD) supplies an overview of installed software components. You
can configure the SAP Agent in a way that it registers at the SLD whenever it starts.
The following steps are required:
276
1.
2.
3.
4.
5.
6.
7.
8.
Chapter 6 Evaluating the Application Return Code of SAP Steps
Log on to system client 0000.
Create a new Connection object for SAP.
Open the Connection object, click theAttributes tab and select the connection type "Internet".
Switch to the Internet tab and specify the SLD connection data.
Store and close the Connection object.
Switch to the folder HOST and open the SAP Agent's object.
Select the Connection object in the Agent tab, field System Landscape Directory.
Store and close the Agent object.
The SAP Agent now tries to register at the SLD whenever it starts. It can successfully start even if a
registration is not possible (e.g. due to incorrect connection parameters).
The SAP Agent's log file contains a message which indicates whether the registration to the SLD was
successful.
Switching Operation Modes
SAP's operation modes support the optimal use of available system resources. Various specifications can
be defined for dialog and background processing, according to the time of day. No R/3 system restart is
required for this method of resource allocation.
UC4 also supports this SAP function. Use the script element R3_SWITCH_OPMODE to switch operation
modes for individual or all SAP application servers.
6.11.28 UC4 JCL for SAP
Script Element
Description
R3_SWITCH_OPMODE
Switches the operation mode in SAP
Automation Engine
277
6.11.29 SAP Banking
UC4 Process Management and SAP for Banking
In cooperation with major European banks, SAP has developed an account management solution with
SAP for Banking. UC4 developers have been working on integrating this new SAP solution into the wellproven UC4 process management.
The result is the UC4.Agent for SAP AM/BCA which provides comprehensive process management
power for banking transactions. UC4 integrates the new SAP solution into its centralized process
management and secures business processes at enterprise-wide level and across all platforms.
Processes in SAP for Banking
A particular feature of SAP Transaction Banking is that entire processes can be stored in the Customizing.
The process definition corresponds to a kind of job plan (tabular maintenance). These processes are
mainly called end-of-day processes.
When controlling these processes you must consider the following factors:
Process network
A process network is created and monitored via a menu function from within a process definition in
Customizing. It has a unique ID which must be specified for each run. A process network contains a set of
processes. A process is an application function which technically is always processed in two steps:
1. The actual application function
2. The application's monitoring part. The monitoring part is only executed if the process has been
initiated via a process network.
The entire application (including the monitoring part) can be processed synchronously or asynchronously.
Synchronous processing
The application function including monitoring is processed synchronously from within a function module
i.e. the function module ends synchronously with the application function.
Asynchronous processing
The application function and the monitoring are both started as background jobs with the monitoring job
always following the application job.
Processes with parallelization
Paralleled processing (similar to IS-U/IS-T) is provided for particular processes (with mass data).
Unfortunately there is no basic functionality for this kind of request.
A process with parallelization creates parallel background jobs i.e. a parallel background job and a
subsequent monitoring job. If the process starts asynchronously, an additional parent job is created
(followed by a monitoring job) which is active for the entire runtime of the process.
Application return code and application log
Processes have an application return code. A normal technical status (e.g. Job ended) cannot sufficiently
ensure successful processing. The individual components of a process (function module, ABAP,
monitoring ABAP, etc.) are also written to an application log.
278
Chapter 6 Evaluating the Application Return Code of SAP Steps
Starting process networks and processes
Process networks are integrated in dialog functions and initiated by them. Depending on the individual
application, processes are initiated synchronously or asynchronously (jobs running a long time are always
asynchronous).
Requirements for UC4
A UC4 Workflow corresponds to the processing definition in SAP's Customizing. Workflow tasks
represent processes.
SAP's basic job control does not provide the appropriate means to control processes in AM/BCA.
Standard background jobs are not suitable for controlling individual processes as the application function's
monitoring part would not start. Thus, no application return code would be created.
Adjusting all application programs in a way that the monitoring function could run implicitly would have
been counterproductive. It would have resulted in many programs and the application return code would
have been communicated via the job log.
The alternative was to create a process network with an individual ID for each task in the SAP system
from within a UC4 Workflow. This process network always contains only one process. If this process
starts via the process network, two asynchronous batch jobs are created in the SAP system – the
application function and the monitoring function.
New script elements are available in UC4 for controlling such processes (BCA_ACTIVATE_PROCESS).
In order to enable UC4 monitoring (status checks), SAP has extended its interface by a corresponding
function.
UC4 functional description
Starting and monitoring processes
This function uses a single process in a process network, while also starting and monitoring it. When the
process ends, the process network also ends because it only contains this single process.
Analyzing application return codes
Single processes supply application return codes. UC4 can analyze them (e.g. in post script) and react to
them.
Analyzing application logs
Processes of a process network write to application logs. Unfortunately, there is no 1:1 relation between a
process or process network and an application log.
Thus, the UC4 analysis of application logs provides different information.
This UC4 function can be used to select application logs according to particular criteria (the results are log
numbers). Application log messages and texts can then be read using these log numbers. Text outputs are
written to a text file or report.
Integration into job networks
UC4 integrates processes in SAP AM/BCA into enterprise-wide job plans. Interdependencies with
processing in other SAP or non-SAP systems can easily be implemented and monitored.
Comprehensive statistics
Automation Engine
279
Comprehensive statistics are provided for all UC4-controlled processes. They can be used for later
analyses and future planning. This also applies to processes in SAP for Banking.
UC4 JCL for SAP
Script Element
Description
BCA_ACTIVATE_
PROCESS
Starts and monitors a process which runs in a separate process
network.
6.11.30 SAP Financial Closing Cockpit
Integrating UC4 in SAP Closing Cockpit
The SAP Financial Closing Cockpit can be used to schedule several tasks that should be executed in a
particular order and at a particular point in time. Through the integration of UC4, you can activate objects of
a UC4 system via Closing Cockpit tasks.
Requirements:
UC4.Internal Webservice
The UC4.Internal Webservice can be used with the following application servers:
l
l
l
l
Sun Glassfish v2, 3
JBoss 5.0
IBM WAS CE 2.0
SAP Netweaver CE 7.1
Use the installation guide to set up the required application server. Make sure to use the current version
of the UC4.Internal Webservice.
SAP version
SAP Basis requires a particular or a later support package version depending on the SAP release
version which is used.
Release
Package name
700
SABKB70017
701
SABKB70101
710
SABKB71007
Another requirement is SAP ERP version 6.00.
Supplied files Refer to the file SAP_CloCo.zip.ucc in the directory CD:FRAMEWORK\SAPCLOSINGCOCKPIT which
contains the supplied files in encoded form.
280
Chapter 6 Evaluating the Application Return Code of SAP Steps
Installation
1.
l
Decoding the supplied file
Use the program UCYBCRYP.EXE for decrypting the file SAP_CloCo.zip.ucc. It is stored in the
folder CD:\TOOLS\ENCRYPT of the UC4 CD. Now call the program via the command line using
the following parameters:
UCYBCRYP.EXE -d -f SAP_CloCo.zip.ucc -lLicense file
The license file was supplied by our support team (customer number.TXT).
l
l
The result is the packed file SAP_CloCo.ZIP.
Unpack the file SAP_CloCo.ZIP.
2.
Loading SAP transports
Specific ABAP programs are required for the integration process. Load them to the SAP system by means
of an import. The archive SAP_CloCo.ZIP includes two corresponding files.
l
l
KNNNNNN.SID - Information file
KNNNNNN.SID - Data file
Copy these files to the transport directory of SAP (e.g.: /usr/sap/trans/). Copy the K file to the subfolder
"cofiles" and the R file to "data".
Log on to the SAP system and import the relevant request using the transaction STMS. Open and check
the request's transport protocol after the import process: all steps have to show the return code 0
(successfully ended) or 4 (ended with warning).
3.
Configuring the HTTP RFC connection
Call the transaction SM59 and select "HTTP connections to the external server". Now create a new
connection.
Enter a name for the RFC destination (e.g.: UC4_WEBSERVICE) and a description.
Tab: Technical settings:
In the field Target host, enter the host name of the application server where the UC4.Internal Webservice
runs. Enter the port number in the field Service number.
Tab: Logon and Security:
Select the option Basic authentication. Specify the data for accessing the UC4 system: in the field User,
enter the UC4 client, user name and the department (separated by a slash). Now enter the password and
store the RFC connection.
Automation Engine
4.
Defining the logical port
Start the transaction SOAMANAGER
1. Select the link "Web Service Configuration" ("Service Administration" tab)
2. Search for the object type "Consumer Proxy" which includes *UC4* as the name.
281
282
Chapter 6 Evaluating the Application Return Code of SAP Steps
3. Create a new logical port with the name UC4.
4. In the "Consumer Security" tab fields "User" and "Password", enter the login data for the
Automation Engine system:
Use the following syntax for the user name: <client>/<user>/<department>. For example:
0001/USER/DEV
As the password, use the password of the defined Automation Engine user.
5. In the "Messaging" tab, set the "Message ID protocol" field to the value "Suppress ID Transfer".
Automation Engine
283
6. "Transport Settings" tab: In the field "URL Access Path", enter the value ""/uc4ws/uc4ws?wsdl".
Also set the computer name and the port of the Webservice's Application Server.
Use SOAP 1.1 as the "Transport Binding Type"
Store and activate the logical port.
5.
Registering the ABAP report for the Closing Cockpit
Call the transaction SM30 and open the table SCMAPROGRAMS for modifications ("Maintain"). Add a
new entry with the following values:
Column
Value
Program
/UC4/CC_
REPORT
Application
CUSTOMER
Store this new entry.
284
Chapter 6 Evaluating the Application Return Code of SAP Steps
6.
Testing the connection
Start the program UC4/CC_REPORT via the transaction SE38 to test the connection from ABAP to the
UC4 system.
See also:
UC4.Internal Webservices
Activating UC4 Objects with SAP Closing Cockpit
The integration of UC4 in the Closing Cockpit is the key to the activation of executable UC4 objects via
tasks in the SAP Financial Closing Cockpit. The corresponding installation guide is provided in the chapter
Installing the SAP Financial Closing Cockpit Integration. This document describes the general mode of
operation and use.
After a successful UC4.Internal Webservice installation and Closing Cockpit integration, you can assign
executable UC4 objects to the Closing Cockpit templates. The required steps and the execution behavior
are described below.
Configuration
Log on to the SAP system and call the transaction CLOCOC. Open a template (Edit) and select the
command "Add task" via the context menu from any location in the organization structure. Specify all
required values in the displayed dialog. Select "Program" for the option Type of task and enter /UC4/CC_
REPORT in the corresponding field. Now select or create an appropriate variant.
This variant stores the name of the UC4 object to be executed. All other fields are optional and will be
passed on to the activated object as additional values via the read buffer.
Automation Engine
285
Call the input assistance (F4) for the field Name of a UC4 object to display all executable UC4 objects of
the client that was specified in the particular RFC connection. Name, type, title and path of the objects are
displayed.
286
Chapter 6 Evaluating the Application Return Code of SAP Steps
The additional fields in the variant dialog can be used to pass additional values on to the activated UC4
object. The names of the script variables that are provided for the UC4 object in the input buffer are listed
below:
Parameter/Field
Name of the UC4 script variable
Controlling area
KOKRS
Period
PERIO
Fiscal year
GJAHR
The additional parameters can be used to write self-defined values to the read buffer. The column UC4
Variable defines the name of the read buffer variable.
The values of this script variable can be read using the script element :READ in the script.
Example:
:READ&KOKRS#,,'KOKRS',
Store the variant and the task. Now create a task list from the template.
Automation Engine
287
Execution
Use the transaction CLOCO to execute task lists of the Closing Cockpit. Open a task list that includes
UC4 object activating tasks. Include these tasks and check their states.
If a task has been executed and its status is shown in SAP as "Completed", then it ended with the status
ENDED_OK in the UC4 system. Every other UC4 status causes the output "Error" in the Closing Cockpit.
To display the UC4 Job report, open the spool of the relevant task in the Closing Cockpit. This spool
includes all UC4 report types (ACT, REP, LOG,...) and the RunID of the executed UC4 task.
In the configuration of the Closing Cockpit (CLOCOC), you can also define dependencies for tasks that
start programs or transactions. Do so by opening a template or task list and calling the view
"Dependencies". Tasks can be inserted in this Dependency area via drag and drop. This function is also
supported in tasks that call UC4 objects. A dependency can be used to determine that a task can only
start when a particular task has ended.
See also:
UC4 Integration in SAP Closing Cockpit
6.11.31 SAP Solution Manager
SAP Solution Manager Integration
You can use the SAP Agent to access a UC4 system with the SAP Solution Manager and read various
information or manage processes in the UC4 system. This document explains the configuration process
and the details of this integration.
Some functions are not directly available in the Solution Manager but by setting up a specific
integration, you can call the UserInterface directly from the Solution Manager and quickly access these
functions. For further details about the affected functions and how to configure the integration, see
Setting up the UserInterface Integration.
Configuration
To use the SAP Solution Manager for UC4, you must define the settings for the SMSE (Solution Manager
Scheduling Enabler) inferface in the Agent's Connection object. Then restart your SAP Agent.
288
Chapter 6 Evaluating the Application Return Code of SAP Steps
Functionality
When you have successfully completed the configuration process, you can run the following UC4
functions with the SAP Solution Manager:
Function
Description
Reading clients
This provides a list of all a UC4 system's clients and their
descriptions.
Canceling tasks
The available commands are cancel, stop, stop (recursive), go,
go (recursive).
Retrieving the states of tasks
This queries the status of a certain activity.
Reading folders
This supplies a list that includes the ID, the folder name, the
folder title and the name of the superordinate folder.
If the name of the folder or the parent folder exceed a length of
80 characters, they will be truncated. The title has a maximum
length of 255 characters. Special folders such as the Recycle
Bin, Transport Case, <No Folder> etc. are not part of the list.
Retrieving a list of SAP systems
This retrieves the name and the description of a certain client's
SAP Agents. The additional description contains the basic SAP
version and the Agent's UC4 version.
Querying a list of Queues
This queries the object name, the title and the max. slots of the
Queues.
Retrieving the executable object
types
This retrieves a list that includes the types and a description of
the executable objects (such as CALL - Notification).
Retrieving the executable objects
This retrieves a list that includes the names and the object types
of the executable objects.
You can specify a certain folder whose objects should be listed.
You can also filter for the name or the object type.
Retrieving the status filter
This retrieves a list of status groups that are used to filter
activities (such as ANY_OK or ANY_ABEND).
Querying a list of activities
This queries the content of the Activity Window of the particular
client.
You can define a status filter and a sorting order (ascending or
descending) in order to limit the results.
The time and date fields (such as the start time) are converted to
UTC and displayed. The system assumes that the actual time
zone in UC4 complies with the local time zone.
Retrieving a task's list of reports
This provides a list that includes all a task's reports and outputs.
This lists contains the report type (such as REP or ACT) and the
output type ("L" = job log, "S" = spool list, "A" = application log,
"O" = other).
Reading a report content
This retrieves the report content of a task.
Automation Engine
Retrieving the user of a task
289
This retrieves the name and the department of the user who has
started the task.
It is read from the statistical details. If the name exceeds a
length of 40 characters, it will be truncated.
Reading the prompt parameters of an
object definition
The following parameters can be read:
Reading the parameters of a task
This reads the name and the value of an activity's object and
PromptSet variables (detail - object variables).
Creating or delete BAE events in
UC4
This creates or deletes BAE events as UC4 Sync objects.
Reading BAE events from UC4
This retrieves the Sync objects that represent BAE events
(object type = SYNC, archive key 1 = SMSE).
-) The name of the PromptSet object
-) The reference variable
-) The type of the PromptSet element ("N" = number, "D"
= timestamp, "S" = all other types)
-) The value of the PromptSet element
-) The property "Value required" ("X" = the option is set, " " = the
option is not set or not known)
-) An input assistant is available Eingabehilfe verfügbar ("X"
= yes, " " = no or not known).
The UC4 Sync objects that represent BAE events have the
value "SMSE" as their archive key 1. This includes that you can
search and filter for these specific objects. The Sync objects
have only two states: CLEARED (initial state) and RAISED.
You can filter for the object name.
Retrieving the status of BAE events
This is the current status of a Sync object that represents a BAE
event. The Sync monitor is read for this purpose. The object title
is returned as a description.
Possible values: R (RAISED) or C (CLEARED)
Querying BAE event instances
This is a list of the tasks that wait for a Sync that represent a
BAE event. It is also read from the Sync monitor.
Reading Notifications
This reads the monitor of active or ended Notification objects.
The following details will be returned:
-) Subject
-) Possible answers
-) Message text
-) Activator (RunID)
-) Start time
-) Status (depending on the Notification type. Alarm or request:
"Q" = active, "R" = ended. message: "N" = active, "R" = ended)
-) Object type of the triggering object.
Reading the message text of
Notifications
This retrieves the message text of an active Notification.
Confirming a Notification
You can accept or reject an active Notification.
Input parameter: The RunID of the Notification.
Input parameter: The RunID of the Notification.
290
Chapter 6 Evaluating the Application Return Code of SAP Steps
Scheduling, changing and starting
tasks
The following actions are possible:
-) to activate the task once or recurrently
-) to restart a task
-) to restart a task from its last restart point
-) to reschedule the task. If you change the activation of a task
from recurrently to once, it will be rescheduled (new RunID).
These functions (except for "Reading clients") refer to the UC4 client that has been specified for the
SMSE interface in the Connection object.
Setting up the UserInterface Integration
Some UC4 functions are not directly available in the SAP Solution Manager but by using a specific
configuration, you can open the UserInterface directly from the Solution Manager at the required position.
By doing so, you can quickly access these functions.
The following functions are not directly available in the SAP Solution Manager:
l
l
l
Creating and editing Job objects
Listing the existing Job objects
Creating and editing Workflows
To set up the UserInterface integration, follow the steps below. For a general description of the
configuration process, see SAP Solution Manager Integration.
Supplied Files
The UserInterface is supplied as a Web application that must be integrated in a Tomcat Application
Server. A Tomcat Application Server of version 7 is required for the installation process.
The Web application is supplied in the following directory: CD:\AGENTS\SAP\_SOLMAN\
File name
Description
UC4WEBSTART.WAR
The UserInterface for the Application Server.
Procedure
1.
l
l
l
l
Setting up the UI Web application
Host
Copy the file UC4WEBSTART.WAR to the "webapps" folder that is stored in the program directory
of the Tomcat Application Server.
Restart the Application Server.
The new sub-folder UC4WEBSTART will be created in the webapps directory.
Do not delete the WAR file because if you do so, Tomcat will also remove the folder UC4WEBSTART.
2.
Adjusting the configuration file
Automation Engine
l
l
l
l
l
291
Host
This step determines the UC4 system to which the UserInterface should connect.
Note that you can configure only one connection for the UserInterface.
Open the configuration file:
<Tomcat directory>/webapps/uc4webstart/WEB-INF/web.xml
Adjust the following parameters to your system environment:
l
Server name: The name or the IP address of the computer on which the UC4 system runs.
l
System name: The name of the UC4 system.
l
Port number: The port number of the CP to which you want to establish a connection.
An example of the relevant part of the file web.xml that must be adjusted:
<init-param>
<param-name>Server name</param-name>
<param-value>SAPHOST01</param-value>
</init-param>
<init-param>
<param-name>SystemName</param-name>
<param-value>UC4</param-value>
</init-param>
<init-param>
<param-name>Portnr</param-name>
<param-value>2217</param-value>
</init-param>
3.
l
l
l
l
Configuring the Agent
Agent computer
Open the INI file of the SAP Agent for which you have configured the SAP Solution Manager
Integration.
Enter the URL of the UI Web application as the value for the parameter WebStartURL= ([SMSE]
section).
Save the INI file and restart the Agent.
For example:
[SMSE]
webStartURL=http://saphost01:8080/uc4webstart
4.
Calling the UserInterface
The URL that you have specified in the Agent's INI file opens when you call one of the described functions
in the Solution Manager.
The Web browser displays a page that includes the link "Start UC4 User Interface". Click it to open the
UserInterface's login dialog. Log on to run the selected function in the UserInterface.
For example: When you create a new Job in the SAP Solution Manager, the UserInterface and the dialog
open that request you to enter a name for the new Job object.
292
Chapter 6 Evaluating the Application Return Code of SAP Steps
6.11.32 Custom Solutions
Archiving Data in SAP Systems
Data archiving in SAP systems removes mass data from the database that is no longer required in the
system but should remain available for future analyses. The UC4 Automation Platform provides for
centrally controlled data archiving.
Data to be archived is pooled in "archiving objects" (e.g. the archiving object SD_VBAK contains all data
concerning sales records). Archiving runs are integrated using the Archive Development Kit (ADK). ADK
provides the technical basis for the archiving transaction (SARA).
Usually, a separate program flags data to be archived based on configurable residence periods. Flags are
often used in two steps: After the end of residence period 1 (e.g. 6 months), a deletion annotation is set and
after the end of residence period 2, the deletion annotation becomes a deletion flag. Now the object can be
archived.
The archiving process is basically divided into four steps:
1. Pre-run (deletion annotation):
Flags data that should be archived. A pre-run can also be performed regardless of the time frame
specified for the archiving run.
2. Creating archive files:
During the archiving process, the data to be archived is sequentially written into newly created
archive files.
3. Starting the deletion program:
Based on the generated archive files, the deletion program removes the archived data from the
database.
4. Storing the archived files:
The newly created archive files can finally be stored in a filing system or manually stored on tape.
The storing process can be initiated automatically or manually.
Transaction SARA provides for a manual or a semi-automatic (deletion, storage) archiving process. UC4
fully automates archiving runs in all SAP releases.
For archiving data outside transaction SARA please adhere to the following notes:
l
l
458670 Data archiving with an external job scheduler
133707 Data archiving outside transaction SARA
Controlling with UC4
From the technical point of view and regardless of the object to be archived, archiving runs in SAP
systems always consist of four steps:
1. Writing program (WRI)
The write program deals with pre-runs and the creation of archive files. It is capable of running in the
background, parameters can be set using a variant.
2. Deletion program (DEL)
The writing program automatically creates a deletion (DEL) job for each archiving file, if this has
been specified in the relevant archiving object's customizing. The DEL job contains the deletion
program.
3. Storing the archived files (STO)
The deletion program creates a storing (STO) job. The STO job contains the storing program.
Automation Engine
293
4. Possible post processing (END)
Post processing jobs are also automatically created. They are not available for all archiving objects.
Requirements in the SAP system
1. Automatic deletion program
Specify in the archiving object's customizing that the deletion program starts automatically.
2. DEL, STO and END jobs must not start automatically in SAP.
For controlling these jobs with UC4, their automatic start in the SAP system must be prevented.
The function "Job Interception" serves this purpose as of release 4.6C. Activate it with the ABAP
program INITXBP2. The interception table must contain the job names of the DEL, STO and END
jobs of all archiving runs.
UC4 objects
The entire process is handled with a Workflow which contains 3 steps:
1. Starting and monitoring the writing program
The UC4 function "Submit ABAP program" creates a WRI job in SAP and monitors it until it ends.
2. Starting and monitoring deletion jobs
The UC4 function "Select and start intercepted jobs" starts and monitors DEL jobs created by the
WRI job.
3. Starting and monitoring storing jobs
The UC4 function "Select and start intercepted jobs" also starts and monitors storing jobs created
by the DEL jobs.
294
Chapter 6 Evaluating the Application Return Code of SAP Steps
Procedure
1. Workflow activation
Use the :READ mask to query the name of the archiving object.
2. Workflow Monitor
Select or specify the archiving object and the Workflow automatically starts and is displayed in the
monitor. It only ends when all processing steps ended successfully.
3. Monitoring and control
The entire procedure can be traced within UC4 and SAP. UC4 provides all logs for automatic
analyses. In SAP, the procedure can also be traced in the administration function of the relevant
archiving object (transaction SARA).
Conclusion
SAP data archiving is easily implemented using UC4's standard functions and offers various advantages:
l
l
l
l
l
l
Complete automation
The entire SAP system management can be automated using the UC4 Automation Platform for
controlling the data archiving processes. Manual interference is not necessary. Mutual
dependencies to other processes are easily implemented.
Cost reduction
Archiving data on a regular basis provides for optimized database dimensions, improves
performance and saves memory. With UC4, these advantages are centrally controlled and
automatically processed without the accumulation of additional costs.
Optimum resource balance
Resources can optimally be used due to the central and automated control, thereby avoiding
conflicts and shortfalls. Smooth SAP operation is guaranteed.
High reliability
Automation considering all system parameters significantly reduces the number of possible error
sources.
Work relief for staff
SAP experts are relieved from cumbersome manual tasks and can apply their expertise in areas of
significant benefit: in improving systems and service levels.
Central control and overview
All processes in the SAP system are centrally monitored and controlled. Potential problems are
immediately noticed which reduces troubleshooting times to an absolute minimum.
Mass Processing
IS-U is SAP's business solution for the utility industry.
IS-U's accounting system for utility and service industries has been specially designed for the specific
requirements of these sectors. By integrating IS-U utility industry with the neutral R/3 standard
components and interfaces to external systems, SAP offers an integrated enterprise-wide solution for the
utility industry's operational data processing.
The transaction volume of utilities with several million customers, various types of utilities and perhaps
billing on a monthly basis is mainly handled in background operation.
Examples:
Automation Engine
l
l
l
l
l
l
295
Creating reading records
Requests for advance payment
Accounting/billing
Dunning runs
Payment runs
etc.
Definition
UC4 is able to automate these background requirements. We developed a special type of background
"mass processing" in order to optimally deal with huge data amounts.
Characteristics of mass processing:
l
l
A master job splits into a dynamic number of partial jobs.
Each mass processing run requires a parameter set which is identified by date and run ID.
One specific requirement is that a particular order must be kept (e.g. accounting must be finished before
billing starts; both are mass processing runs).
Technique
Mass processing includes a dispatcher which generates parallel split jobs through the definition of
parameters.
When scheduling mass processing, the dispatcher forms the master job of background processing. When
it is processed, it generates a dynamic number of split jobs (the number depends on the defined parameter
settings).
Controlling is handled by UC4. Scheduling can be handled by UC4 or SAP.
SAP R/3 Client Copies
Like the UC4 Automation Platform, SAP R/3 is a client-capable application. The individual clients are
completely separate units. In some cases, periodical data exchange between clients is necessary. UC4
can be used to automate these processes.
The "client" is the top-level hierarchy in R/3 applications. Settings on client level apply to all structures in
the R/3 enterprise organization. The client is a self-contained unit in technical, economical and
organizational terms.
This client concept can be used for:
l
l
Managing many data center customers in one R/3 system.
Setting up several clients with different tasks on one R/3 System. For example:
l
Standard client (client 000)
l
Customizing client (001)
l
Test client
l
Quality assurance client
l
Production client
In such an environment it is often required to supply a QA or test client with consistent data. The most
suitable way to obtain this data is copying the production client. Regularly copy this client in order to
establish a realistic test environment.
296
Chapter 6 Evaluating the Application Return Code of SAP Steps
Client copies in SAP R/3
Copying clients in SAP R/3 involves some effort, especially the creation of periodical copies for supplying
test systems with current data.
SAP R/3 supports the online copying and transportation of clients. These transactions are not suitable for
periodical execution (SAP Release 4.0 to 4.6D).
The R/3 background job control cannot perform such periodical transactions because dynamic variants are
used.
Problem definition
Huge amounts of data are transferred when a client is copied. A client without application data allocates
about 500 MB database memory. The copying process can therefore take several hours with one or more
dialog processes being busy during this process.
Users should not use the source and target client during the copying process. Active users in other clients
consume additional resources and extend the time required for copying.
A test run should be performed before starting the copying process. In doing so, you can determine which
tables need to be modified and the available database memory is also checked.
The target client is often deleted before a client is copied, thus deleting all master user data. Therefore,
only the user SAP* can log on to the target client.
R/3 Client copies with UC4
Using UC4 for the periodical creation of client copies makes this process easier and more secure. Test run
and copying process can be automated and the normal operation is not interrupted.
The copying process starts depending on test results and resource availability. UC4 informs the operator
immediately if an error occurs.
The SAP system must meet the following requirements before UC4 can create client copies:
l
l
Master user data must not be deleted before the copying process
UC4 uses a normal user account for logging on to SAP. It cannot use the SAP* user. In SAP, it is
not possible to delete the target client before copying it. Alternately, you can use custom ABAPs in
order to delete large tables (see SAP Service Marketplace, note no. 365304).
The report RSCLXCOP must be modified in order to enable the maintaining of report
variants.
A job for copying clients obtains its information from a variant. This variant is overwritten with data
from the source client or deleted during the copy process. During a client export the number of the
copy is entered in the variant, thus causing problems with periodical scheduling. Identical variants
(using identical names) for the report RSCLXCOP must therefore be created in source and target
client. Detailed information is provided in note no. 303007 of the SAP Service Marketplace.
If all the above requirements are met, you can create a UC4 job for copying clients. Dependencies can be
represented within a Workflow. Test run and the actual copy process can run in automated form. UC4
ensures sufficient system resources. Periodical client copies can so be created in an easy and secure
way.
Automation Engine
297
SAP Dialog for UC4
The SAP Dialog for UC4 is a graphical interface for SAP R/3 users and serves to trigger processing in the
UC4 system. SAP-defined tasks are transferred to the UC4 system via the CallAPI for SAP.
The transaction "/sbb/uc4dc" shows the end user's interface. It contains an overview of tasks. Users see
only tasks for which they have authorizations. Tasks can be grouped in classes and named accordingly.
Click the list to select them. Depending on the specified settings, you can query variables and attributes or
maintain variants. Each task activation is logged in the statistics.
l
Activation by entering freely definable attributes
Attributes are freely definable and can be transferred to UC4 using :PUT_READ_BUFFER .
l
Direct connection to standard variant maintenance
A direct connection to SAP's variant maintenance is provided if standard ABAPs are used. Only
predefined variants can be maintained.
l
Mapping Workflows
Workflows can be mapped using variables. In doing so, you can decide which components of a
predefined procedure should be processed. Communication to the UC4 Workflow is exclusively
made by setting variables.
l
Statistics and status tracing
Users have statistics in which all activations can be traced. Tasks can explicitly be canceled or
current states be adjusted.
The SAP Dialog for UC4 cannot completely replace the UserInterface. It supports users who
exclusively work with the SAP GUI and whose background tasks (jobs, job plans) should be controlled
by UC4 from within SAP.
The SAP Dialog for UC4 is a consultant solution and not part of the product. Thus, it is not maintained.
Automated SystemCopy for SAP
This UC4 solution allows you to create a SAP system copy by fully automated means. You can adjust all
the individual steps according to your requirements.
UC4 Automated SystemCopy for SAP is a consulting solution and is not subject to maintenance.
Documentation is available in the form of an external document.
298
Chapter 6 Evaluating the Application Return Code of SAP Steps
6.11.33 Technical Connection
UC4 and SAP
An Agent serves to establish a connection between UC4 and SAP. Its INI file contains the connection
data to a particular UC4 system. Connection data to an SAP system is stored in Connection objects. The
Agent requires at least one Connection object which contains the CPIC User including his or her Login
data.
UC4 jobs require the indication of an Agent and a Login object with the login information determining the
SAP client in which the job will be processed.
The Form tab is very useful for creating UC4 jobs. It provides a graphical interface in which you can easily
enter scripting lines. You can also retrieve particular data from the SAP system (such as the available
variants) with the SAP Agent establishing the required connection to the SAP system. User name,
password and client are taken from the Connection object for "ABAP Basis".
See also:
Form tab
Multiple SAP Systems
The following description explains the appropriate configuration of several SAP Agents which run on
different SAP systems.
Other SAP Agents
1.
Edit ServiceManager Definition File UC4.SMD. Enter the additional Agents in the ServiceManager Definition file according to the following example.
Ensure that the name of the *.INI file is separated by a blank and specified after the start path of the Agent.
! Comment lines begin with an exclamation mark
!
! Now, sub-services are defined
!DEFINE UC4 Server;*OWN\UCServer.exe;*OWN
DEFINE UC4 C11-Agent;*OWN\C11\UCXJR3X.exe -i*OWN\UCXJC11.INI;*OWN
DEFINE UC4 XYZ-Agent;c:\uc4global\bin\XYZ\UCXJRX3.exe ic:\uc4global\bin\XYZ\UCXJXYZ.INI;*OWN\XYZ
Alternately, these entries in the file UC4.SMD can also be duplicated and adjusted with the
ServiceManager Dialog.
2.
Creating *.INI files
Create a UCXJ*.INI file with the name you have specified in UC4.SMD for every additional Agent. UC4
recommends copying the file of an already existing Agent (e.g. UCXJR3X.INI to UCXJC11.INI).
Check or edit the created UCXJ*.INI files.
Automation Engine
3.
299
Editing SAPRFC.INI (only when using the SAPRFC.INI)
Add the additional chapters in the SAPRFC.INI (so far SIDEINFO) as specified in the UCXJ*.INI files in
accordance with the following example:
DEST=UC_C11
LU=R33
TP=sapdp00
GWHOST=R33
GWSERV=sapgw00
PROTOCOL=I
DEST=UC_XYZ
LU=R33
TP=sapdp01
GWHOST=R33
GWSERV=sapgw01
PROTOCOL=I
4.
Opening and closing the ServiceManager.
Close the ServiceManager and restart it. After that, the additional Agents should be available. Create the
user for the RFCLOGIN in the relevant SAP system.
SAP Security Objects
SAP authorizations required for UC4 Jobs depend on the particular installation and on the range of
functions used in UC4. What is shown below are authorization objects which are necessary for the CPIC
user in order to provide maximum functionality.
For understanding the following table, knowledge of SAP authorization concepts is assumed.
Authorization Object
Connection to UC4
Field name
S_RFC
When the Profile Parameter
ACTVT RFC_
auth/rfc_authority_check is
NAME RFC_
set, SAP checks if the RFC
TYPE
user is allowed to call the given
function group.
*
*
*
S_BTCH_JOB
Batch Processing:
Operations on Batch
Jobs
UC4 creates SAP Jobs
dynamically and needs the
authorization to plan, monitor
and release Jobs. In addition,
UC4 creates jobs in order to
process BDC sessions,
thereby using the standard
ABAP program RSBDCBTC.
*
*
JOBACTION
JOBGROUP
Values
300
Chapter 6 Evaluating the Application Return Code of SAP Steps
Authorization Object
Connection to UC4
Field name
Values
S_BTCH_ADM
Background
Processing:
Background
Administrator
In order to run existing SAP
Jobs, UC4 must change the
respectiveJo bs. The UC4 and
standard interfaces use the
standard function module BP_
JOB_MODIFY to run Jobs.
This requires batchadministrator authorization.
This type of authorization is
also required for retrieving the
Spool List of a Job in case the
CPIC user is not the job
creator.
BTCADMIN
Y
Attention: S_BTCH_ADM
allows the client-independent
selection of existing Jobs. If
the UC4 JCL statement R3_
ACTIVATE_JOBS is
processed with a CPIC user
having this authorization, UC4
possibly starts Jobs in several
SAP clients, depending on the
specified selection criteria
(e.g. same Job name in 2 SAP
clients)
S_BTCH_NAM
In order to create and run Jobs
for any other SAP user, the
CPIC user must be authorized
to specify the user name.
BTCUNAME
*
S_SPO_DEV
Spooler: Device
Authorization
In order to specify the printing
parameter 'print immediately'
within a Job step, the CPIC
user must be authorized to
access the corresponding
printing device.
SPODEVICE
*
S_TMS_ACT
In order to transfer the cover
page of a Spool List back to
UC4, it is helpful to see the
parameters of the variant
which was used to run the
ABAP. This information is part
of the cover page.
STMSACTION
STMSOBJECT
STMSOWNER
*
*
*
S_XMI_PROD
This object is used to log on to EXTCOMPANY
the Standard Interface. Before EXTPRODUCT
Calling functions of an
INTERFACE
External Interface, the
External Application has to Log
on to the Interface.
*
*
*
Automation Engine
301
Authorization Object
Connection to UC4
Field name
Values
S_XMI_LOG
Not necessary for UC4, but
when using the standard
interface, entries into the XMI
log are created (Online
Transaction Code RZ15). This
authorization is required to
view them or to clear the log.
-
-
S_WFAR_OBJ
ArchiveLink
Authorizations for
accessing Documents
UC4 allows the specification
of Archive Parameters (object
type, document type...). This
includes that the printing list of
an ABAP program can be
transferred to an optical
archive immediately. This only
makes sense if an optical
archive system is installed for
the SAP system.
ACTVT
OAARCHIV
OADOCUMENT
OAOBJEKTE
*
*
*
*
S_WFAR_PRI
ArchiveLink
Authorizations for
accessing Print Lists
In order to create printing lists
within an optical archive, the
CPIC user must have the
corresponding authorization.
ACTVT
OAARCHIV
OADOKUMENT
OAOBJEKTE
PROGRAM
*
*
*
*
*
S_PROGRAM
ABAP: Program run
checks
UC4 needs this authorization
P_ACTION
object to schedule ABAP
P_GROUP
programs that are assigned to
authorization groups
(Authorization field P_ACTION
= BTCSUBMIT) and to
manage variants
(Authorization field P_ACTION
= VARIANT).
BTCSUBMIT,VARIANT
*
S_SPO_ACT
Spool: Actions
In order to transfer Spool Lists
not created from the CPIC
user, the field SPOACTION
has to allow the actions BASE
and DISP for the
corresponding users.
SPOACTION
SPOAUTH
BASE,DISP
*
S_ADMI_FCD
System Authorizations
In order to transfer Spool Lists
not created from the CPIC
user, the field S_ADMI_FCD
has to allow the actions at
least the action SP0R.
S_ADMI_FCD
SP0R
S_RS_ISOUR
Administrator
Workbench InfoSource (Flexible
Update)
Only needed if the Business
Warehouse Function BW_
ACTIVATE_INFOPACKAGE
is used and Flexible Update is
used.
ACTVT
RSAPPLNM
RSISOURCE
RSISRCOBJ
*
*
*
*
302
Chapter 6 Evaluating the Application Return Code of SAP Steps
Authorization Object
Connection to UC4
Field name
Values
S_RS_ISOUR
Administrator
Workbench InfoSource (Direct
Update)
Only needed if the Business
Warehouse Function BW_
ACTIVATE_INFOPACKAGE
is used and Direct Update is
used.
ACTVT
RSAPPLNM
RSISOURCE
RSISRCOBJ
*
*
*
*
S_DEVELOP ABAP
Workbench
Only needed if the Business
Warehouse Function BW_
ACTIVATE_CHAIN is used.
ACTVT
DEVCLASS
OBJNAME
OBJTYPE P_
GROUP
*
*
*
*
*
S_RS_ICUBE
Administrator
Workbench - InfoCube
Only needed if the Business
Warehouse Function BW_
ACTIVATE_CHAIN is used.
ACTVT
RSICUBEOBJ
RSINFOAREA
RSINFOCUBE
*
*
*
*
S_RS_ADMWB
Administrator
Workbench - Objects
Only needed if the Business
Warehouse Functions are
used.
ACTVT
RSADMWBOBJ
*
*
S_RS_DS
Only needed if the Business
Warehouse Functions are
used.
S_RS_DTP
Only needed if the Business
Warehouse Functions are
used.
S_RS_ODSO
Only needed if the Business
Warehouse Functions are
used.
S_RS_PC
Only needed if the Business
Warehouse Functions are
used.
S_RZL_ADM
Releasing Intercepted Jobs
(RemoteTaskManager, R3_
activate_intercepted_jobs)
ACTVT
01
S_TABU_DIS
For using SAP Forms
ACTVT
DICBERCLS
03
SPFL
-
No specific SAP
authorizations are necessary
for additional UC4 functions,
as there is no security risk.
*) UC4 recommends creating your authorizations in accordance with your naming conventions.
For using minimum UC4 functionality, it is necessary to provide the RFC user with a user profile that
contains the authorization object S_BTCH_JOB. It must contain the standard authorization S_BTCH_ALL
or an authorization where the fields are filled in as follows:
Activities in Jobs: DELE, PLAN, PROT, RELE, SHOW
Summarizing Jobs for a group: *
Automation Engine
303
Consideration of Job Attributes
The host-specific tab in SAP jobs contains some attributes that affect several script elements. The table
shown below lists them all. Those SAP-specific script elements that are not included in this list do not use
attributes.
Script element
Login language
Job
Job Target Start
name class system type
Delete in
CCMS
Spool list
recipient
BCA_ACTIVATE_
PROCESS
R3_ACTIVATE_EXT_
COMMAND
R3_ACTIVATE_EXT_
PROGRAM
R3_ACTIVATE_
INTERCEPTED_JOBS
R3_ACTIVATE_JOBS
R3_ACTIVATE_
REPORT
R3_ACTIVATE_
SESSIONS
R3_CALL_
TRANSACTION
R3_GET_EVENT
R3_GET_JOB_SPOOL
R3_MODIFY_JOB
R3_RAISE_EVENT
See also:
SAP tab in SAP Jobs
Interfaces
Interfaces
General information
Agents communicate with the SAP system via SAP's RFC (Remote Function Call). Functional modules
are called in this process. The Agent can use the standar interfaces but also the UC4 Interfaces which
allows using additional functionalities.
This documentation addresses the two types of interfaces as shown below:
304
Chapter 6 Evaluating the Application Return Code of SAP Steps
l
l
The UC4 Interface
is based on functional modules that have been developed by UC4.
The standard interfaces are based upon functional modules that are provided by SAP. UC4 uses
several of these interfaces for various purposes. The interfaces are subdivided:
l
XMB (eXternal Monitoring Basics)
l
XAL (eXternal ALerting)
l
XBP (eXternal Batch Processing) *)
l
XMW (eXternal Monitoring Write)
l
BW-STA (Business Warehouse - data STAging)
*) Note that the XBP 2.0 interface must be activated using the program INITXBP2. This is part of the XBP
2.0 installation. Otherwise, you cannot use parent-child relations and Intercepted Job functions.
The UC4 Automation Platform supports the SAP NetWeaver XBP 2.0 and XBP 3.0 interface.
Therefore, you can use SAP modules that use this interface (such as SAP 4.7, NetWeaver Stack
2004s, ECC5, ECC6).
The XBP interface version is not relevant for the Kernel version. SAP ensures compatibility by
supporting a particular number of new Kernel versions that still support the old interface when a new
interface version is released.
The UC4 Interface requires BABP XBP V2.0. Check the version in your SAP system and install an upto-date support package.
Functional Differences
The following table provides an overview of SAP script elements which require the UC4 Interface (Script
Element). Script elements which have specific parameters which require the UC4 Interface are also
checked (Parameter).
6.11.34 Script Elements and Corresponding Interfaces
UC4 Interface required
Script Statements
Description
R3_ACTIVATE_
CM_PROFILE
Activates a profile in the SAP Criteria
Manager
R3_ACTIVATE_
EXT_COMMAND
Execution of an external command
R3_ACTIVATE_
EXT_PROGRAM
Execution of an external program
R3_ACTIVATE_
INTERCEPTED_
JOBS
Carries out Intercepted Jobs
R3_ACTIVATE_
JOBS
Executes already planned jobs
R3_ACTIVATE_
REPORT
Executes an ABAP program
Script
Element
Parameter
Automation Engine
R3_ACTIVATE_
SESSIONS
Processes Batch Input Sessions
R3_CALL_
TRANSACTION
Calls an SAP transaction
R3_COPY_
VARIANT
Copies the variant of a report
R3_CREATE_
OUTPUT_
REQUEST
Creates a new output request to an existing
spool request
R3_CREATE_
VARIANT
Creates a new variant
R3_DEACTIVATE_
CM_PROFILE
Deactivates a profile in the SAP Criteria
Manager
R3_DELETE_
NODE
Deletes a node in the SAP monitor
architecture.
R3_DELETE_
VARIANT
Deletes the variant of a report
R3_GET_
APPLICATION_RC
Checks the application return code of one or
several job steps.
R3_GET_
APPLICATIONLOG
Retrieves messages of the application log
and writes them into report or file
R3_GET_EVENT
Waits for an event to be triggered in SAP
R3_GET_
INTERCEPTION
Reads the filter table for Intercepted Jobs and
saves them in the activation report or a file
R3_GET_JOB_
SPOOL
Reads the spool list of an "ABAP program"
step
R3_GET_JOBLOG
Retrieves the Job log of an SAP Job from
SAP and writes it to the report
R3_GET_JOBS
Selects SAP Jobs and lists the result in the
activation report
R3_GET_
MONITOR
Reads data from an SAP monitor
R3_GET_
SESSIONS
Selects batch input sessions and lists the
result in the activation report or in a file
R3_GET_
Selects spool requests with pre-defined filters
SPOOLREQUESTS
R3_GET_
SYSTEMLOG
Reads the system log of an SAP system over
a specified period of time
R3_GET_
VARIANTS
Reads the variant catalog
R3_GET_
VARIANT_
CONTENTS
Shows the content of a variant
R3_MODIFY_
INTERCEPTION
Modifies the filter table for Intercepted Jobs
305
306
Chapter 6 Evaluating the Application Return Code of SAP Steps
R3_MODIFY_JOB
Modifies an ABAP Step
R3_MODIFY_
VARIANT
Modifies a value in a variant
R3_RAISE_EVENT
Triggers an event defined in SAP
R3_SCHEDULE_
JOB_CANCEL
Resets an already released SAP Job to the
status "Scheduled"
R3_SEND_
SPOOL_REQUEST
Sends an existing spool request
R3_SET_
BDCDATA
Defines BDC data
R3_SET_FREE_
SELECTION
Defines a free selection
R3_SET_LOG_
ATTR
Sets a log attribute in the SAP monitor
architecture
R3_SET_PERF_
ATTR
Sets a performance attribute in the SAP
monitor architecture
R3_SET_PRINT_
DEFAULTS
Sets default values for print parameters
which are used when executing reports
R3_SET_SELECT_
OPTION
Defines a selection criterion
R3_SET_STATUS_
ATTR
Sets a status attribute in the SAP monitor
architecture
R3_SET_TEXT_
ATTR
Sets a text attribute in the SAP monitor
architecture
R3_SWITCH_
OPMODE
Switches the operation mode in SAP
See also:
About UC4 JCL for Applications
Transporting the UC4 Interface
General
In order to take advantage of the functionality of the UC4 Interface, function modules must be transported
to the SAP system.
Function modules are developed as ABAP development objects. These components are supplied with the
"Correction & Transport System " package of the SAP System:
l
l
l
KNNNNNN.SID information file, for example K000046.T45
RNNNNNN.SID data file, for example R000046.T45
ENNNNNN.txt export protocol, for example E000046.txt
Automation Engine
307
Name ranges are transported along with function modules in separate transport requests. A list of all
currently valid transport requests is found in the file TRANSPRT.TXT. All transports must take place when
a new installation is made. With an update installation, it is only the function modules (UC4 Interface)
because there is no change of the name ranges.
The names of the development objects are described in Terminology.
Throughout this document, the following codes are used:
l
l
l
NNNNNN for the transport job number of the delivery system and
SID for the system names of the delivery system.
TID is used for the system name of the target system (to which the function modules are imported).
File Names
SAP can be installed in various environments (UNIX, Windows...). Therefore, it is important to consider
the specific features of the system when you name the files.
In this document, the file names that refer to a SAP environment are written in UNIX language ("/"). For
Windows environments, the names are the same with the exception that thy use a "\" character.
6.11.35 Importing Function Modules in SAP
If the functionality of the UC4 Interface is used, function modules must be transported to the SAP system.
Requirements:
All activities that concern the transport system must be made by a SAP administrator (SIDadm).
The transport system must be properly installed and set. This takes place during the installation of the
SAP system.
In this case, importing requires that at least 2 batch work processes (BTC) are running.
Control: Tools - Administration - Monitor - System Control - System Overview (Transaction SM50).
To import development objects, the Transport demon must be planned for in client 000 (background job
"RDDIMPDP") and cleared for the SAP system. Control: see below
The functionality can be checked as follows:
cd usr/sap/trans/bin........ Change to the SAP transport directory.
tp checkimpdp TID........... Verify that the Transport demon RDDIMDP is active in SAP.
tp connect TID.............. Test the connection to the SAP system.
The transport system is described in the SAP online documentation in the chapter BASIS - TRANSPORT
CONTROL.
Note that the import process requires the option "Ignore Non-Matching Component Versions" to be set.
Procedure:
Import the supplied transport files to the SAP transport environment:
l
l
l
On the SAP computer:
Change to the appropriate subdirectory (for the SAP version) in CD:AGENTS\SAP\_TRANS:
Copy the files from there to the following directory:
KNNNNNN.SID by /usr/sap/trans/cofiles
RNNNNNN.SID by /usr/sap/trans/data
308
Chapter 6 Evaluating the Application Return Code of SAP Steps
If SAP is installed under UNIX, the files are usually transferred via FTP. Be sure to enter "bin" for
binary transfers.
l
The file ENNNNNN.TXT on the CD contains the complete export log and can be used for analysis.
Importing the delivery into the SAP system:
l
l
l
On the SAP computer (use the SAP administrator (SIDadm) to register).
The imported transport files (RNNNNNN.SID and KNNNNNN.SID) must not be write protected
(be careful when you copy them from the CD).
If needed, you can create a directory that includes all objects of the transport job:
cd usr/sap/trans/data....... Change to SAP transport directory.
r3trans -l RNNNNNN.SID...... Create a file trans.log (List of transported objects).
l
Create a buffer entry for the target system.
cd usr/sap/trans/bin........ Change to SAP transport directory.
tp addtobuffer SIDkNNNNNN TID [pf=<Profile name, Default TPPARAM>
l
If needed, you can check the buffer entry:
tp showbuffer TID [pf=<Profile name, Default TPPARAM>
l
l
Before you start to import, decide upon the unconditional modes (u) that should be used:
l
4....valid only for SAP Release 3.x: guarantees that the target system name (TID) that is
used for the export does not correspond to the actual target system name. This mode must
be used because the actual target system is not known.
l
1....must be entered when the import should be repeated.
Start the import using one of the following commands:
tp import SIDkNNNNNN TID u4 client123] [pf=<Profile name, default TPPARAM>] or
tp import SIDkNNNNNN TID u14 client123] [pf=<Profile name, default TPPARAM>]
The unconditional modes are distinguished by TP version and can be checked in the SAP
Documentation if needed.
Note for the import process:
l
This process requires that at least 2 batch tasks are running.
l
Although the transport job does not include client-specific data, it can happen that a client is
required. In this case, enter a valid client=nnn (client 010 is used for the export).
l
The import can take a few minutes, especially if the Transport demon RDDIMPDP is
planned not to be event-triggered but rather time-controlled.
l
Message "no profile used ":
l
No profile is specified if you call an internal program on "sapevt". That is the reason why this
message occurs with any call on sapevt. Usually, it can be ignored.
l
Other messages can occur. Only the return code is crucial (see below - Control).
Control:
l
l
Because of the SAP transport system's and the SAP environment's complexity, thorough error
diagnosis and correction can only be handled by an expert who is familiar with installation
environments.
A general assessment as to whether the import was successful should be possible for a non-expert
with the following tips:
Automation Engine
Importing creates logging files.
These are in the directory /usr/sap/trans/log and are called SIDsNNNNNN.TID
s means transport step:
l
l
l
G... Report and screen generation
H... R3TRANS import Dictionary
I... R3TRANS main import
In these three log files the exit code (=return code) has to be checked (it always occurs at
the end of the file). It cannot exceed "4"!
l
l
309
The expert can also check the log files in the SAP system.
Testing the UC4 Interface with ABAP Workbench
1.
Starting the development environment and opening the function modules
Start the development environment (ABAP/4 Workbench) and open the function modules to the function
group /SBB/UC4_JOB with the Object Browser:
Tools⇒ ABAP/4 Workbench⇒Overview ⇒Object Navigator, select Function Group /SBB/UC4_JOB,
select Function Modules, position the cursor on the object and click Test in the context menu.
The name of the function modules always has the prefix UC4.
2.
Testing the function module UC4_JOB_OPEN
Parameters that must be specified:
JOB NAME - Any name (such as TEST).
JOBCLASS - A, B or C
The parameter JOBCOUNT is supplied. This value must be noted or copied to the clipboard.
310
Chapter 6 Evaluating the Application Return Code of SAP Steps
3.
Testing the function module UC4_JOB_SUBMIT
Parameters that must be specified:
JOBCOUNT - Enter the value or import from the clipboard.
JOBNAME - As with function module UC4_JOB_OPEN,
REPORT_ID - 'RSM04000' or 'RSM04000_ALV'.
Automation Engine
311
Make sure after the execution that no exception has occurred. Although parameters are supplied, they
are not necessarily required for testing.
4.
Testing the function module UC4_JOB_CLOSE
Parameter to be specified:
JOBCOUNT - enter value or import from the clipboard,
JOBNAME - as with function module UC4_JOB_OPEN.
After the execution, verify that no exception has occurred.
312
Chapter 6 Evaluating the Application Return Code of SAP Steps
The Job has now been started and can be displayed by using a standard transaction SM37
(System⇒Services ⇒Jobs ⇒Job Overview). If the Job has ended okay, this indicates that the function
modules within the SAP system work properly.
Agent for SAP BW
General
The UC4 Automation Platform supports the components SAP Business Information Warehouse (SAP
BW) in the same way that it supports an operating system. Technically, this cooperation is set up so that
Automation Engine
313
function modules are called via SAP's RFC (Remote Function Call) within the SAP system. The
communication for the SAP system is carried out exclusively via RFC and is therefore independent of the
environment where SAP BW is installed.
The setting of the connection parameter is carried out in the Connection object of the Agent. Furthermore,
this Agent can be set for all UC4-supported SAP BW versions.
The Agent for SAP BW can also process Jobs in the SAP basis system (regular background jobs).
The following table shows which SAP Version and SAP Basis correspond to an Agent for SAP BW.
BW Release
SAP Basis
Agent for SAP BW
1.2B
4.5A
Not supported
2.0B
4.6C
Available first with UC4 Version 2.63C
2.1C
4.6D
Available first with UC4 Version 2.63C
3.0B
6.10
Available first with UC4 Version 2.63D
>3.0B
6.x
Available first with UC4 Version 2.63D
Support Packages for SAP BW
For the operational use of the Agent, UC4 recommends installation of the following support packages from
SAP BW.
SAP BW Release
Support Package Level
2.0B
32
2.1C
24
3.0B
14
3.1C
08
>3.1C
Support Package Level unknown
If the Agent is used with a lower support package level, the following messages can appear. Further
information is found in the given SAP notes.
SAP Note Number
Message
488588
short dump "DYNPRO_SEND_IN_BACKGROUND"
426047
Message E089(RSM1) "Job not (yet ?) started"
488808
BAPI_IPAK_CHANGE ignores InfoPackage Parameter
Status check
The UC4 Automation Platform presumes that the technical status that is submitted when the function
status check is called is a "final status". The Interface Repository gives the following description:
The parameter TECHSTATUS is the request's technical status. It always contains one of the following
values:
l
l
l
G - green (request handling successful)
Y - yellow (request is being processed)
R - red (request incorrect or canceled)
314
Chapter 6 Evaluating the Application Return Code of SAP Steps
Obviously, these states are not "final states". A status can change to "red" for a short time and then to
"yellow" or "green" after a while. UC4 accounts for this fact. For status checks, a time delay can be
activated so that it can be checked n times if the status "red" actually remains in this status, for example.
The INI file of the SAP Agent contains the parameters maxruntime= and repeat_check= [SAP_BW]) for
this.
Another function is available which checks the states of process chains. It supplies the following values:
l
l
l
l
l
l
l
l
l
l
"R" - cancel
"G" - normal end
"F" - normal end
"A" - continue checking
"X" - cancel
"P" - continue checking
"S" - cancel (but only after the process chain has been restarted)
"Q" - continue checking
"Y" - continue checking
" " - continue checking
UC4 then converts these states into return codes:
Return code
Status
SAP Status
0
ENDED_OK
G or F
4
ENDED_NOT_OK
R
8
ENDED_NOT_OK
X
12
ENDED_NOT_OK
S
Automation Engine
315
Archive Parameters with R3_ACTIVATE_REPORT
The archive parameters which can be specified by a user in R3_ACTIVATE_REPORT correspond to the
entry fields displayed in the figure below. The dialog field is displayed in the SAP System if "Archive" has
been selected as the mode in the printing parameters.
Parameters in SAP
Parameters for R3_ACTIVATE_REPORT
Obj. type
ARCHIVE_SAPOBJECT
Doc. type
ARCHIVE_OBJECT
Information
ARCHIVE_INFO
Text
ARCHIVE_TEXT
See also:
R3_ACTIVATE_REPORT
ERROR/ERRORLEVEL with R3_ACTIVATE_SESSIONS
When processing R3_ACTIVATE_SESSIONS, UC4 first retrieves a list of sessions which should be
processed from the SAP system. Each of these sessions will be processed with an individual SAP job. In
this document, these jobs are referred to as Replayers. A Replayer uses the ABAP program
"RSBDCBTC" to process sessions.
ERROR
Refers to the result (status) of the Replayer. The status can be "A" for abend or "F" for finished
successfully.
316
Chapter 6 Evaluating the Application Return Code of SAP Steps
ERROR=IGNORE
The next session of the list will be processed in any case. The result of the previous Replayer is
ignored.
ERROR=ABEND
Processing of sessions stops immediately if a Replayer ends with status "A". The UC4 Job
abends.
ERRORLEVEL
Always refers to the session itself and is checked when the Replayer has ended. ERRORLEVEL
defines the number of incorrectly processed transactions in % within a session. If the session value
has been exceeded, the processing of the UC4 Job is canceled. No further sessions of the session
list are executed. No check is made for successfully processed transactions if no ERRORLEVEL
has been specified.
Automation Engine
317
Troubleshooting
Checking Errors
This document contains information that will support you in recognizing the source of errors which cause
the Agent to function improperly or individual tasks to be executed incorrectly.
Job report
The first source to be checked is the activation log of the UC4 Job for SAP. It provides information about
the actions the Agent has taken in connection with the SAP system and how the particular actions ended.
Attributes of Executable Objects
Sometimes the error cause is easily found in the attributes of an executable object (e.g. wrong client or
user). Check the attributes of the particular object.
CPIC User
An SAP user (client, name or passport) must be defined in a Login object to be able to establish a
connection to the SAP System. This user must also be available with the same password in all an SAP
system's clients in which tasks are executed. Check the Login object and the users in the SAP system.
Within the SAP system, the Agent is represented by the CPIC user. This user requires the appropriate
rights such as operator rights for background processing, for example. Check the rights of the SAP
system's CPIC user.
Helpful Transactions
Through job logs and spool lists, the transaction "SM37" provides information about job executions. The
XMI log which can be called using "RZ15" also supplies helpful records.
Log Files
Agent and Server log files provide exact information about the relevant point in time when the error
occurred. These files' contents are also provided in the System Overview. The initial section shows the
complete INI file including the parameters which have been specified for the Agent and Server. This
section is followed by a chronological list of all executed actions.
SAP's System Log
Error situations occurring in the SAP system are logged in SAP's system log. Use the SAP transaction
"SM21" to view the system log. In particular cases (e.g. when the Agent fails to schedule a JobStep), the
SAP system log is automatically copied to an own tab in the UC4 report.
318
Chapter 6 Evaluating the Application Return Code of SAP Steps
Traces
Traces provide even more detailed information than log files. They contain all messages which were sent
from and to Agent and Server or Agent and SAP system (RFC trace). Traces can be activated in the
Agent's INI file or the System Overview. Trace contents are stored in files in the Agent's working directory
or an individually defined directory.
Traces are required for the support or development team's analysis process. Always include this
information in your support message.
An activated RFC trace create files on Agent side but also on SAP's application server computer. UC4
recommends activating traces only for a short period of time in order to reduce the hard disk's memory
consumption. Set gw/accept_remote_trace_level to 0 if no trace files should be created in the SAP
system.
Further information about RFC trace is available in the SAP note number 532918.
Problems by Importing Function Modules
Program tp does Not Terminate
6.11.36 Symptom
While importing the development objects, the program tp does not terminate (normally it runs a few
minutes). After canceling with (Ctrl-C), the following message is displayed in the SLOG file.
Background Job RDDIMPDP could not be started or terminated abnormally
6.11.37 Cause
The import of development objects is executed by Job RDDIMPDP. This is usually event-controlled and
triggered by the event "SAP_TRIGGER_RDDIMPDP" of the program tp. In this case, starting the Job with
the event does not work - tp consequently waits infinitely.
6.11.38 Solution
Verify that the event "SAP_TRIGGER_RDDIMPDP" has been defined (SM64).
Verify that the entries for the event control are correctly set in TPPARAM.
Search for possible information in the SAP Service Portal with the headword "SAP_TRIGGER_
RDDIMPDP"
If necessary, use the 5-minute RDDIMPDP, which can be scheduled with SE38 via ABAP RDDPUTPP.
Automation Engine
319
SAP Jobs End with ARCHIVE_INFO_NOT_FOUND
6.11.39 Symptom
SAP Jobs canceled with the following message:
U2004001 RFC Return code: ARCHIVE_INFO_NOT_FOUND
6.11.40 Cause
ARCHIVE_INFO_NOT_FOUND is an exception of the function module "GET_PRINT_PARAMETERS".
This function module is a standard function module of the SAP System.
ARCHIVE_INFO_NOT_FOUND does not necessarily refer to the info field of the archive parameters.
ARCHIVE_INFO_NOT_FOUND refers to the entire archive parameters. These are currently:
l
l
l
l
ARCHIVE_O[BJECT]= Document type
ARCHIVE_S[APOBJECT]= Object type
ARCHIVE_T[EXT]= Text
ARCHIVE_I[NFO]= Info field
ARCHIVE_INFO_NOT_FOUND can have various reasons such as:
l
l
l
The specified document type or object type has not been defined in SAP.
The document type is assigned to a non-existing archive in SAP (Content Repository).
The user has no access (see authorization object S_WFAR_PRI in SAP).
Provided that the parameters are correctly transferred from UC4 to the function modules, the reason for an
exception is mostly found in SAP.
6.11.41 Solution
Use RFC Trace to check whether the UC4 parameters are correctly transferred to the function module.
Check your customized settings "Business Documents" and "ArchiveLink" and the authorizations of the
CPIC User in the SAP system.
See also:
R3_ACTIVATE_REPORT
Archive Parameter with R3_ACTIVATE_REPORT
Stability problems with SAP instances occurred if many SAP Agents (RFC
connection) were used on one Server
6.11.42 Symptom
The external RFC/CPIC server cannot open additional connections.
The system issues the error message:
320
Chapter 6 Evaluating the Application Return Code of SAP Steps
LOCATION CPIC (TCP/IP) on local host ERROR max no. of 100 conversations
exceeded
6.11.43
Reason
The number of parallel connections that can be kept in the library is set to 100.
6.11.44
Solution
By setting the environment variables CPIC_MAX_CONV, the library can handle multiple connections at
the same time.
Windows: set CPIC_MAX_CONV=<n>
For example, set CPIC_MAX_CONV=500 (for 500 connections)
Unix: setenv CPIC_MAX_CONV <n> ( csh )
For example, setenv CPIC_MAX_CONV 500 (for 500 connections)
Unix: export CPIC_MAX_CONV=<n> ( ksh )
For example, export CPIC_MAX_CONV=500 (for 500 connections)
iSeries: ADDENVVAR ENVVAR(CPIC_MAX_CONV) VALUE(<n>)
For example, ADDENVVAR ENVVAR(CPIC_MAX_CONV) VALUE(500) (for 500 connections)
Problem with Password Assignment to SAP
After updating to SAP NetWeaver 2004s and later, CPIC user could no longer log on
6.11.45 Symptom
Password-based logon attempts (to ABAP systems as of Release 7.00 / NetWeaver 2004s / SAP ERP
2005) fail, although the user has entered a supposedly correct password in a front-end component or in a
destination (of another system). However, a (direct) SAPGUI logon with the same password is
successful.
6.11.46 Reason
ABAP systems as of NetWeaver 2004s (7.00) support passwords of up to 40 characters and differentiate
between uppercase and lowercase. In earlier ABAP Releases (prior to 7.00), passwords could only be
comprised of a maximum of 8 characters, whereby lowercase letters that were entered were automatically
changed to uppercase letters.
If, in a newer ABAP system (as of Release 7.00), a downwardly incompatible password is unknowingly
granted (see below), and if the front-end or middleware components are not able to process such
passwords correctly, logon problems inevitably occur.
This is usually due to the (invisible) automatic conversion from lowercase to uppercase letters. The
Automation Engine
321
problem is that the password entered by the user does not arrive at the server in the same form, but is
changed either during input or during the transmission (in which many components are involved).
Term definitions
l
Password: downwardly compatible / downwardly incompatible
A (plain text) password is downwardly compatible if it consists of a maximum of 8 characters and
contains no lowercase letters.
A (plain text) password is downwardly incompatible if it consists of more than 8 characters or
contains at least one lowercase letter.
Older ABAP systems support downwardly compatible passwords only. In newer ABAP systems
(as of Release 7.00), downwardly incompatible as well as downwardly compatible passwords can
be granted. Since lowercase letters that you enter are now no longer changed to uppercase letters,
the passwords granted in newer ABAP systems are normally downwardly incompatible.
l
Hash password procedure / Code versions
ABAP systems do not save passwords in plain text, but instead calculate a hash value and save
this together with the meta information using the hash password procedure ("code version"). This
information is stored in the user master record and is analyzed during the password check: A hash
value is determined, using the code version specification (from the user master record), from the
plain text password to be checked and is compared with the reference hash value (from the user
master record).
The quantity of the hash password procedure supported is release-dependent, whereby newer
releases always support all procedures of preceding releases. This ensures that a password logon
is also possible after a release upgrade.
Only the hash password procedures available as of Release 7.00 also support the processing of
downwardly incompatible passwords. Older hash password procedures support downwardly
compatible passwords only.
Whether downwardly incompatible passwords are supported or expected during a password logon
depends primarily on the specifications (code version) saved in the user maser record.
6.11.47
Solution
l
When using the technical user (in RFC destinations):
We strongly recommend that you use the SYSTEM user type on the server (or also SERVICE,
provided a SAPGUI capability is required), since the password has unlimited validity only for these
user types (see SAP note 622464). If the password should be entered in an RFC destination of an
older system (= RFC client), it must be granted as a downwardly compatible password on the
server. For users of the SYSTEM or SERVICE type, this is always possible, even if the password
rules of the system normally compel the use of downwardly incompatible passwords (for example,
by login/min_password_lng > 8 or login/min_password_lowercase > 0).
322
Chapter 6 Evaluating the Application Return Code of SAP Steps
l
When using older front-end or middleware components and password logon of "normal"
users (DIALOG type):
In this case, it is not practical to change the passwords of the (numerous) users affected (as in the
above case with technical users). Instead you must replace the obsolete front-end or middleware
components. SAP note 792850 describes as of which version level certain front-end or middleware
components support the interaction with downwardly incompatible passwords. In addition, you may
need to update other software components (attached to these components), as well as those of
external providers. This is particularly the case if these components have their own password input
dialog and are not able to support downwardly incompatible passwords (according to the above
definition of the term).
For the moment, you can set the profile parameter login/password_downwards_compatibility on the
server to the value 2 or 3 for test purposes. In this case, the server checks if the client has sent a
matching downwardly compatible password for the expected downwardly incompatible password
(that is, a password that is 8 characters long and converted to uppercase). If this is the case, it is
logged in the sys log (for error analysis purposes), and the logon is assessed as successful (for
value 3). Using transaction RZ11, you can change the profile parameter dynamically, that is,
without restarting the system.
Automation Engine
6.11.48 Certificates
323
324
Chapter 6 Evaluating the Application Return Code of SAP Steps
Overview
All functions we provide for SAP are certified.
Automation Engine
325
The following table lists all certifications:
Solution Interface Software
SAP Interface
UC4.Agent for SAP
BC-XBP 6.10 - Background Processing, Job Scheduling 6.10 (Vers.
2.0)
BC-XBP 7.0 - Background Processing, Job Scheduling 7.0 (Vers. 3.0)
JAVA-JXBP 7.1
UC4.Agent for SAP BW
BW-SCH 3.0 - Scheduling for SAP BW 3.0
UC4.Agent for Java EE/JMX
JAVA-EE-STD 7.1
See also:
SAP Partner
SAP Developer Network (SDN)
6.12 UC4 and Siebel
6.12.1 Starting and Monitoring Tasks
The Siebel Agent uses the command-line interface of the Siebel Server Manager for executing tasks. Enter
the directory in which it is found in the INI file of the Siebel Agent in the section [VARIABLES].
Example:
[VARIABLES]
UC_SIEBEL_SRVRMGR=C:\siebel\srvrmgr.exe
Commands that should be executed in Siebel can be specified in the Script tab of a Siebel Job. Do so with
the specific script statement SI_START_TASK. The Siebel command is transferred with the parameter
CMD=:
SI_START_TASKCMD="Siebel command"
Each script line with "SI_START_TASK" is a separate task in Siebel. In order to enable task monitoring
(such as canceling or restarting tasks), it is essential that the Siebel command starts with "start task". If
"run task" is used, the Siebel Job is canceled and an error message is printed.
Two log files are available after the execution of the task:
1) Log file of the Siebel Server Manager call
2) Log file of the task
Define in the section [VARIABLES] of the INI file of the Siebel Agent where these log files are stored.
Thus, the log files can be transferred from the Siebel Agent to UC4 in the form of reports.
Example:
[VARIABLES]
UC_SIEBEL_SRVRMGR=C:\siebel\srvrmgr.exe
UC_SIEBEL_LOGPATH=C:\siebel\siebelLOGS\
326
Chapter 6 Evaluating the Application Return Code of SAP Steps
Note that report contents can be read with the script element PREP_PROCESS_REPORT. Report type
"LOG" stands for the log file of the Siebel Server Manager call and report type "REP" for the log file of the
task.
See also:
Tab for Host Attributes - Siebel
6.13 UC4 and UNIX
6.13.1 Authentication of Login Data
Jobs and FileTransfers must log on to the OS before they can be processed. Login data is stored in Login
objects.
The Agent provides two methods of authenticating User name and passwords.
1. Local User authentication
2. Pluggable Authentication Modules (PAM)
PAM authentication is only supported for the Agent on AIX, Linux and Sun Solaris (SPARC).
The method to be applied is specified in the Agent's INI file. The section [MISC] includes the parameter
authentication= to which you can assign the value "local" or "PAM".
Example:
[MISC]
authentification=local
If you opt for PAM authentication, also specify the library name.
Example:
[PAM]
Libname=libpam.so
Store the path for the library in the environment variable LD_LIBRARY_PATH if it is not stored in the
default directory.
The Agent must have root privileges.
See also:
Login Object
Automation Engine
327
6.13.2 Shell and Shell Options
A shell under which a particular job should run can be specified in the Unix tab which is available for Unix
jobs. Options can also be specified for calling this Shell. If no shell is defined, the default shell from the
passwd file is used.
Shells selected in the Unix tab are maintained in the UC4 Variable UC_SHELL_UNIX of client 0000. The
following shells are available by default:
l
l
l
l
l
bash
csh
ksh
sh
tcsh
You can add additional shells in the UC4 Variable UC_SHELL_UNIX. Additionally, a shell-specific script
line must be inserted in the Include "TRAILER.UNIX". The following format should be used:
##UC4[Shell]Shell specific command
Determining the Shell Path
1. If a path string has been defined in the configuration file (section STARTCMD, parameter "shell_
pfad"), this path is used.
Format Path String: <Path name1>[:<Path name2>]...
Format Path name: /<dir1>[/<dir2>]...
2. If the parameter "shell_pfad" has not been specified, the environment variable PATH is read and
used.
3. If no PATH environment variable is available, the "/bin" directory is used.
The shell file name is composed of the retrieved shell path and the selected shell (Host Attributes tab)
and checked for the availability of the right to execute. If this file must not be executed or cannot be found,
an information message is output. The user's default shell which has been defined in the passwd file is
then used. If no shell has been specified in the passwd file, the bourne shell from "/bin/sh" is used.
Determining Shell Options
If shell options have been specified in the Host Attributes tab, these are used.
Shell options may be defined in the configuration file (section STARTCMD, variables "Bourne_Shell_Opt",
"Korn_Shell_Opt" and "C_Shell_Opt")
If no options were specified at all, the default option "-c" in the program applies.
6.13.3 User ID for the UNIX Agent
The Agent for UNIX must be installed under a user ID which must fulfill the following requirements:
l
The subdirectory "temp" must be defined in a way that it can be read from any other user ID. For
this, its not sufficient to only supply this directory with read rights. All directories from the root
328
Chapter 6 Evaluating the Application Return Code of SAP Steps
l
directory on must have read rights.
The subdirectory "out" must be defined in a way that it can be written to from any other user ID. For
this, all superordinate directories must have at least read rights (see above).
6.13.4 UNIX Agent - FileTransfer Support
When defining a FileTransfer object, you can also specify additionaloptions in the FileTransfer tab, File
Attributes field.
Under UNIX, there are no file attributes. Therefore, all specifications are ignored, except for the options
reclen and nl. Note that several options need to be separated with a comma.
Sender's File Attributes:
l
l
reclen - Record length specified in bytes
nl=mixed -a CR character used at the end of a text file's line can corrupt the file in some systems.
The value "mixed" automatically removes this character.
Receiver's File Attributes:
l
nl - character for inserting line breaks
Allowed values: "crlf", "lf" (default value) and "none"
"crlf" - carriage return and line feed
"lf" - line feed
"none" - no line break is made
Example: nl=crlf
6.13.5 Rights for Deleting Source Files in FileTransfers
In FileTransfers, you can define that the relevant file will be deleted after it has been transferred. Several
rights must be checked if the source is UNIX. The following flow chart explains the process details.
Flowchart details
User UID = UID of the user who has been specified in the Login object of the source (FileTransfer tab,
From area).
Deletion right = The right "wx" to access the folder in which the file is stored.
When checking User GID=Folder GID, the system verifies that the user is a member of the same Group
as the folder.
Automation Engine
329
6.13.6 Querying the Unix File System
An example will demonstrate how to use the UC4 utility UCXE???F to query the Unix file system.
The following files should be listed:
l
l
l
those which are located in the home directory of the signature UC4 and in all subdirectories,
those which have last been modified between 10.1.1999 00:00 and 10.7.1999 23:50 and
those which have a file size between 1 and 9999 bytes.
The creation, the forming up and the processing of a data sequence is a complex process in which script
functions and statements as well as special objects cooperate closely. The following example shows the
330
Chapter 6 Evaluating the Application Return Code of SAP Steps
necessary definitions for the involved objects and the corresponding script statements and their
references. The example is intentionally kept small and clear to show the principles.
The UC4 utility UCXE???F offers wider query possibilities compared to the traditional operating
system command ls. It has to be installed on the host. The question marks in the program name are
placeholders for System ID and Version of the Unix derivative.
Job: SC.PROCESS.UNIXFS
The script of the job calls the function PREP_PROCESS, which prepares the processing of the data
sequence. The following parameters are passed:
l
l
l
l
l
Name of the computer on which an Event job is to be executed - in this case: SOLARIS.
Type of the Event job to be executed - in this case UNIXFS.
By specifying UNIXFS, the job EVENT.UNIXFS will be executed.
By default the Event jobs EVENT.BS2000.CMD, EVENT.BS2000UCON, EVENT.UNIXCMD,
EVENT.UNIXFS and EVENT.WINCMD are supplied with client 0000. They can be used as they
are or as a template for your own Event jobs.
The third function parameter specifies which lines produced by the command should be taken into
account. By using the wildcard character "*", all lines will be accepted.
With the keywords PATH and FSPAR, you specify additional parameters containing the actual
queries of the Unix file system. Following the keyword FSPAR are other keywords as well as value
assignments for the modification time frame, the file size and the inclusion of subdirectories. The
definition of the modification time frame clearly shows the following particularities: The beginning is
specified without a time. This automatically sets the time to 00:00. The end is made up of date and
time specification, separated by a blank. Because blanks separate each specification within the
parameter, the date and time specification has to be between quotation marks.
The Login object UC4ADMIN is used.
Automation Engine
The job SC.PROCESS.UNIXFS will then be started.
Job: EVENT.UNIXFS
This is the job EVENT.UNIXFS from client 0000. It is supplied by default.
331
332
Chapter 6 Evaluating the Application Return Code of SAP Steps
It is important that the check box "Attribute dialog" is checked in its Notification tab That way the Include
object ATTRDIA.BS2000 is read which normally causes the start of the Attribute Dialog.
Include: ATTRDIA.UNIX
All attributes listed in the script of the Include can be supplied. The script variable &UC_USERID receives
the value UC4. The Attribute Dialog is not displayed because the passing of the variable contents is done
internally.
Job: EVENT.UNIXFS
Automation Engine
333
At the start of the job EVENT.UNIXFS, the script variables &PATH and &FSPAR are supplied with
values. These values are defined in the parameters of the script function PREP_PROCESS of the job
SC.PROCESS.UNIXFS. The UC4 utility is called with these specifications. It retrieves the requested
information on the Unix file system. It is not necessary to replace the question marks in the program name.
The utility can be called in this way after a correct installation.
The outfile is transferred to the UC4 Automation Engine via file transfer and is then available as a data
sequence. The execution of the job EVENT.UNIXFS is then completed.
Job: SC.PROCESS.UNIXFS
334
Chapter 6 Evaluating the Application Return Code of SAP Steps
The function PREP_PROCESS returns a value that is a handle for information on the data sequence that
will be processed.
This value is passed to the statement :PROCESS as a start parameter, :PROCESS and
:ENDPROCESS then form a processing loop which, in this case, will be cycled until the end of the data
sequence is reached. During each iteration a new line of the data sequence is fetched from memory. The
function GET_PROCESS_LINE can - by using the current value - retrieve the content of the current line.
In the example, the current console line is written to the activation protocol.
The :STOP statement interrupts the execution and displays this activation report.
6.13.7 PREP_PROCESS - Querying the UNIX File System
UC4 supplies the utility UCXE???F which can be used to query the UNIX file system. The question marks
are placeholders for the UNIX system's system ID and version number.
Using this utility extends the query options compared to the usual OS command "ls". To obtain information
about the UNIX file system, you must specify the parameters of the script statement PREP_PROCESS
in a specific syntax.
In one of this script function's parameters, you can specify the file name including the path. This parameter
starts with the keyword PATH. To specify the file name, you can use the wildcards "*" and "?". "*"
represents any number of characters, "?" represents exactly one. The current directory is used if neither
path nor file name are specified. Relative path indications are not yet supported.
A different parameter starts with the keyword FSPAR. It stores the specifications for querying the file
system. These specifications consist of a keyword and a value. Several additional specifications must be
separated with a blank. Enclose a value in double quotation marks if it includes a blank (for example,
ATIME="980101 1000").
Automation Engine
Keyword
Value/Description
PATH (or:
PFAD)
This is the parameter keyword for the file-name specification, including its full path
description.
FSPAR
This is the parameter keyword for the file-system query.
TYPE
The specification of a file type:
335
- for a regular file
D for a directory file
L for a symbolic reference (not applicable in POSIX.1 or SVR4)
B for a block-oriented device file
C for a character-oriented device file
P for a Pipe or a FIFO
S for a Socket (not applicable in POSIX.1 or SVR4)
Default value: all file types.
SIZE
The selection criteria for the file size.
OWNER
The name of the owner of the files (User), not the User ID.
GROUP
The name of the owners of the file (Group), not the Group ID.
ATIME
The time of the last access.
MTIME
The time of the last modification of the file system.
STIME
The time of the change of the file status.
MODE
When you specify "RECURSIVE", the subordinate directories will also be checked.
Comments
SIZE can only be specified for regular files. If SIZE has been defined, the TYPE definition is internally set
to a regular file. The file size is specified in bytes.
For example:
SIZE=100,
SIZE=100
SIZE=,100
SIZE=100,4000
Files as of 100 bytes
Files up to 100 bytes
Files up to 100 bytes
Files between 100 and 4000 bytes
The following date and time formats can be used to specify ATIME, MTIME and STIME. The following
abbreviations are used: "Y" for the year, "M" for the month and "D" for the day. If no time is specified, UC4
uses the value "0000".
YYYYMMDD,
"YYYYMMDD HHMM",
YYMMDD,
"YYMMDD HHMM".
For example:
ATIME=19971231
All files until this date
ATIME=,19971231
All files until this date
ATIME=19971231,
All files as of this date
ATIME=19970101,19971231 All files as of the first date to the second date
336
Chapter 6 Evaluating the Application Return Code of SAP Steps
Examples
All home-directory files with the ID UC4 which were last accessed between 6 October 1997, 12:00 and 31
December 1998, 23:50 and which have a file size between 1 and 9999 bytes are listed. All subdirectories
of the home directory are considered.
:SET &HND = PREP_PROCESS('SOLARIS','UNIXFS','*','UC_LOGIN=UC4','PATH=./*',
'FSPAR=ATIME="19971006 1200","19981231 2350" SIZE=1,9999 MODE=RECURSIVE')
See also:
Querying the UNIX File System
About Scripts
Script Elements - Alphabetical Listing
Script Elements - Ordered by Function
6.13.8 AIX Process Abort Due To Lack of Memory
Programs on AIX can abort if the memory allocated to a process is not sufficient for the ongoing
processing.
On AIX systems, 256 MB are allocated to each process by default. This memory limit can be increased to
a maximum of 2 GB using the Environment Variable LDR_CNTRL.
This variable must be set before starting a UC4 Automation Engine on AIX.
Execute the following commands:
LDR_CNTRL=MAXDATA=0x80000000
export LDR_CNTRL
Value 8 stands for 8x256MB (max. value) => 2 GB
Using this parameterization, up to 2 GB memory can be allocated even from a 32-bit Agent. Aborts due to
insufficient memory can occur during the transfer or processing of huge spool lists or reports.
For Jobs which require more than 2 GB memory, the User must increase the limit in the Job using the
command ulimit (authorization required). It is also possible to define that there is no memory limit. This
can be defined in the Job using the command ulimit -d unlimited.
6.13.9 Enlarging Core Files
It is important to have a complete Core file in order to be able to analyze problems if errors occur. By
default, AIX only generates minimum Core files. Therefore, specify the value "true" for the system
environment variable "fullcore" .
Start off by querying the variable. "sys0" stands for the device name.
lsattr -El sys0 | grep fullcore
The default result is:
fullcore
false
Enable full CORE dump
True
Automation Engine
337
There are several ways that can be used to set the variable fullcore to the value "True". The easiest one is
to call the tool "smit" with the root user using the parameter "chgsys".
smit chgsys
Use this tool to set the variable "Enable full CORE dump" to the value "true". By doing so, the variable
"fullcore" is activated on a system-wide basis.
Two other parameters can also be used to specify the maximum file size (which includes the Core file's
size). Query the specified values with the command "ulimit":
ulimit -a
Possible output is shown below:
file(blocks)
coredump(blocks)
2097151 <-- !
2097151 <-- !
The command "ulimit" can be used to change values. The option "-f" indicates the maximum file size in
blocks of 512 bytes.
Example:
ulimit -f 4096
# 4096 * 512 Bytes
ulimit -f unlimited
The option "-c" defines the maximum size of Core files in blocks of 512 bytes or unlimited.
Examples:
ulimit -c 4096
# 4096 * 512 Bytes
ulimit -c unlimited
6.13.10 Return Codes for UNIX Jobs
The Agent logs all occurring errors in the Job's activation report.
Depending on the Job's execution, it also sets one of the following return codes:
Return code
Description
0
No error occurred.
1-200
OS error codes
201
setgid() - The Agent does not have the required privileges.
202
initgroup() - The Agent does not have the required privileges.
203
setuid() - The Agent does not have the required privileges.
205
chdir() - Change directory for Job user does not exist.
206
The Job report file cannot be opened.
208
dup2(STDOUT) - Standard output cannot be assigned.
209
dup2(STDERR) - Standard error output cannot be assigned.
210
execle() error - Job file cannot be started.
338
Chapter 6 Evaluating the Application Return Code of SAP Steps
You can define the return code as of which the Job should abort in the Job object's Runtime tab.
6.13.11 Activating Job Messenger Traces
The following guide describes the activation of a trace output for UNIX and VMS Job messengers. Doing
so is possible per Job, per client or for the whole system.
The Agent writes Job messenger traces to the Job report (REP). These outputs are found at the report's
beginning (start messenger) and its end (end messenger). They contain information about the messenger's
connection status. Trace output is automatically activated if an error occurs in combination with the
messenger program.
Activate the output as follows:
Use the parameter TRC= when calling the Job messenger program in the Trailer and/or Header Include
(see: Job Includes). It is automatically included in the Unix Job Includes. The predefined script variable
&UC_MD_JOB_TRC will be assigned to this parameter. Thus, you can activate ('1') or deactivate ('0')
trace output by using this variable.
Trace activation is possible to the following extent:
l
For all of a UC4 system's Jobs
Setting in the Header / Trailer - Includes in system client 0.
We do not recommend using this setting because it will significantly increase the report size of
all UNIX and VMS Jobs and prolong runtimes.
l
l
For all of a client's Jobs
Create and adjust the Header / Trailer Includes in the client's folder <No Folder>.
Per Job (recommended)
Set the script variable in the PreProcess tab.
By default, the activation of Job messenger trace outputs is provided in the Header Include of UNIX Jobs.
Open the Include object HEADER.UNIX in the system client. It contains the definition for the variable
&UC_JOB_MD_TRC. This variable's value will be passed on to the parameter TRC= when the Job
messenger is called (JCL line).
Automation Engine
339
You can activate the trace output for a particular UNIX Job by inserting the following scripting line in the
PreProcess tab:
:SET &UC_JOB_MD_TRC = '1'
340
Chapter 6 Evaluating the Application Return Code of SAP Steps
See also:
Agent's Job Messenger
Logging/Trace
6.13.12 Solaris: Separating Jobs from Agent Processes
When you start the agent under Solaris by using SMF, all the processes (jobs) that this agent starts will run
in the same contract. The effect is that when this agent crashes, ends or is restarted, all its processes will
also end. To solve this problems, you can separate the jobs from the agent contract so that they can run
without being affected by the agent processes.
The following steps are required for this purpose:
Step 1: Create the two shell script files chk-uc4-start.ksh and chk-uc4.ksh with the following contents:
chk-uc4-start.ksh:
nohup /usr/local/bin/sudo -u mgws /var/tmp/chk-uc4.ksh&
chk-uc4.ksh :
while true
do
echo "$(date) $0" >> /var/tmp/chk-uc4.log
sleep 10
done
Automation Engine
341
Step 2: In the job script, call the shell script chk-uc4-start.ksh with the utility "ctrun" and at the beginning
of the job script, insert the following line:
ctrun -l child /var/tmp/chk-uc4-start.ksh
6.13.13 Resource Limitation by using ulimit
You can use the UNIX command "ulimit" in order to limit OS resources per OS user. In doing so, you
ensure that users do not create too many resources which could negatively affect the performance of your
system.
UC4 recommends that you do not define any limit for the user under which UC4 components start. It can
occur that a component that is affected by such a limit cannot work as required (for example, the agent
cannot open the report) or it rare cases, it can even happen that the program crashes.
UC4 recommends removing or not using limits or when necessary, defining very high values for them.
These recommendations for limits affect all UC4 components that run under UNIX, which includes the
UNIX agent, the utilities, the UserInterface, and also the Java and ERP agents.
You can use the resource concept of the UC4 Automation Engine in order to save OS resources.
6.14 UC4 and VMS
6.14.1 VMS Agent - FileTransfer Support
When defining a FileTransfer object, file attributes for its destination can additionally be specified in the
FileTransfer tab.
Possible attributes
Attribute
Attribute description
alq = number
Allocation quantity; ignored
if an allocation XAB is
present.
bls = number
Device block size (applies
to files of sequential
organization only)
deq = number
Default extension quantity
fop = value,
value, ...
File processing options
Possible
values
Description
ctg
Contiguous: indicates that the space for
a file is to be allocated contiguously.
cbt
Contiguous-best-try.
cif
Create if nonexistent.
342
Chapter 6 Evaluating the Application Return Code of SAP Steps
fsz = number
Fixed header size.
gbc = number
The requested number of
global buffers for a file.
mbc = number
Multiblock count.
mbf = number
Multibuffer count.
mrs = number
Maximum record size.
rat = value,
value, ...
Record Attribute
rfm = value
Record Format
dfw
Deferred write: writing back to the file
from the modified buffer is deferred.
Applies to relative and indexed files and
sequential files opened for shared
access.
dlt
Delete file on close.
mxw
Maximize version number.
nef
Not end-of-file.
pos
Current position.
rck
Read check compare operation.
rwc
Rewind file on close.
rwo
Rewind file on open.
scf
Submit as command file on close.
spl
Spool to system printer on close.
sqo
File can only be processed in a
sequential manner.
sup
Supersede.
tef
Truncate at end-of-file.
tmd
Temporary delete.
tmp
Temporary (no file directory).
wck
Write check compare operation.
cr
Carriage-return control.
blk
Disallow records to span block
boundaries.
ftn
Fortran print control.
none
Explicitly forces no carriage control.
prn
Print file format.
fix
Fixed length record format.
stm
RMS stream record format.
stmlf
Stream format with line-feed terminator.
stmcr
Stream format with carriage-return
terminator.
udf
Undefined.
Automation Engine
rop = value,
value,...
Record processing
Operations
343
var
Variable length record format.
vcf
Variable length record with fixed control.
asy
Asynchronous I/O.
cco
Cancels Ctrl/O (used with Terminal
I/O).
cvt
Capitalizes characters on a read from
the terminal.
eof
Positions the record stream to the endof-file for the connect operation only.
nlk
Do not lock record.
pmt
Enables use of the prompt specified by
"pmt=usr-prmpt" on input from the
terminal.
pta
Eliminates any information in the typeahead buffer on a read from the
terminal.
rah
Read ahead.
rea
Locks record for a read operation for this
process, while allowing other accessors
to read the record.
rlk
Locks record for write.
rne
Suppresses echoing of input data on the
screen as it is entered on the keyboard.
rnf
Indicates that Ctrl/U, Ctrl/R, and
DELETE are not to be considered
control commands on terminal input, but
are to be passed to the application
program.
rrl
Reads regardless of lock.
syncsts
Returns a success status of RMS$_
SYNCH if the requested service
completes its task immediately.
tmo
Timeout I/O.
tpt
Allows put/write services using
sequential record access mode to occur
at any point in the file, truncating the file
at that point.
ulk
Prohibits RMS from automatically
unlocking records.
wat
Wait until record is available, if currently
locked by another stream.
wbh/nowbh
Write behind.
344
Chapter 6 Evaluating the Application Return Code of SAP Steps
6.14.2 Return Codes of VMS Jobs
Return codes in VMS differ from those in UC4. Value "1" in VMS signals that a job has successfully been
processed. "0" stands for warnings. In UC4, it is the opposite way round. Return code "0" stands for a
successful execution and values other than "0" signal errors.
If the Agent sends return code "0" to the UC4 system, this equals code "1" in UC4.
Warnings and successful job executions cannot be distinguished. UC4 strongly recommends analyzing
the variable $severity whenever a VMS command has been processed. It contains the return code of the
last command. Further job processing can then be handled via script.
Use an Include object for analyzing the variable $severity. In doing so, the relevant script lines must
only be maintained in one object and can be included in any job.
Example for an Include object:
$
$
$
$
$
$
RETCODE = $severity
if (RETCODE .EQ. 0)
then
RETCODE = 3
goto RETURN
endif
The system checks whether the returned code is a warning. If so, job execution is continued in the Trailer.
"goto RETURN" leads to the Include object "TRAILER.VMS" which is processed when a job has ended.
See also:
Job - Includes
6.15 UC4 and WebSphere MQ
6.15.1 UC4 Connector for WebSphere MQ Queue Manager
The UC4 Connector is the link between WebSphere MQ Queue Manager and the UC4 Automation Engine.
Automation Engine
345
The UC4 Connector reads a request, a message in XML format, from the request queue (SIQ) and
forwards it for processing to the UC4 Automation Engine. An internal format is used for this. The UC4
Connector waits for the UC4 Server to verify processing and notify the end of the process. Here an internal
format is also used. The answer is assigned to the request from the UC4 Connector and written in XML
format into the reply queue (CIQ).
XML Request Message
XML element
Description
<apiscriptexec>
Start of API request.
XML element must be present.
<uc-env request="ID"
release="1">
The ID identifies the request.
The "request=" attribute must be entered. The UC4 Connector refers to
this ID in its messages. This ID is also written in the reply message.
The "release=" attribute is not required. If it is still entered, at the
moment only the value "1" is allowed. On the future this attribute will
serve as the version entry.
XML element must be present.
<requestname name="any
name">
Name of the request.
Attribute "name=" is not required.
XML element must be present.
<control>
XML element must be present.
<timeout unit="sec">10</timeout>
Request runtime limit.
Runtime starts before establishing connection with the UC4
Automation Engine and ends when UC4 accepts execution or an
unrecoverable error occurs. The "unit=" attribute is used to define the
runtime unit.
Allowed values: "1" - "31999"
Default: "10"
XML element is not necessary.
<control
unit="sec">20</control>
Not yet supported by current version.
</control>
Element termination <control>
XML element is not necessary.
XML element is not necessary.
<login>
Start of element for login information.
XML element must be present.
<system>UC4 Automation
Engine name</system>
Name of UC4 Automation Engine.
The name is used for checking the connection to the UC4 Automation
Engine. The contents correspond to the name= parameter in the INI file
of the UC4 Automation Engine to which the UC4 Connector has
established a connection.
XML element must be present.
346
Chapter 6 Evaluating the Application Return Code of SAP Steps
<client>client number</client> Client number for logging on to the UC4 Automation Engine.
XML element must be present.
<name>user name</name>
User name for logging on to the UC4 Automation Engine.
XML element must be present.
<department>user's
department</department>
Designation of user's department for logging on to the UC4 Server.
<passw>password</passw>
User password for logging on to the UC4 Automation Engine.
XML element must be present.
XML element is not necessary.
<language>E/D/F</language> Choice of language in which messages are to be output.
If no language is specified, massages are written according to the
setting in the INI file of the UC4 Connector.
XML element is not necessary.
<clienttype>C</clienttype>
Clients type.
If the type is to be specified, currently only "C" is allowed.
XML element is not necessary.
<clientvers>client
version</clientvers
Version of UC4 Connector.
Allowed values: Current Version
XML element is not necessary.
</login>
Termination for XML element <login>.
XML element must be present.
<script><![CDATA[Script
content]]></script>
Script statements to be executed in UC4.
</request>
Termination for XML element <request>.
XML element must be present.
XML element must be present.
</uc-env>
Termination for XML element <uc-env>.
XML element must be present.
</apiscriptexec>
Termination for XML element <apiscriptexec>.
XML element must be present.
Example of Request
<apiscriptexec>
<uc-env request="ID1" release="1">
<request name="apiscriptexec">
<control>
<timeout unit="sec">10</timeout>
</control>
<login>
<system>UC4</system>
<client>97</client>
Automation Engine
347
<name>NAME01</name>
<department>DEPARTMENT01</department>
<passw></passw>
<language>D</language>
<clienttype>C</clienttype>
<clientvers>3.02A</clientvers>
</login>
<script><![CDATA[:SET &RUNNR = ACTIVATE_UC_OBJECT
(JOBS,EXAMPLE1)]]></script>
</request>
</uc-env>
</apiscriptexec>
XML Reply Message
XML Element
Description
<apiscriptexec>
Outer message frame.
XML element is always present.
<uc-env request="ID"
release="1">
The provided ID is removed from its corresponding request.
The "request=" attribute is always output.
XML element is always present.
<result name="Reply">
XML element is always present.
<status>reason</status>
Reason for this reply to a request.
Currently the reply is always "completed".
XML element is always present.
<complcode>code</complcode>
Completion code supplied by the UC4 Connector for the executed
request. All possible codes are described in the message manual.
XML element is always present.
<compltext>![CDATA[completion Description text for completion code.
text]]</compltext>
XML element is always present.
<returnvalue>value</returnvalue> Return value from components which were present during
processing (UC4 Automation Engine, XML Parser, etc.).
XML element is always present.
<returntext>![CDATA[return text]] Description of return value.
</returntext>
XML element is always present.
</result>
Termination for XML element <result>.
XML element is always present.
</uc-env>
Termination for XML element <uc-env>.
XML element is always present.
</apiscriptexec>
Termination for XML element <apiscriptexec>.
XML element is always present.
348
Chapter 6 Evaluating the Application Return Code of SAP Steps
6.16 UC4 and Windows
6.16.1 Starting Programs Under Windows
Attributes
The following parameters are important when you start Jobs under Windows:
Domain
Windows domain in which the user is defined.
User Name
The Windows user name.
Password
The user's password.
BATCH (login type)
You can allow a user to use particular login types. The login types interactive and batch can be
used. For example, if a user is only allowed to log on via batch, this user can start Jobs only in
batch mode. The parameter BATCH must be specified in this case.
DESKTOP
This option should be specified if the Job that should start expects particular user inputs. The
process is then visible for any user who is logged in. This user can enter the required user inputs.
If this option is not specified and the process requires an input, the job hangs and can only be
removed by using the Task Manager.
Attributes are defined in the attribute cards of the Job.
Attention
l
l
l
l
Attributes are defined in the attribute cards of the Job.
All parameters except for the password are defined in the Job attributes.
The password is read from the Login object.
These new options (compared to version 1.10) are only available if parameter "logon=1" is specified
in the Agent's INI-file section [GLOBAL]. This parameter should be set if the Agent starts as a
service.
Automation Engine
349
System Dependencies
Depending on the operating system and the Agent's start type, there are the following dependencies that
apply:
Agent
INI File
User
BATCH
DESKTOP
Agent on desktop logon=0
1.
1.
1. Agent on desktop logon=1
2.
2.
2. Agent as a service logon=1
3.
3.
3. 1. Irrelevant, the system starts on the desktop using the user's name and rights.
2. Is used - The desktop user must have the appropriate privileges (such as a system user).
3. Is used.
Note the following peculiarities:
l
Difference between an interactive login and a Win32 Agent login:
The Agent does not load the Job's user profile to the registry database. That means that a
program that stores user-specific data in the registry (for example, the UC4 Dialog stores the
latest logon) cannot access a this data through a UC4 Job.
l
Start path:
The start path is a CreateProcess and CreateProcessAsUser parameter. It is not an
obligatory UC4 parameter. If it is not specified, the Agent passes it on to the UC4 Job.
It is important to know that you can specify a start path in the user definition. This start path
is used if a normal interactive logon is made. Note that it cannot be analyzed when you start
the Job using UC4.
UC4 recommends always specifying the start path.
Strategy for Jobs under Windows
Windows distinguishes four program types.
1.
2.
3.
4.
Programs with a graphical user interface (32-bit and 16-bit GUI programs).
32-bit console programs.
Old DOS programs.
Operating system commands (not a real program, for example, DIR, SET etc.).
Types 1 and 2 (GUI and console programs) should be started from the command line if possible.
The advantage is that UC4 can retrieve the correct program exit code.
Type 3 and 4 (DOS programs and OS commands) can only be started through a BAT file. The Job
ends correctly or incorrectly using the Job Messenger mechanism.
UC4 recommends testing the BAT file or the command line on the target system before you start
the Job via UC4. Use the user who should later execute the UC4 if possible.
Using graphical programs can always cause unexpected user dialogs (message box). UC4
recommends using the option DESKTOP for test runs.
Job report: The program output after STDOUT and STDERR is the Job report of a Windows Job.
Usually, only 32-bit console programs and most DOS programs create a Job report.
350
Chapter 6 Evaluating the Application Return Code of SAP Steps
6.16.2 Test Programs for the Windows Agent
Purpose
There are various ways of starting Windows jobs or programs. Therefore, UC4 supplies a number of test
programs which in the various modes in Windows.
Files
The programs are found in the subdirectory EXAMPLE of the Windows Agent
(CD:AGENTS\WINDOWS...).
The following programs are supplied:
UCYBTX86C - 32Bit Console Program (DOS-Window)
UCYBTX86G - 32Bit GUI Program (Visual C++)
UCYBTX86V - 32Bit GUI Program (Visual Basic)
UCYBTIA64C - 64Bit Console Program (DOS-Window)
UCYBTX64C - 64Bit Console Program (DOS-Window)
Operating the Test Programs
The test programs do not have an actual function. their execution can be controlled through parameters in
the startup options.
/w<n> Wait <n> seconds /d Run Dialog (e.g. file selection)
/m Message (message box)
/o<n>
Output <n> lines in this standard output (=Jobreport)
/r<n> Set return code to <n> The parameters are executed in the order of their appearance.
Not every parameter is possible with every program:
Program
/w<n> wait
/d Dialog
/m Message
Box
/o<n>
STDOUT
/r<n>
Retcode
UCYBTX86C Yes
Yes
Yes
Yes
Yes UCYBTX86G Yes
Yes (file selection)
Yes
Yes
Yes UCYBTX86V
Yes (Loop)
Yes (file selection)
Yes
No
Yes UCYBTIA64C
Yes
Yes
Yes
Yes
Yes
UCYBTX64C
Yes
Yes
Yes
Yes
Yes
Example
UCYBTX86G /w10 /d /r4
Automation Engine
351
The 32Bit GUI program is started. It waits for 10 seconds, executes the file dialog without effect, sets the
return code to 4 and closes itself.
6.16.3 Windows Job Object
The execution of Windows Jobs initiates processes such as program starts.
A Windows Job object combines all the processes of a Window Job and provides the following
advantages:
l
l
l
CPU-time measuring includes all sub-processes,
the Windows Job does not end before all sub-processes have ended,
when a Windows Job is canceled, all sub-processes are also canceled
In the host tab of a Windows Job, you can specify whether it should run in a Windows Job object or not.
You can also specify this setting in the Windows Agent's INI file. This setting is then used as the default
value and is used for all Windows Jobs.
[GLOBAL]
;...
useJobObject=1
Refer to the report of a Windows Jobs to see if it has run with a Windows Job object.
Example:
The setting "Job Object - Yes" has been checked in the host tab of a Windows Job. The Process tab
contains the command Start "New Window" which starts a new process. This Windows Job only
ends when you quit the new window using the "exit" command. It is displayed in the Activity Window until
then as the following illustration shows.
The Windows are only displayed when the option Show job at the desktop is activated in the host tab
or when the Windows Agent does not run as a service.
352
Chapter 6 Evaluating the Application Return Code of SAP Steps
6.16.4 Reports of Windows Jobs
The reports of Windows Jobs have some special features.
Generating Job Reports through Script
Use the host specific Windows tab to specify if the Job report should be stored in the database and/or in a
file. It is also possible to define that a report should only be stored in case of an error.
The option Is generated by script serves programs whose outputs are supplied in files. If this
specification has been activated, the Job reports contain the program outputs.
Automation Engine
353
With each Job execution, an extra file is created for the Job report. Use the attribute "FILENAME_
SYSOUT" to retrieve these files' names which are composed of the individual run numbers (RunID). The
path for the Job report can be set with the UC4 Variable "UC_EX_PATH_JOBREPORT" and read with the
script function GET_VAR. Finally, the retrieved information can be assigned to the program.
Example:
:SET &job_report_path# = GET_VAR(UC_EX_PATH_JOBREPORT)
:SET &job_report_filename# = GET_ATT(FILENAME_SYSOUT)
isqlw -S PC1\SQL2000 -d TEST_DB -U sa -i c:\temp\test.sql -o &job_report_
path#&job_report_filename#
Windows Job Object
Reports of Windows Jobs show whether a particular Job used a Windows Job Object. The end of the UC4
Job Messenger then supplies different information:
Example: Without Job Object:
UCMDJP:
UCMDJP:
UCMDJP:
UCMDJP:
UCMDJP:
*******************************************************************
** JOB 26181380 (ProcID:0000005796) ENDED AT 22.07.2004/15:02:10 **
** ------------------------------------------------------------- **
**
USED:
@ CPU
**
*******************************************************************
Example: With Job Object:
UCMDJP:
UCMDJP:
UCMDJP:
UCMDJP:
UCMDJP:
UCMDJP:
UCMDJP:
*******************************************************************
** JOB 26181383 (ProcID:0000001416) ENDED AT 22.07.2004/15:03:09 **
** ------------------------------------------------------------- **
**
USED:
0.188 CPU
**
**
1154 PAGE FAULTS **
**
3 PROCESSES
**
*******************************************************************
See also:
Report for Executable Objects
6.16.5 User Account Control in Windows 2008 and Vista
If you intend to open programs via UC4 Jobs that require "Elevation" (a higher authorization), you can do
so by selecting the option log on as batch user.
No automatic elevation is possible if the batch mode is not activated. The Windows user under which the
Job is executed requires the right to log on as batch job (System Control - Administration - Local Security
Policy).
The relevant Job will automatically be elevated if it requires more authorization. Therefore, the user who is
specified in the Login object must have the required authorizations. Note that all processes of the affected
354
Chapter 6 Evaluating the Application Return Code of SAP Steps
UC4 Job will be executed with these rights. If the relevant user does not have one or several of the
required rights, the Agent cannot execute all processes. Windows then aborts with the error 740 (elevation
required).
On Windows 2012 you should also change the relevant entries in the registry. It is not sufficient to
change the UAC privileges by using the control panel in Windows 2012.
Comment
The Windows-UAC displays a message asking users to confirm execution of functions and programs,
according to permissions that have been set for the respective user.
This behaviour cannot be controlled via the Automation Engine. You should set the relevant permissions
according to the notes on installation in the Automation Engine documentation relevant to Agents, Jobs,
etc.
6.16.6 Retrieving the CPU Number
The number of CPUs of the computer on which the Agent runs is output in the log file and in the System
Overview.
Hyper-threading
For technical reasons, the Windows Agent cannot retrieve the correct number of CPUs for all supported
Windows versions if the computer runs with hyper-thread turned on. In such a case, the Agent supplies a
lower number of CPUs than is actually available. The following table lists the Windows versions for which
the number of CPUs is correctly retrieved:
Windows version
x86
x64
Windows 2003
Yes
Yes
Windows XP
As of Service Pack 3
As of Service Pack 3
Windows Vista
Yes
Yes
Windows 2008
Yes
Yes
6.16.7 Libraries in Windows 7
This is an important note for using UC4 for Windows 7 in combination with the new function "Libraries".
Libraries in Windows 7 are "virtual folders" which can be used to combine contents that have been stored
in different locations. In other words, they are a collection of different directories.
These virtual directories can be accessed via the path "Libraries" (e.g. "Libraries\Documents"). This is a
"relative path" because it does not indicate the actual storage location. Thus, it cannot be used in
combination with UC4.
This note is of special importance if Agents are used for FileTransfers which run on Windows 7.
The absolute path is required to access Libraries using UC4. Under Windows 7, Libraries are stored in the
following directory:
Automation Engine
355
C:\Users\%Username%\AppData\Roaming\Microsoft\Windows\Libraries\
6.16.8 Windows Agent - FileTransfer Support
When defining a FileTransfer object, you can also specify additional details in the FileTransfer field.
These details can be file attributes of the operating system or additional options which are only evaluated
by the Agent. Note that several attributes and options need to be separated with commas.
Windows File Attributes
File attributes can be specified for the FileTransfer's destination.
You can also override the original attributes. This means that even if the option Keep original attributes
has been activated, the attributes that should be passed on to the target should be overwritten (e.g.,
setting a read-only permission for all destination files).
The value "YES" sets an attribute, "NO" removes it.
Example: ARCHIVE=YES, HIDDEN=NO
Attribute
Description
ARCHIVE
Archive (file has changed since the last backup was made)
COMPRESSED
Compressed file
ENCRYPTED
Encrypted file
HIDDEN
Hidden file
READONLY
File is read only
SYSTEM
System file
Additional Options
You can specify particular options in addition to the operating system's file attributes in the File attributes
field. They affect the formatting of the file content, but are not file attributes. These options are also
available for UNIX Agents.
Options for the sender's file attributes
l
l
reclen - record length specified in bytes.
nl=mixed - a CR character used at the end of a text file's line can corrupt the file in some systems.
The value "mixed" automatically removes this character.
Options for the receiver's file attributes
l
nl character for inserting line separation.
Allowed values: "crlf", "lf" (default) and "none"
"crlf" - carriage return and line feed.
"lf" - line feed.
"none" - no line break.
Example: nl=crlf
356
Chapter 6 Evaluating the Application Return Code of SAP Steps
6.17 UC4 and z/OS
6.17.1 Agent - Interaction between UC4 and z/OS
The z/OS Agent works together with the UC4 system via a TCP/IP interface.
It communicates within z/OS exclusively with JES2 or JES3.
The z/OS Agent provides the following functions:
l
l
l
l
Jobs Processing
Execution of FileTransfers
Event Handling
CallAPI
Job Processing
In UC4, Jobs are defined and maintained in the form of objects that include various tabs. The JCL is stored
in the Process tab. Its logic can be very complex if you make use of UC4's script elements.
See: User Guide - Job and Job - Execution
In UC4, you can start Jobs either manually or via control mechanisms such as Workflows or Schedules.
The UC4 Automation Engine then generates an executable Job and sends it to the MPE Agent via a
FileTransfer.
See: Inside UC4 Guide - Executing Objects
In z/OS, the Job is read and put to the Internal Reader. The Internal Reader starts the Job. Monitoring
takes place through SSL.
The Job notifies the Agent about the beginning and end of an execution. The Agent then passes this
information on to the UC4 Automation Engine.
The Agent monitors the Job's status in regular intervals. This ensures that an abnormal end can be
determined if a Job vanishes ABEND or CANCEL). The Job's return code is available in UC4.
The Job report (MSGCLASS) which includes the JES statistics and the complete job output is stored in a
file that is specified by the UC4 Automation Engine. If specified in the Job, the Agent transfers the report to
the UC4 Automation Engine which stores it in the UC4 Database. Because JES requests the Job output,
you must use a MSGCLASS with the status HOLD.
Executing FileTransfers
In UC4, FileTransfers are defined and maintained in the form of objects that include various tabs. They are
executed with the character conversions that are defined in these tabs (such as IBM_3270_
INTERNATIONAL).
See: User Guide - FileTransfer
See: Knowledge Base UC4 and z/OS - Agent - FileTransfer Support
Automation Engine
357
Event Handling
In UC4, Events are defined and maintained in the form of objects that include various tabs.
The z/OS Agent also supports Events of type FileSystem and Console.
See: User Guide - Event
CallAPI
You can use the CallAPI with a utility that can be called by using a Job.
See: User Guide - CallAPI for z/OS
6.17.2 z/OS Agent - FileTransfer Support
The z/OS Agent supports all file transfer functions such as the transfers of text and binary files or file
transfers with wildcard characters. The z/OS Agent can extend sequential files (PS, but not the members
of a library.
While defining a FileTransfer object, you can define additional file attributes for the FileTransfer's
destination in the FileTransfer tab. This definition overrides the system's default allocation. You can assume the attributes of the source files if the source and destination platform comply with each
other. Use the option "Keep original file attributes" in the FileTransfer object for this purpose. Note that in
z/OS, you cannot override these attributes. With this option being activated, an error will occur if you
define additional attributes.
The following two formats can be used to specify file attributes in FileTransfers that use z/OS as the
destination platform.
Language Environment Format
The "Language Environment Format" is the usual format. The file attributes for FileTransfers of older UC4
versions have already been specified in this format. Several file attributes are separated by commas,
values are assigned using the character '='.
You can specify the following file attributes:
l
l
l
l
l
recfm= (all 27 record formats of OS/390 plus * and A are valid)
lrecl= (0, any positive number up to 32,760 and X for each Reclen)
blksize= (0, any positive number up to 32,760)
space= ([CYL,TRK],(prim,sec,directory))
nl= (crlf (default setting in the Windows Agent) -> records are separated by <cr><lf> (=0d0a);
lf (default setting in the Unix Agent) -> records are spearated by <nl> (=0a);
none (no line separator is inserted between records).
Examples
recfm=fb,lrecl=1024,blksize=2048,space=(CYL,(1,1,0))
recfm=fb,lrecl=80
358
Chapter 6 Evaluating the Application Return Code of SAP Steps
Allocate Format
Starting with version 9.00A, you can set the attributes for FileTransfer files using the ALLOCATE
command. Several attributes are separated by using blanks and the values are written in parentheses
directly after the attribute name. The '=' character is not required.
This spelling can only be used with the new FileTransfer protocol (source and destination Agent are of
version 9.00A or later).
The following attributes are supported:
l
l
l
l
l
l
l
l
l
l
l
l
l
l
DATACLAS
EXPDT
MGMTCLASS
RETPD
RLSE
STORCLAS
UNIT
VOLUME
RECFM
LRECL
BLKSIZE
SPACE (only in combination with CYLINDERS, TRACKS or BLOCK)
DSORG
ROUND
For a detailed description refer to the IBM documentation of the TSO command ALLOCATE.
Example
ALLOCATE RECFM(FB) LRECL(1024) BLKSIZE(2048) EXPDT(2010100) SPACE(1,1) CYLS
DIR(10) UNIT(3390) VOLUME(DSK30D,DSK30E)
6.17.3 Message Classes
The job log of a z/OS job is stored in a JES spool which is divided into message classes. Each of these
classes has a single figure description consisting of the characters A to Z or the letters 0 to 9. You can
decide how the job log is structured and in which message classes it should be routed.
The Agent can:
l
l
l
l
l
Write the job output to the message class specified in the Job object
Include the JES statistics (JESMSGLG, JESJCL and JESYSMSG) in the job log in addition to the
job output
Read message classes and include them in the job log
Route the job log to message classes
Release the job log for printing and delete it
The relevant settings can be defined as a default setting in the Agent's INI file or in the Job object. Jobobject specifications overrule the INI-file values. All settings can also be defined in the script via job
attributes. UC4 recommends specifying the configuration that is used most in the INI file and jobs
differing from this specification directly in the object or via script.
The following table contains all possible specifications for message classes. The entries of the column
Job object correspond to the fields in the interface of the z/OS tab.
Automation Engine
359
Job log
handling
Job object
INI-file
parameter
Job attribute
Complexity
With additional output
completeJobout= MVS_
COMPLETEJOBOUT
Job output
Msg Class
Not available
MVS_MSGCLASS
Identification
Obtain the following message
class/classes
getMsgClass=
MVS_
GETMSGCLASSES
Redirection
Route message class/classes to
routeMsgClass=
MVS_
ROUTEMSGCLASS
Release for
printing
Release
relMsgClass=
MVS_RELMSGCLASS
Deletion in JES
spool
Purge
jobPurge=
MVS_JOBPURGE
It is possible to enter a message class on step level within a job in order to route particular messages
and filter them.
Using an Output Management System
Some parameters must be specified if using an Output Management System such as BETA92:
1. Enter the message class in which the job output is stored.
2. It is important that this message class is read (perhaps other ones as well).
3. Define the message class which is assigned to the Output Management System and route the job
log to it.
In some Output Management Systems, the Msgclass must be a write class - otherwise, it
cannot be processed. Also, an external writer should not be connected to this class as the output
would be processed from this writer.
4. The job log must not be deleted in the JES spool.
Use an extra message class for UC4.
How the job-log routing is specified directly in the job is shown in the following illustration. The job writes
its output in message class "B". This message class and class "A" are read. The order is significant when
message classes are routed. Message class "A" is routed to "K" and "B" to class "J".
360
Chapter 6 Evaluating the Application Return Code of SAP Steps
See also:
z/OS - Job
z/OS - Attributes
6.17.4 Event Monitor
UC4 handles Events in the form of objects which include several tabs. z/OS Agent Events of type
"Console" facilitate the monitoring of Console outputs. The Event is immediately triggered if all conditions
specified in the Console tab are met.
This requires the Event Monitor UCXEM25 to be installed and started. Type "FileSystem" checks via SMF
whether the condition is met and, if so, the Event is immediately triggered.
Event Monitor as independent task (Started Task)
The Event Monitor can also be operated in the form of a Started Task. In this case, an extra INI file is
required and the parameter start= in the Agent's INI file must be commented. Start the Event Monitor as a
Started Task and it tries to establish a TCP/IP connection to the Agent. The Event Monitor only connects
to the Console of its own LPAR. It loads the SMF Exit to use the SMF-based functions. If it is not possible
to establish a connection to the Agent, or if the connection is lost during operation, an attempt to
reestablish the connection is made in the specified interval (parameter connect= in the section TCP/IP in
the INI file).
Automation Engine
361
The Console command "MODIFY ..., EX=<addr>,:<port> facilitates that a reconnection can quickly be
established. In this case, the attempt to reconnect to the specified Agent is made immediately. A
connection is also established if the Event Monitor has an existing connection to another Agent. A new
connection is established in this case. The old connection is ended if the new connection is
successfully established.
The Event Monitor supports logging and trace functions. If the trace buttons are dynamically modified at
runtime, these modifications are sent to the Event Monitor. The Event Monitor's logging is not written to
the UC4 database.
Each Event Monitor requires two files:
VSAM file
This file serves as Event memory; the filtered Events are stored. Only after the Server has acknowledged
that the Event has been processed does the Event Monitor delete it from this file. This ensures that the
Event Monitor does not lose Events and that they are kept even if the Event Monitor had been ended and
restarted.
Sequential file
This file contains filter definitions - the Event Monitor memorizes the filter which it has received from the
Server. The whole file is rewritten if something is changed in the filter definitions. If the Event Monitor is
restarted, it uses these filters (even without the Agent). The Event Monitor can obtain additional filters or
existing ones can be deactivated as soon as the connection to the Agent has been established.
The Event Monitor can be ended via the Console command "STOP" or "MODIFY END". "MODIFY
SHUTDOWN" is available in the Agent. In this case, the Agent ends all Event Monitors that are
connected to the Agent via TCP/IP and then the Agent ends itself.
Ending the Event Monitor Use the following commands to end the Event Monitor and/or the SMF Exit manually:
Command
Description
MODIFY Name of the Event
Monitor,END
Ends the Event Monitor, the SMF Exit remains active
STOP Name of the Event
Monitor
MODIFY Name of the Event
Monitor,SHUTDOWN
Ends the Event Monitor and the SMF Exit
MODIFY Name of the
Agent,SHUTDOWN
Ends all Event Monitors including SMF Exits which are connected to
the Agent. The Agent then ends itself.
The SMF Exit always remains active when an Event Monitor is canceled.
SMF Exit
An Event Monitor forwards Events to the UC4 Automation Engine only when it is active. The SMF Exit
stores them if the Event Monitor ends or aborts in order to ensure that no Event is lost.
See file:
362
Chapter 6 Evaluating the Application Return Code of SAP Steps
GET_CONSOLE, GET_EVENT_INFO
Reads message data of an occurred Console or File System
Event
Event
INI File of the z/OS Agent (Event Monitor as Sub-Task)
INI File for the Independent Event Monitor
Agent - Combining UC4 and z/OS
Installing the Agent for z/OS
6.17.5 External Job Monitor
The external Job Monitor (EJM) can be used to identify jobs that were started by a scheduling system
other than UC4 (e.g., OPC, CA7). You can react to these jobs in the UC4 system using the Event Monitor
and the UC4 Agent.
The external Job Monitor runs as an independent Started Task.
Function of the external Job Monitor (EJM)
A reaction to external Events is possible through the Event Monitor.
The Event Monitor identifies Console Events, automatic FileSystem Events and the end of z/OS jobs. The
Event Monitor can also be used to react to the generation of external files. As soon as the external Job
Monitor identifies an external Job end, it creates a file, thereby enabling a reaction through the Event
Monitor. The Event Monitor communicates with the UC4 system via the Agent and triggers an Event
object.
Not every job end requires an action. You can use a filter file to determine the jobs or steps that require a
reaction. If the end of an affected job has been identified, the EJM creates a temporary file. This file is only
required for the generation of an SMF record to which the Event Monitor can react. It can be deleted
afterwards.
Note that the creation and deletion of files leads to entries in the dataset catalog. Make sure to
reorganize it regularly.
Automation Engine
363
It is possible to identify external jobs within a Sysplex if an external Job Monitor and an Event Monitor
instance run on each LPAR (local partition). Each LPAR has its own SMF subsystem which is not
sysplex-able. The Agent does not require SMF and can be used sysplex-wide. There is no direct
connection between EJM and EM. The EJM signals to the EM that a Job has ended by generating a file.
The EM sends the data to the z/OS Agent across LPARs.
364
Chapter 6 Evaluating the Application Return Code of SAP Steps
SMF Exit
Events and information concerning the external Job Monitor should be written to the CADS via an SMF
Exit (same procedure as in EventMonitor). Doing so requires a new SMF Exit (UC4EXJM). This Exit
behaves similarly to the Event Monitor SMF Exit with the exception that it only collects type 30 records.
The SMF Exit module will automatically be loaded when the external Job Monitor module starts. The SMF
Exit continues collecting Events even if the EJM has been ended. A message is written to the log file if a
Job that has been specified in the filter file finishes in the meantime.
You can use the existing program CADSDEL as emergency recovery for the EJM.
Problems can occur if you use a filter file of the same content in several LPARs. For example, Jobs of
the same name can end on different LPARs at the same time. In this case, the system attempts to
generate files of the same name in parallel which eventually leads to an error. As this error hardly ever
occurs, the utility only writes an error message to the log file and continues.
Filter file
The EJM filter file is necessary to select the relevant ending Jobs. The individual filter criteria are
immediately checked whenever an event occurs.
Example: A filter file contains a condition referring to a particular Step/ProcStep. The ending of this Step is
immediately identified and not only when the Job has ended. The filter file contains the following selection
criteria:
l
l
l
l
l
Job name (partially/fully qualified)
Step name (partially/fully qualified)
ProcStep name (partially/fully qualified)
Job end
Return code
Automation Engine
365
The filter file must include the DCB attributes RECFM (record format)=FB, LRECL (record length) =85 and
BLKSIZE (block size) =5120. The filter file includes an 85-character line for each filter.
Use the following command to reload the filter file manually:
MODIFY <Name of the STC>, RELOAD
(STC = Started Task)
Filter criterion
Digits
Description
Job name
1-8 (Length 8)
Filter for the Job's name in z/OS.
The wildcard characters "*" and "?" are
allowed.
Step name
9-16 (Length 8)
Optional
Filter for the Job's Step name in z/OS.
The wildcard characters "*" and "?" are
allowed.
ProcStep name
17-24 (Length 8)
Optional
Filter for the Job's Procedure Step name in
z/OS.
The wildcard characters "*" and "?" are
allowed.
Job end
25 (Length 1)
" " -> Check immediately at Step/ProcStep
end.
"X" -> Check at Job end. No RC verification.
"N" -> Check at Job end and when the Job
ends normally (i.e. with a return code
between 0 and 4095).
"A" -> Check at Job end and when the Job
ends abnormally (i.e. with a return code
between 4096 and 12287).
Job return code
26-41 (Length 16)
Optional
Filter for the Job's return code (condition
codes, user abends and system abends).
Several return codes can also be specified;
separate them with the character ";" or ",".
Ranges can be defined using the character "".
File name
42-85 (Length 44)
File name of the temporary file to be
generated for redirection.
The example shown below illustrates the usage of a Job filter dataset:
JOBTEST STEP3* 0-100;S0C4 JOB.ZUC800A1.EJM.TRIGGER.TEMP01
JOBF* STEP01 N0,4,8,12-16 JOBF.ZUC800A1.EJM.TRIGGER.TEMP02
JOBTEST2DUMMY 0-4096 JOB.ZUC800A1.EJM.TRIGGER.TEMP03
JOBTEST2DUMMY2 N0-4096 JOB.ZUC800A1.EJM.TRIGGER.TEMP04
The individual filter lines are connected through an OR relation. Thus, the lines are processed and checked
in sequences. If a selection applies, the particular file will be created.
See also:
366
Chapter 6 Evaluating the Application Return Code of SAP Steps
Event Monitor
Structure of the External Job Monitor's Configuration File
6.17.6 SMF Exit
The SMF subsystem collects and logs information about the system and its jobs.
The z/OS Agent and its Event Monitors use SMF records in the following areas:
l
l
Automatic File-System Events
l
Support of Generation Data Groups
Recognizing and Assessing Job Ends
A requirement for SMF usage is that your z/OS system accepts the relevant system exits and that the
SMF module logs particular entries. The INI files of the Agent and Event Monitors contain some settings
for SMF. Detailed information about the exact configuration is provided in the documentation about the
above functionalities.
General
The Event Monitor monitors Console and FileSystem Events and forwards them to the UC4 Automation
Engine. You can react to them via Event objects. Events are only monitored when the Event Monitor is
active. Events are collected on the basis of SMF records via an SMF exit. This Exit is able to buffer
Events even if the Event Monitor is not available and transmits the collected Events to the Event Monitor
after a restart. No SMF records are lost unless the buffer is full (its size is definable).
The System Management Facility (SMF) is also used in other fields. It recognizes job ends and GDGs,
for example.
The following illustration shows the interaction of Agent, Event Monitor and SMF Exit.
Automation Engine
367
The SMF Exit stores Events in an Area Data Space (CADS). The z/OS Console shows the CADS filling
level colored:
l
l
25%, 50% and 75% in white
80%, 85%, 90%, 95% and 100% in red
The SMF Exit cannot store Events if the CADS is full. The oldest Event entry is not overwritten.
Events are stored in the CADS again as soon as memory has become available. This is the case when
the SMF Exit transmits Events to the Event Monitor.
The default value for the CADS is 10 MB which is sufficient for storing about 65000 Events.
Events occurring during a startup, shutdown or IPL stage are not collected. Events are processed as
soon as the Event Monitor has started.
Configuration
Start the SMF Exit as shown below:
l
l
Make sure in your z/OS system that the SMF subsystem logs all SMF records of type 14, 15, 30
and 64 and that the exits IEFU83 and IEFU84 are active.
The SMF Exit can run as a subtask of the Agent or Event Monitor which requires their INI files to be
adjusted as shown below:
Enter a description for the SMF Exit in the section (CONSOLE), parameter ModulName=.
Define the CADS size in the section (CONSOLE), parameter SMF_Buffersize=. The default size is
10 MB.
l
Start the Event Monitor.
368
Chapter 6 Evaluating the Application Return Code of SAP Steps
Starting the Event Monitor
Use the following command to start the Event Monitor including the SMF Exit:
START Name of the Event Monitor
Ending the Event Monitor
Use the following commands to end the Event Monitor and/or the SMF Exit manually:
Command
Description
MODIFY Name of the Event
Monitor,END
Ends the Event Monitor, the SMF Exit remains active
STOP Name of the Event
Monitor
MODIFY Name of the Event
Monitor,SHUTDOWN
Ends the Event Monitor and the SMF Exit
MODIFY Name of the
Agent,SHUTDOWN
Ends all Event Monitors including SMF Exits which are connected to
the Agent. The Agent then ends itself.
The SMF Exit always remains active when an Event Monitor is canceled.
Warm start
The SMF Exit remains active when the Event Monitor is ended manually ("END") or aborts. As soon as the
Event Monitor has been restarted, it connects to the SMF exit again and processes the Events which have
accumulated meanwhile.
INI-file modifications in the parameters ModulName= and SMF_Buffersize= have no effect. Values are
only read when the SMF Exit is started again.
Exceptions
Usually, the SMF Exit ends when the Event Monitor is ended with "SHUTDOWN". The CADS is
automatically deleted. Manually ending the SMF Exit is also possible:
SET PROG,EXIT,DELETE,EXITNAME=Name of the SMF Exit,MODULNAME=Name of the UC4
module
The CADS is not deleted if the SMF Exit is ended manually.
Use the utility CADSDEL to delete the CADS content:
Open the Event Monitor's log file. The following log line contains the parameters STOKEN and
TCBTOKEN which are required for ending the SMF Exit:
-UC4 STOKEN=8000160200001328;TCBTOKEN=00000004000000010000000000FD2300
The UC4 system name and an eyecatcher name must also be specified. Both values are defined in the
Event Monitor's INI file:
l
l
system= contains the name of the UC4 system
CADSEyeCatcher= contains the eyecatcher name
Automation Engine
369
Call the utility CADSDEL using the above four parameters:
//CADSDEL JOB ####,PROGRAMMER,NOTIFY=&SYSUID,MSGLEVEL=(1,1)
//CADSDEL EXEC PGM=CADSDEL,
// PARM='8000160200001328 00000004000000010000000000FD2300 UC4PROD
UC4EYEC'
//STEPLIB DD DISP=SHR,DSN=<UC4.LOADLIB>
Verify that the CADS has been deleted with the z/OS command D A,*MASTER*.
Scenario
There are two LPARs in Sysplex:
l
l
The first one includes an Agent and an Event Monitor. Both run as independent tasks. The SMF
Exit is a subtask of the Event Monitor.
The second one also includes an Event Monitor with an SMF Exit running as a subtask.
LPAR1
LPAR2
Agent: MVS01
Event Monitor: EM01
SMF Exit: SMFE01
Event Monitor: EM01
SMF Exit: SMFE01
The following configurations are required in LPAR1:
l
Install an Agent in LPAR1 as described in the Installation Guide. The complete section
(CONSOLE) in the Agent's INI file must be commented out because the Event Monitor should run
with the SMF Exit as an independent Started Task.
;(CONSOLE)
;start=
;buffersize=
;smfwrite=
;ModulName=
;smfStepFilter=
;smfJob=
;SMF_Buffersize=
;ABENDNUM=
l
Install the Event Monitor as an independent Started Task in LPAR1. The corresponding description
is also found in the Installation Guide. The section (CONSOLE) in the Event Monitor's INI file must
be adjusted because the SMF Exit is a subtask of the Event Monitor:
(CONSOLE)
smfwrite=1
ModulName=SMFE01
smfStepFilter=0
SMFJob=0
SMF_Buffersize=10
The following configurations are required in LPAR2:
l
Install the Event Monitor as an independent Started Task in LPAR2. Adjust the section
(CONSOLE) in the Event Monitor's INI file because the SMF Exit is also a subtask of the Event
Monitor:
(CONSOLE)
smfwrite=1
370
Chapter 6 Evaluating the Application Return Code of SAP Steps
ModulName=SMFE01
smfStepFilter=0
SMFJob=0
SMF_Buffersize=10
See also:
Event Monitor
6.17.7 Automatic File-System Events
The z/OS Agent supports the monitoring of file systems and file closings. The Event is triggered when a
file is closed according to the defined conditions.
In an Event object, you can either filter by the file name or specify a series of filter criteria. The latter
include the name of the file, the job which has processed the file and its return code.
!Process is processed when the Event has been triggered. The script function GET_EVENT_INFO
supplies information about the file.
The UC4 administrator must set the parameter smfwrite=1 in the INI file of the Agent or Event Monitor.
Make sure in your z/OS system that the SMF subsystem allows the system exits IEFU83 and
IEFU84. The entries 14, 15, 30 and 64 must be logged.
Automatic FileSystem Events on PDS members are not supported.
Procedure 1. Create an Event object of type File System.
2. Open it and switch to the File System tab.
3. Select a z/OS Agent.
Automation Engine
371
4. The section Timer control now shows the additional menu item "Automatically". Select it.
File name as filter
1. Enter a file name in the field Path. Use wildcard characters if you intend to monitor several files or
specify the exact name if a particular file should be monitored.
2. The option Startup Event serves to check the file's existence when the Event object is activated.
An Event is triggered if the file exists.
3. Enter the script statements to be executed when the Event is triggered in the !Process tab. Use the
script function GET_EVENT_INFO.
4. Store the Event object and start it at the time when the file should be monitored.
Several filter criteria
1. Create a file containing the filter criteria on the LPAR on which the Agent runs. This file must have a
particular format which is described in the table below.
2. Specify the filter-file name in the field Path. Use the following format: *file(DSNAME)
Example: *file(SGD.PROD.MASSFILTER)
Wildcard characters are not allowed in DSNAME.
3. Enter the script statements to be executed when the Event is triggered in the !Process tab. Use the
script function GET_EVENT_INFO.
Note that "Process" is not processed if the filter file contains the specification of an object that
should be started.
4. Store the Event object and start it at the time when the file should monitored.
Filter criteria
The Event Monitor is able to consider several filter criteria upon the notification of a file closing. In this
case, the Event is only triggered if a particular job has used the file or if a specific return code occurs.
372
Chapter 6 Evaluating the Application Return Code of SAP Steps
Filter criteria are stored in a separate file which contains one filter definition per line. If several filter
definitions apply in an Event (e.g. because they overlap), an Event is triggered per applicable line.
The filter file must have the DCB attributes RECFM=FB, LRECL=512 and BLKSIZE=5120.
Each filter-file line is limited to 307 characters. The following areas are available:
Filter
Digits Description
criteria
File
name
1 to
81
Filters for the file name
Job
name
82 to
89
Filters for the name of the z/OS job which has closed the file
Job
end
90
Waits for the job end
DS names including PDS members and GDGs are supported. Wildcard characters
can be used.
The wildcard characters "*" and "?" are allowed.
Allowed values: " ", "X", "N" or "A"
" " - File closing immediately triggers the Event. The job end is not waited for.
"X" - File closing only triggers the Event when the job ends. The return code is
irrelevant.
"N" - The Event is triggered when the job ends normally (return code 0-4095).
"A" - The Event is triggered when the job ends abnormally (return code 4096-12287).
Use the filter criterion "Job return code" to define the expected return codes.
When analyzing the job end, the Agent either refers to the job end's SMF records
or it also considers the records of the STEP ends. Normal and abnormal job ends
can be distinguished if only the job end's SMF records are considered. The
analysis is more detailed if STEP ends are also considered. In this case, the
Event Monitor retrieves the maximum value.
The UC4 administrator can determine whether only the job end or also STEP ends
should be considered when checking the return code. Specifications are made in
the Event Monitor's INI file using the parameter smfStepFilter=.
Job
return
code
91 to
106
Filters for the job's return code (Condition Codes, User Abends and System Abends)
Values can be specified as in z/OS or using the UC4-specific syntax.
If you intend to specify several return codes, separate them with ";" or ",". Areas are
defined using "-".
Action
107
Action which should follow the Event
Allowed values: "Y" and "N" (default value)
"Y" - The object specified in the following area is processed instead of !Process.
"N" - The object (if specified) is not processed.
Object
108 to
307
Name of the object to be processed
You can store a Job object here.
Note that the content of !Process is NOT processed. Instead, the object specified
here is activated.
For lack of space the following example does not show all 307 characters and the full number of digits:
DEV.DS1
DEV.DS1
JOBA
JOBB
A
A
S806
Y
CALL.ADMIN
Automation Engine
UC4.D*.*LIB
SYS1.PARMLIB
TEST.S62*.T*
TEST2
N
0-12;16-18
TEST1
X
11-17;S806
Y
373
MM.CLOSING
When the Event object starts, the Agent reads the filter file and automatically notifies the Event Monitors.
Changing filter criteria requires the affected Event object to be restarted or the filter file to be reloaded using
the statement MODIFY.
Syntax:
MODIFY Name of the Agent-STC,FEVNT=Name of the filter file
Example:
MODIFY UC600T1,FEVNT=UC600T.FILTER1
Optionally, you can define an object which should be activated in reaction to the occurred Event. In this
case, the Agent stores all information in the input buffer which can be read in the Event object with the
script function GET_EVENT_INFO using keywords. Thus, the activated object can retrieve data using the
script statement :READ. Use the keywords as variable names.
Example:
:SET &FILENAME# = GET_EVENT_INFO (FILENAME)
:READ &FILENAME#,,
See also:
GET_EVENT_INFO
Event Monitor
6.17.8 GDG Support
The UC4 Automation Platform also supports Generation Data Groups (GDG). This type of file
management can be used in FileSystem Event objects and the script element GET_EVENT_INFO.
FileSystem Event
A standard function of this object type is to check file-system values. It is also possible to trigger an Event
if a GDG generation is closed. Enter an z/OS host in the File System Event tab and select the option
Automatically in the timer control of the Event tab in order to use this function.
The closing of a new generation is waited for if GDG(+1) has been specified, which is normally the
case. If you specify GDG with +/-0 (+0, +00, +000, -0, -00, -000), the closing of the current generation
is waited for.
Example:
PAYROLL
Name of the GDG
DSNAME=PAYROLL(0) This week's generation data set
DSNAME=PAYROLL(-1) Last week's generation data set
DSNAME=PAYROLL(-2) Generation data set of two weeks ago
Script element GET_EVENT_INFO
This script function retrieves the name of a generation which can then be processed.
Extract of an example:
374
Chapter 6 Evaluating the Application Return Code of SAP Steps
:SET &FILENAME# = GET_EVENT_INFO (FILENAME)
:SET &HND# = PREP_PROCESS_FILE ("MVSHOST", &FILENAME#)
Configuration
Some specifications are required in order to use GDG in your UC4 system:
l
Activate the parameter smfwrite= in the INI file of the z/OS Agent.
(CONSOLE)
start=UCXEM25
smfwrite=1
l
l
Activate the exit modules IEFU83 and IEFU84.
The entries 14, 15, 30 and 64 must be logged.
See also:
FileSystem Event
GET_EVENT_INFO
6.17.9 Recognizing and Assessing Job Ends
The Agent can also use SMF records in order to recognize job or STEP ends.
Activate this function in the INI file of the Agents or the Event Monitor if it runs as an independent Started
Task:
(CONSOLE)
SMFJob=1
By default, the job messenger is used to recognize job ends. Thus, the Agent variable UC_EX_JOB_MD
must be adjusted in the Agent's INI-file section (Variables). Replace the component "UCXJM25M " by
"UC4START" and restart the Agent.
(VARIABLES)
UC_EX_JOB_MD=UC4START
The advantage of using this function is that jobs can be assessed on the basis of the return codes the
job steps supply. You can specify in the Job object whether the highest return code or the last one to
occur is considered for the job end.
Make sure in your z/OS system that the SMF module logs the entries 30.
Each LPAR must run an EM if the jobs are distributed in the SYSPLEX with WLM, as otherwise
recognition does not work.
Note that changing between the two job messenger types TCP/IP and SMF does not affect active or
generated jobs. Do not change the job messenger if jobs are active or have been generated. Otherwise,
these jobs obtain the end status ENDED_VANISHED. Despite this end status, these Jobs ended
successfully; it is only the end message which could not be sent to the Agent. Thus, all of a system's
Jobs should have ended before the Job messenger type is changed.
See also:
Automation Engine
375
Event Monitor
6.17.10 Return Codes of z/OS Jobs
The Agent logs all errors in the Job's activation report and sets a return code depending on the job
execution. The value as of which the Job should be canceled can be defined in the Job object's Runtime
tab.
You can also define value ranges for the steps instead of individual return codes. The Agent compares
the result of a step execution with the defined step list.
z/OS distinguishes three types of return codes: Condition Code, User Abend and System Abend. The
Agent uses number ranges each of 4 KB in order to assign the return codes.
Type of return code
z/OS
UC4
Condition Code
0 to 4095
0000 - 0FFF (0 to 4095)
User Abend
U0000 to U4095
1000 - 1FFF (4096 to 8191)
System Abend
S000 to SFFF
2000 - 2FFF (8192 to 12287)
The return code of a Job object must be specified as a decimal number. Thus, User and System
Abends must be converted to decimal numbers.
Example:
Return code SB37 indicates a full volume while a file is being written. The corresponding decimal number
is 11063.
See also:
Runtime tab
6.17.11 JCL Exit
JCL Exits are available when processing z/OS Jobs. These Exits are supplied in the form of a module
which can be used to modify the generated Job before it is processed.
Create a z/OS Job in UC4 as usual. Its start causes the generated Job to be sent to the Agent which
completes it and executes the Job in the target system. When using the JCL Exit, the Agent calls the
specified module before executing the Job. In doing so, the JCL in z/OS can be changed subsequently.
You can add, change or evaluate JCL lines, thereby preventing the start of particular programs, for
example.
The supplied CD contains a folder for z/OS Agents. It includes a sample module in the file uc4jcle.asm
which inserts comment lines. It also contains a description about how the module is used.
The JCL Exit module can be individually activated for each z/OS Agent. The module is loaded when
the Agent is started.
376
Chapter 6 Evaluating the Application Return Code of SAP Steps
Configuration
l
Enter the name of your JCL Exit module in the z/OS Agent's INI file and specify the size of the
output range.
(JCL Exit)
name=Module name
maxJclRecords=1000
l
l
Copy this module either to the UC4 Load library or add the STEPLIB definition for the Agent to the
library with the JCL Exit.
Now start the Agent (this includes the loading of the module).
See also:
INI file
6.17.12 Include MVS.JOBMD_DEFINITIONS
In order to enable the Job messenger to establish a TCP/IP connection, the appropriate DD statements
need to be included in the include object. Otherwise, Jobs would switch over to the status ENDED_
VANISHED.
The Include object MVS.JOBMD_DEFINITIONS does not have to be adjusted unless the MVS or
Language Environment Resolver work incorrectly.
This situation can be avoided by creating an Include object with the name MVS.JOBMD_DEFINITIONS in
the system client 0000. In it, you can enter the particular DD statements. The whole statements are found
in the started task of the TCP/IP.
Example:
//SYSTCPD DD DSN=TCPIP.SYSTSMS.TCPPARMS(DT20OEDA),DISP=SHR
//PROFILE DD DSN=TCPIP.SYSTSMS.TCPPARMS(DT20VIPA),DISP=SHR
The Include is called in the Header upon the execution of a Job. The Header is an object called
HEADER.MVS which, by default, is supplied in the system client 0000.
:INC MVS.JOBMD_DEFINITIONS ,nofound=ignore
Automation Engine
7 Terminology - Computer, Programs
and Files
7.1 Naming Conventions
[Name Conventions] [Program and File Overview]
7.1.1 General
In this documentation, universal typographical conventions apply to all files and folder names.
File names can be entered in lowercase letters because in Windows file names are case-insensitive.
7.1.2 Syntax in General
Short file names (8.3) are used on the installation CD in order to avoid problems.
They are structured as shown below:
UCZKxxxx
Z = Purpose
K = UC4 components
xxxx = individual definition
Purpose
Description
D
UserInterface
S
Server Routine (DLL)
X
Agent
Y
Utility (service program)
7.1.3 UC4 Server Syntax
UCSRVTP
UCSRV stands forUC4 Server (UC4 Automation Engine)
T = Type - "c" for the communication process, "w" for the work process
P = Process
7.1.4 Agent Syntax
An extended syntax applies for Agents:
UCXJSSVA
SSV = System ID and Version
A = Task (only for messenger program and CallAPI)
377
378
Chapter 7 Terminology - Computer, Programs and Files
System ID and Version
Hardware, Operating System, Version
B2.
BS2000
B24
SNI, BS2000 Sockets version 1.3
B25
SNI, BS2000 Sockets version 2.1 *
B26
SNI, BS2000 Sockets version 2.3 *
*) UC4 recommends using the Agent with the latest socket version.
MP.
MPE
MP6
HP 3000, MPE Version 6.5 or later
N..
NSK
NS1
Tandem Guardian NSK Version D40 or later
NI6
Computers with Itanium processors
OAX
Oracle Applications
M..
z/OS
M25
IBM, z/OS Version V2R5 or later
O..
OS/400
O41
IBM, OS/400 Version V4R1M0 or later
PSX
PeopleSoft
R3X
SAP
SLX
Siebel
D..
UNIX - DEC OSF
DA4
Alpha - DEC-OSF/1 - Digital UNIX - Tru64 UNIX
H..
UNIX - HP-UX
HP1
HP Workstation (9000), HP-UX
HI6
rx2600 computer with Itanium, HP-UX
A..
UNIX - IBM AIX
A64
Power PC64, AIX
AP6
Power PC, AIX
L..
UNIX - Linux
LI3
Intel, Linux
LI6
Itanium, Linux
LX6
Linux (x64)
LZ3
zSeries, zLinux
LZ6
zSeries, zLinux 64bit
C..
UNIX - SCO
CI5
Intel, SCO-UNIX ODT
CI7
Intel, SCO Unixware
U..
UNIX - Sun OS (Solaris)
U64
Sparc64, Solaris
Automation Engine
US8
Sparc, Solaris
UI8
Intel, Solaris
SI6
Intel 64 bit (x64), Solaris
V..
VMS
VA7
Alpha, OpenVMS-Alpha
VI8
OpenVMS (IA64)
VV7
VAX, VAX/VMS
W..
Windows
WI3
32 Bit plattforms (x86)
WI6
64 Bit platforms (IA64)
WX6
64 Bit platforms (x64)
Task
Purpose
M
Message program
C
CallAPI
7.2 Program and File Overview
[Naming Conventions] [Program and File Overview]
7.2.1 Programs
Program
Purpose
ucsrvcp
UC4 Automation Engine for UNIX, communication process
ucsrvwp
UC4 Automation Engine for UNIX, work process
ucsrvcp.exe
UC4 Automation Engine for Windows, communication process
ucsrvwp.exe
UC4 Automation Engine for Windows, work process
UCDJ.EXE
Start program for UserInterface
UCDJ.JAR
UserInterface
UCX...
Agent programs
UCYBARBR.EXE
Utility for searching the archive files
UCYBCHNG.EXE
Utility for modifying exported data
UCYBDBCC.JAR
Utility for copying and deleting clients
UCYBDBAR.JAR
Utility for archiving the database
UCYBDBLD.JAR
Utility for loading the database
UCYBDBRE.JAR
Utility or reorganizing the database
UCYBDBUN.JAR
Utility for unloading the database
379
380
Chapter 7 Terminology - Computer, Programs and Files
UCYBDBRR.EXE
Utility for creating revision reports (object audits)
UCYBCRYP.EXE
Utility for encoding passwords
UCYBSMGR.EXE
Service Manager - Service
UCYBSMDI.EXE
Service Manager - Dialog Program
UCYBSMCL.EXE
Service Manager - Command Line Program
UCS...DLL
Server routines
7.2.2 Files
File
Purpose
UC.MSL
Message library
UCX.MSL
Message library for Agents outside Windows
UC_INI.TXT
Initial database contents for DB.Load
UC_DEF.TXT
Default database contents for NEW installation
UC_DDL.SQL
DDL for DB structure
CBLRTSS.DLL
Micro Focus Cobol runtime system (Version 4.0)
ZU*.DLL, UC*.DLL
UC4 function libraries
*.OCX
Visual Basic runtime system (Version 6.0)
TRANSPRT.TXT,
K*.*, R*.*, E*.TXT
Function modules for SAP Systems:
Overview of valid transport jobs, function modules and export protocol
UCYBABR.VBP,
BROWSE*.*, TOOBIG.*
Microsoft Visual Basic source code of the Archive Browser
*.JAR
Java function libraries
7.2.3 SAP Development Objects of the UC4 Interface
The UC4 Interface for SAP Basis Job scheduling has been developed in ABAP. It consists of the SAP
development objects that are listed in the following table:
R3X on SAP Basis Release
3.x
R3X on SAP Basis Releases 4.0x, 4.5x, 4.6x
and 6.10
Development
class
J2U0
/SBB/UC4
DDIC structures
J_2U*
/SBB/UC4*
Function group
J2U3
/SBB/UC4*
Function
modules
J_2U_30_*
/SBB/UC4*
7.2.4 Return Codes of Agents running on Windows
Agents that run on a Windows platform supply the following return codes:
Automation Engine
l
l
l
l
l
62 (FATAL_ERROR_SOCKETS) - Socket error
63 (FATAL_ERROR_NOINIFILE) - INI file not available
64 (FATAL_ERROR_NOMEMORY) - Memory allocation failed
65 (FATAL_ERROR_CONFIG) - Agent name or TCP/IP port number is not defined
66 - Log file could not be opened
381
382
Chapter
Automation Engine
383
Glossary
This glossary lists all UC4-specific technical terms in alphabetical order.
ABC D EFGH IJKLMN OPQR STU VW XYZ
A
l
l
l
l
l
l
activation
Through activation, tasks obtain a RunID, are displayed in the Activity Window, and are ready for
execution (see also 'Start').
activation log
A report that contains all details about task activation. The details that are included in the log
depend on the settings that have been specified (for example, the generated JCL, modified
Variables).
Activity Window
A UserInterface window that displays all activated tasks.
Agent
A program that enables the execution of processes on target systems such as computers or
business solutions. A particular UC4 object type.
alias
This refers to the name of Workflow tasks or objects that are activated once or recurring. This name
is used instead of the actual object name in the Activity Window, the monitors and the statistics.
AutoForecast
It displays tasks that will run in a predetermined period. Comprehensive forecast for all future
activities.
B
l
batch mode
This refers to the sequential background processing of tasks.
C
l
l
l
l
l
Calendar
It consists of days using Calendar keywords. A particular UC4 object type.
Calendar condition
The criteria for running a task is based on Calendar keywords.
Calendar keyword
A part of a Calendar object that is used to define days.
CallAPI
A programming interface that can either be called directly or from a different program. It processes a
script in the UC4 system.
Child, Children
These are objects that are activated by superordinate tasks (parents).
384
Chapter Glossary
l
l
l
l
l
client
This is a closed environment for the execution of tasks within a UC4 system. A particular UC4
object type.
Cockpit
It visualizes the values and states of UC4 or of the monitored and controlled system. A particular
UC4 object type.
CodeTable
It defines a complete set of characters. A particular UC4 object type.
communication process
A communication process is part of the UC4 Automation Engine. It is responsible for connecting
the UC4 components.
context menu
A menu that opens in a particular place when you right-click with the mouse.
D
l
l
l
l
data sequence
An internal listing of Console outputs or lines of Variable objects, etc. The lines of a data sequence
can be accessed by using a PROCESS loop or the script element GET_PROCESS_LINE. The
script elements PREP_PROCESS* generate data sequences.
dialog process
A part of the UC4 Automation Engine and a special form of work process. Is exclusively
responsible for UserInterface messages.
Documentation
This refers to the UC4 Guides. It is also a particular UC4 object type that can be used to store
information.
dynamic variables
A Variable object with the attributes "Source" - "SQL", "SQL internal", "Multi" or "Filelist". Values
are directly retrieved from the data source and not stored in the object.
E
l
l
l
l
l
l
.
E-mail connection
This is a functionality of Windows and UNIX Agents that is used to send e-mails.
Enterprise Control Center (ECC)
A separate UC4 product. Web application that allows access to the functions of various UC4
applications and products in a quick and easy way.
Available for download from the UC4 Download Center.
Event
Action that is triggered if particular conditions apply. A particular UC4 object type.
Event ID
First RunID of FileSystem and Console Events. Both Event types require communication between
UC4 Automation Engine and Agent. They communicate via the first RunID. Otherwise, Event
identification is no longer possible after the first log change.
Explorer
UserInterface window in which objects can be created, edited and administered.
external dependency
A task whose end status is considered when a Workflow is being processed. The task itself,
however, does not run within the framework of this Workflow.
Automation Engine
385
F
l
l
l
File transfer
Transfers files from one computer to another. A particular UC4 object type (FileTransfer object).
Forecast
Estimates a task's runtime on the basis of previous executions.
fully qualified FileTransfer
FileTransfers without wildcard characters. One particular file is transferred.
G
l
Group
Integrates tasks so that they can be processed together. A particular UC4 object type.
H
l
l
l
host
Computer, target system.
host attributes
Platform-independent attributes of the Job object.
HTML help
Microsoft help format for manuals. These help files have the ending .CHM (see also 'WebHelp').
I
l
Include
A script that is often used in several objects. A particular UC4 object type.
J
l
l
JCL
Short form of "Job Control Language". It refers to applications that are processing steps executed
on computers.
Job
Processing on a target system. A particular UC4 object type.
K
l
l
Key
Column in static Variable objects that can be used to access values of a particular line.
Keyword
Part of a Calendar or Variable object (Calendar keyword or key) or parameter of a script element
that is used to define values.
386
Chapter Glossary
L
l
l
Login
Login data for target systems. A particular UC4 object type.
logical date
The logical date is used as a comparison date for checking Calendar conditions.
M
l
l
Message Window
UserInterface window that displays warnings, information and error messages.
Monitor
Graphical view of a task's execution.
N
l
l
nonstop process
Part of the UC4 Automation Engine. Assumes processing if the computer with the active Server
processes fails.
Notification
Sends messages to individual Users and UserGroups of the UC4 system. A particular UC4 object
type.
O
l
l
l
l
object
UC4-controlled activities and processes are structured in the form of objects (see also 'Task').
object class
There are four classes of objects: executable, active, passive and system objects.
object type
An individual object is provided for the individual activities: User, UserGroup, Notification, Cockpit,
CodeTable, Documentation, Event, Agent, FileTransfer, Group, Include, Job, Workflow, Calendar,
Login, Client, RemoteTaskManager, Schedule, Script, Server, Sync, Variable and TimeZone.
object variables
Placeholder for values that are stored in an object's "Values" tab.
P
l
l
l
l
parent
There are different ways of activating objects. The originator of an activation is referred to as the
superordinate task (parent). (See also 'Child', 'Children')
partially qualified FileTransfer
FileTransfers that use wildcard characters in order to transfer several files.
Period Container
Controls the execution of periodical tasks
perspective
Separate functional area of the Enterprise Control Center's (ECC) web interface. The perspectives
Automation Engine
l
l
l
l
l
l
l
l
387
Process Automation and Process Monitoring provide functionalities of the UC4 Automation
Platform.
Process Automation
The old name of the Service Catalog perspective.
Process Assembly
A perspective of the Enterprise Control Centers. You use it to create, define and modify Workflows.
Process Monitoring
A perspective of the Enterprise Control Center. It lists the activities of all users and provides the
opportunity to manipulate them (you can cancel or deactivate them).
predefined variables
Fixed variables that can be used in the attributes or the script of executable objects. The values
refer to the object or the system.
primary work process
It is responsible for the execution of UC4-internal tasks and work processes.
PromptSet
A user-defined input mask for executable objects. A UC4 object type.
PromptSet element
Fields/control elements that are used to query User values. They are the content of a PromptSet
input mask.
PromptSet variable
It stores the value of a PromptSet element. Depending on the situation, a value can be user-defined
or a default value. PromptSet variables show the same behavior as object variables.
Q
l
Queue
A Queue determines the maximum number of concurrent tasks, their priorities and the order in
which tasks should be executed. A particular UC4 object type.
R
l
l
l
l
Rapid Automation (RA)
A generic technology that can include various solutions. Is composed of an RA Agent and an RA
Solution.
RA Agent
A UC4 Agent that can be connected to a particular RA Solution and thus provide this solution's
functionalities to a UC4 system. It is the interface between an external system / application /
platform and a UC4 system.
RA Solution
A solution that is based on the Rapid Automation Technology that allows UC4 to access an
external system / application / platform. The RA Solution is supplied as a JAR file that must be
loaded to the UC4 Database and connected with an RA Agent. The specific RA objects (such as
Jobs, Connections, Agent) are available in the UC4 system as soon as the solution has been
loaded.
real date
The date that is used for checking runtime monitoring or time conditions in the properties of
Workflow tasks is referred to as the real date. It complies with the top Workflow's activation time. It
is passed on to all subordinate tasks.
388
Chapter Glossary
l
l
l
l
l
l
l
l
l
recurring tasks
These tasks are scheduled without using a Schedule object and mostly consist of a period that is
less than a day.
registered
This is the status of a task that runs within a group and is waiting for its start.
RemoteTaskManager
It monitors and controls external Jobs that were not started by UC4. A particular UC4 object type.
report
A report provides more detailed information about a task's execution or a UC4 component.
Result column
The first column of dynamic Variable objects with the sources "SQL", "SQL-internal" and "Multi".
The content of this column can be defined with Result format.
restart
A restart refers to the repetition of an object's execution. This action differs from a new start in
some parts.
return code
The value that represents the result of tasks and script functions.
RunID
Short for "run number". It is a number that provides unique information about a task's execution.
The RunID can include 7 to 10 digits. It is assigned by the UC4 Server.
Runtime
The duration of a task's execution. It refers to the period between a task's start and end. It does not
include its activation period (see also: activation and start).
S
l
l
l
l
l
l
l
l
l
l
l
Schedule
It starts executable objects periodically. A particular UC4 object type.
Script
A script processes statements in UC4's script language. A particular UC4 object type.
Script Variable
A placeholder for a value within a script.
Server process
The core of a UC4 Automation Engine. Different types are available: communication, work and
dialog processes, as well as nonstop processes.
ServiceManager
A program that facilitates the starts and stops of UC4 components.
Service Catalog
A perspective of the Enterprise Control Center. It allows users to start the objects in their Favorites
folder and generally monitor their execution.
start
This refers to the start of a task's execution (see also 'Activation').
static variables
A Variable object with the setting "Source" - "Static": Variable values are entered by a User or with
a script and remain stored in the object.
Statistics
This is a list of a task's previous runs.
status
This represents the condition of a task (such as active, blocked, generating).
Sub-Workflow
A Workflow that is part of a different Workflow.
Automation Engine
l
l
l
389
superordinate task
There are various ways of activating objects. The originator of the activation is referred to as the
superordinate task (parent).
Sync
It synchronizes executable objects based on defined states and actions. A particular UC4 object
type.
System Overview
The UserInterface window that contains information about the UC4 system.
T
l
l
l
task
An executable object that is running is also referred to as a task.
timeout
Occurs when a particular period of time is over.
TimeZone
It defines a local time. A particular UC4 object type.
U
l
l
l
l
l
l
l
l
l
UC4 Automation Engine
It drives a UC4 system and consists of different types of Server processes.
UC4 Automation Platform
A separate UC4 product. Includes the components that are required in order to operate a UC4
system (such as the Automation Engine, UserInterface, Agents, WebInterface).
Available for download from the UC4 Download Center.
UC4 ClearView
A separate UC4 product. Graphical analysis tool: Displays the activities, statistical and forecast
data per UC4 system client in a bar diagram and can be used to calculate the critical path.
Available for download from the UC4 Download Center.
UC4 component
Refers to UC4 programs such as UserInterfaces, the Automation Engine, Agents,
ServiceManagers, utilities etc.
UC4 Database
A relational database management system (RDMS) that administers all scheduling data from a
central point. It contains object definitions, system specifications, statistical data, job reports, etc.
UC4 Insight
A separate UC4 product. Complex graphical analysis tool for the data of UC4 Automation Platform
systems (such as tasks).
Available for download from the UC4 Download Center.
UC4 Policy Orchestrator (
A separate UC4 product. Can be used to define and administer business rules and trigger Events.
Available for download from the UC4 Download Center.
UC4 priority
Affects the order of task execution within a UC4 system.
UC4 Application Release Automation
Separate UC4 product that can be used to define, administer and activate installation and
integration processes and to administer the versions and dependencies of various applications. The
Deployment processes run via the UC4 Automation Platform.
Available for download from the UC4 Download Center.
390
Chapter Glossary
l
l
l
l
l
l
l
l
l
l
UC4 Script
UC4's scripting language.
UC4 Server
Old term for UC4 Automation Engine (v8 or lower).
UC4 Service Orchestrator
A UC4 product. The Service Orchestrator is a perspective of the UC4 Enterprise Control Centers
(ECC) and it is used to handle, monitor and analyze the performance of SLAs (Service Level
Agreements).
UC4 system
An environment that is managed by UC4 components.
UC4 Variables
These are Variable objects that include the UC4 system's specifications.
User
A person who uses a UC4 system. A particular UC4 object type.
User group
A group of users who have a common profile of rights. A particular UC4 object type.
UTC
Internally, UC4 uses UTC (Universal Time Coordinated) because UTC is the international time
standard and is always precise. Nevertheless, TimeZone objects are available that can be used to
show local times in tasks and script elements.
UserInterface
This is UC4's graphical user interface.
utilities
Utilities support the execution of administrative tasks in a UC4 system (such as reorganizing and
archiving the UC4 Database).
V
l
l
Variable
It stores or retrieves values dynamically at runtime. An individual UC4 object type.
Version Management
This refers to an object version that is stored when you have modified the object.
W
l
l
l
l
l
WebHelp
One of the help formats that are provided for manuals. You open it with a Web browser (see also
'HTML Help').
WebInterface
A UC4 user interface that can be called via a Web browser.
wildcard characters
These are placeholders for characters when you specify filters. ? stands for exactly one character, *
for any number of characters.
work process
A part of the UC4 Automation Engine. It is responsible for a UC4 system's processes (see also
'Primary work process').
Workflow
It refers to the execution of processes. A particular UC4 object type.
Automation Engine
X
l
XML file
A format for imports and exports. An XML file contains object structures.
391