Global Event Control Server®
Global Event Control Server®
Version 3.11
Copyright 1991 - 2003 Vinzant, Inc.
All Rights Reserved
I
Global Event Control Server®
Unless otherwise provided in writing, Vinzant, Inc. warrants that the media on which this software program is
provided, will be computer readable for a period of 30 days after delivery. Vinzant, Inc. does not warrant that this
software program will operate with any future versions of other software programs or hardware. Except as set forth
above, the software is provided “as is” without warranty of any kind, either expressed or implied, including, but not
limited to the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the
quality and performance of the software is with the Licensee. Should the program prove defective, the Licensee
(and not Vinzant, Inc. or any agent of Vinzant, Inc.) assumes the entire cost of all necessary servicing, repair or
correction. Vinzant, Inc. does not warrant that the functions contained in the software will meet the users
requirements or that the operation of the program will be uninterrupted or error free. Improper testing or misuse of
this or any software program can cause disastrous loss of information. The licensee is responsible for any and all
costs incurred because of the use of this software program, whether used properly or not. Neither Vinzant, Inc. or
any of its agents are liable for any damages related to the use of this program.The licensee is responsible for
determining the fitness of this software program and the accuracy of the results it produces.
This software program is licensed without any implied obligation of end user technical support, either by Vinzant,
Inc. or its dealers or agents. End user technical support is available from your dealer or from Vinzant, Inc. at an
additional charge. Contact your dealer or Vinzant, Inc. for information on purchasing technical support if you so
desire.
Event Control Server® is a registered trademark of Vinzant, Inc.,
Portions Copyright 1984-1995 Faircom Corporation. All Rights Reserved.
NetWare and MHS are trademarks of Novell, Inc.,
PCDOS, OS/2, LAN Server and cc:Mail are trademarks of IBM Corp.,
MSDOS, Windows, Windows 95/98/ME, Windows NT/2000/XP/2003, MS Mail, MS Exchange,
LAN Manager is a trademarks Microsoft Corp.,
Acrobat is a trademark of Adobe Systems Inc.
II
Table of Contents
Table of Contents
III
Table of Contents
IV
Table of Contents
Table of Contents
CHAPTER 1 - Introduction
The Global Event Control Server®
1-3
CHAPTER 2 - Getting Started
System Requirements
2-3
GECS Express Installation
2-8
Creating and Scheduling Test Jobs
2-10
Configuring GECS Client Computers
2-17
GECS Documentation & Installation
2-18
Upgrading from ECS 5.1
2-18
Upgrading from GECS 2.0 or Later
2-21
Updating your GECS License Number
2-23
CHAPTER 3 - User Guide
GECS System Overview
3-3
Overview of Terminology
3-4
GECS Licensing
3-8
Supported Operating Systems
3-8
Windows Client Program Interface
3-8
GECS System Setup
3-9
GECS Naming & Numbering Schemes
3-11
CHAPTER 4 - Task Automation
Job Creation
4-3
Batch Jobs
4-4
Studio Worksheets
4-4
Job Views
4-4
Job Name
4-5
Command Line
4-5
Capture Output
4-9
Next Run Time
4-9
Job Status
4-10
Sending Keystrokes to Programs
4-19
Job Return Code Overview
4-25
Creating Jobs Using WRK Files
4-33
V
Table of Contents
Submitting Jobs via Mail
4-39
When Your GECS Job Won’t Run...
4-40
CHAPTER 5 - Scheduling Jobs
Scheduling Concepts
5-3
Advanced Scheduling Features
5-6
Defining Calendars
5-6
Valid Time Periods
5-7
Trigger Files
5-9
Job Dependencies
5-11
Depends On Event
5-12
CHAPTER 6 - Events
Event Follow up
6-4
Viewing Events in Lists
6-4
Event Definitions
6-5
Generating User Defined Events
6-6
Event Definitions List
6-7
Setting Up Event Email Notifications
6-9
Event SNMP Trap Messages
6-12
CHAPTER 7 - Monitoring & Managing
Monitoring the GECS System
7-3
Checking the Status of Jobs
7-3
Customize Job And Event Views
7-5
Monitoring GECS Using a Browser
7-6
GECS Administration Overview
7-7
Minimizing User Intervention
7-7
Job Lateness Issues
7-8
Return Code Issues
7-9
CHAPTER 8 - GECS Windows Client Programs
Windows Client Programs Overview
8-3
CHAPTER 9 - GECS Agents
Agent Overview
9-3
Installing Windows Agents from CD
9-3
Installing Agents from Images
9-3
VI
Table of Contents
Create Agent Records
9-6
Starting your Agents
9-6
Running a Test Job on New Agents
9-7
Troubleshooting
9-8
Monitoring Your Agents
9-9
Agent Parameters
9-10
Configuring Agents
9-14
Starting and Stopping Agents
9-15
Agent Command Line Utilities
9-19
Agent Desktop Terminal Commands
9-19
Uninstalling GECS Agents
9-20
CHAPTER 10 - GECS Controller
Controller Overview
10-3
Installing the Controller Program
10-3
Monitoring Your Controller
10-4
Controller Parameters
10-5
Starting and Stopping your Controller
10-13
Configuring Your Controller
10-14
Controller Window Commands
10-16
Uninstalling GECS
10-16
CHAPTER 11 - GECS DBMS
GECS DBMS Overview
11-3
Installing the DBMS Program
11-3
Monitoring Your DBMS
11-4
DBMS Parameters
11-4
Configuring the DBMS
11-8
DBMS Data Backup
11-8
Scheduled Backups
11-8
Setting up a GECS Fail Over System
11-9
GECS System Recovery Procedures
11-9
Starting and Stopping the DBMS
11-10
DBMS Window Commands
11-11
Uninstalling GECS
11-11
VII
Table of Contents
CHAPTER 12 - GECS Web Manager and Browser Clients
GECS Web Manager Overview
12-3
Configuring your Web Manager
12-3
Starting and Stopping the Web Manager
12-3
Web Manager Window Commands
12-4
Using GECS Browser Client Programs
12-4
CHAPTER 13 - GECS Utility Programs
GECS Command Line Utilities
13-3
CHAPTER 14 - GECS Custom Installation
GECS Configurations
14-3
The Basic Architecture
14-3
Adding Agent Computers
14-4
Adding Windows Client Programs on Users Computers
14-5
Managing the GECS System from a Browser
14-6
Installing the GECS System Across Multiple Computers
14-8
Custom Installation Program
14-9
CHAPTER 15 - Technical Reference
GECS.INI File
15-3
Time Synchronization
15-9
Time Change Issues
15-12
Configuring GECS for Sound
15-13
GECS Licensing Restrictions
15-13
CHAPTER 16 - GECS Security
Access to the GECS Client programs
16-3
Security Enhancements
16-4
Setting Up Packet Encryption
16-4
Setting Up GECS Certificate Management
16-4
CHAPTER 17 - File Glossary
File Glossary
17-3
Overview of Data File Structure
17-10
Using ODBC to Access GECS Data
17-11
Job Dump Data Files
17-12
Completed Job Dump Data Files
17-19
VIII
Table of Contents
CHAPTER 18 - Error Numbers
Description of Errors
18-3
Database Errors
18-3
MAPI Error Codes
18-11
WinExec Errors
18-12
CHAPTER 19 - Global ECS System Configuration Worksheet
Global ECS Configuration Worksheet
19-3
CHAPTER 20 - Index
IX
Table of Contents
X
Global ECS Introduction
Introduction
1-1
Global ECS Introduction
1-2
Global ECS Introduction
The Global Event Control Server®
The Global Event Control Server® (GECS) is a set of integrated tools for creating a sophisticated computer
automation, job scheduling and batch processing system. GECS lets you apply mainframe concepts of 24 hour job
scheduling and automated batch processing to your client / server systems.
GECS uses several components to create, monitor, control and run jobs; Client programs , Controller, DBMS, Web
Manager and Agent programs.
Client Programs
The Client programs are run on users’ workstations. They provide a single point of control for monitoring and
managing job streams and the GECS system. There are two types of GECS Client programs. There are Browser
Based Client programs and Windows Client programs. When the GECS Web Manager program is running, the
Browser Based Client programs can be run from most computers running a browser. The Web Manager program
has an integrated web server and no additional web server is needed. The Windows Client programs can be run on
Windows Workstations or Servers that have network access to the computer running the GECS DBMS program or
data files.
DBMS, Controller and Web Manager Programs
The DBMS, Controller and Web Manager programs run on a Windows NT/2000/XP/2003 Server or Workstation.
They are all usually run on the same machine. The DBMS allows access to the GECS data. The Controller
dispatches jobs to available Agents. The Web Manager is an interface between an internet browser and the GECS
DBMS.
Agent Programs
GECS Agent software must run on every computer on which jobs will run. The GECS Controller dispatches jobs to
available GECS Agents. The Agents answer status requests from the Controller and DBMS programs. There are
Agents available for computers running:
• Windows NT v4.0 or higher (Server or Workstation)
• NetWare 4.11 or 5.0
1-3
Global ECS Introduction
• SCO UnixWare v2.1 or v7.0
• Linux (Red Hat Linux v5.1, Caldera OpenLinux 1.2 or SuSE Linux 6.1) for Intel
• HP-UX v10.x
• Solaris 2.6 for Sparc and Solaris 2.6 for Intel
• AIX
• Tru64 Unix (Digital Unix)
• (Silicon Graphics) SGI IRIX.
Architecture
GECS Client programs can run on any computer running an internet browser or Windows
95/98/ME/NT/2000/XP/2003 PC (where the GECS Client programs are configured). Client programs allow users
to enter data into and monitor the GECS system. The Windows Client programs can be installed locally on each
client machine or can be accessed over a network from a shared drive. Client computers must be able to access the
DBMS or Web Manager via TCP/IP.
The GECS system uses one DBMS and one Controller to control all Agents and to dispatch jobs to computers
running the Agent software on Windows NT/2000/XP/2003, NetWare, SCO UnixWare, Linux, HP-UX, Solaris,
AIX, Tru64 Unix or SGI IRIX. The DBMS and Controller programs must always be running to control and dispatch
jobs to Agents. When using browser clients, the Web Manager program must be running.
The Agent programs accept jobs from the Controller and answer status requests from the Controller and DBMS via
TCP/IP or drive sharing.
Regardless of operating system, each computer running either the Agent, Controller, DBMS, Web Manager or
Windows client software must have a TCP/IP protocol stack loaded.
1-4
Global ECS Introduction
Supported operating systems can be mixed in any fashion. For example, you may have a Linux Agent, an HP-UX
Agent, a Windows Agent and use any machine with an internet browser to monitor the system.
In addition to the Client, Controller, DBMS, Web Manager and Agent software programs, a variety of maintenance
and testing programs are installed.
As a test, you must be able to ‘ping’ each computer which will run GECS Agent software from the computer which
will be the GECS DBMS and Controller. Use PING.EXE which comes with Windows.
You will need to know the IP address or name of each computer that will be running the Agent software. This might
beintheformof
Your GECS license determines the type and number of machines that can run the Agent programs at one time.
There is no limit on the number of PCs that can run the Client programs at one time. You can only run one
Controller, one DBMS and one Web Manager.
The different operating system platforms supported by GECS Agents can run different types of programs as jobs.
This is referred to as the command line type. The operating system, GECS Agents and the types of command lines
they can run can be summarized by:
Windows Agent
• BAT or CMD Batch Files
• DOS Programs
• OS/2 Text Programs
• Windows 3.1/95/98/ME/NT/2000/XP/2003 Programs
AIX Agent
• AIX Programs
HP-UX Agent
• HP-UX Programs
Linux Agent
• Linux Programs
NetWare Agent
• NetWare NLMs
SCO UnixWare Agent
• SCO UnixWare Programs
Solaris Agent
• Solaris Programs
Tru64 Unix Agent
• Tru64 Unix (Digital Unix) Programs
SGI IRIX Unix Agent
• SGI IRIX Unix Programs
There are limitations on some of the program types depending on the way the Agents are being run (hidden, as a
service or daemon).
1-5
Global ECS Introduction
In addition to the different operating system platforms supported by GECS, the Windows clients, DBMS and the
Controller can interface with NetWare networks, Microsoft networks (workgroups and networks) and LAN Server
(LAN Manager & ) networks. When networking features are enabled, they can automatically recognize network
user names as GECS user names and they can send network messages for Event notification using the standard
messaging capabilities built into these networks.
The GECS DBMS can also interface with MS Mail or MS Exchange using , cc:Mail using VIM or MAPI, Lotus
Notes Mail, Internet Mail (SMTP/POP3) or MHS mail systems. GECS will send messages via these mail systems
to indicate special Events such as the completion of jobs or to notify the system manager of problems. Jobs can also
be mailed to GECS via most of these mail systems.
It is important that you pay attention to software versions with GECS. All GECS programs in use must be of the
same version. Do not mix programs of different versions.
1-6
Getting Started
Getting Started
2-1
Getting Started
2-2
Getting Started
System Requirements
Client Programs
GECS Windows Client programs will run on any Intel based hardware environment that is supported by Windows
95/98/ME/NT/2000/XP/2003. Minimum hardware requirements; Pentium 200 with 32 megabytes of RAM.
Browser based Client programs should run on most computers running a browser.
DBMS, Controller and Web Manager
The GECS DBMS, Controller and Web Manager programs will run on any Intel based hardware environment that is
supported by Windows NT version 4.0 or higher. Though GECS will operate on the minimum hardware required to
run Windows NT/2000/XP/2003, typically that will produce slow operation. The following are recommended
minimum hardware requirements; 1 Gigahertz Pentium or above with 128 megabytes of RAM. For systems with
large numbers of jobs, faster CPU with more memory will be essential.
GECS Agents
GECS Agent programs and supported operating systems are listed below.
Windows Agent
- Windows NT version 4.0 or higher with minimum hardware requirements
Pentium 200 with 32 megabytes of RAM.
AIX Agent
- AIX version 4.3 or higher
Linux Agent
- Red Hat Linux version 5.1
- Caldera OpenLinux version 1.2
- SuSE Linux 6.1
HP-UX Agent
- HP-UX version 10.x
NetWare Agent
- NetWare version 4.11 or 5.0
SCO UnixWare Agent
- SCO UnixWare version 2.1 or version 7.0
Solaris Agent
- Solaris version 2.6 for Sparc
- Solaris version 2.6 for Intel
Tru64 Unix Agent
- Tru64 Unix (Digital Unix) version 5.0 or higher
SGI IRIX Unix Agent
- (Silicon Graphics) SGI IRIX Unix
Hardware Recommendations
Frequently the question is asked, “How much hardware power does GECS need?”. GECS will run on very limited
hardware power, though as the power is increased GECS can take advantage of it. Sometimes this occurs
automatically, other times through system configuration. The jobs you intend to run, the operating system you’re
using and your desired level of performance will determine the hardware power required.
On its own, GECS puts very little drain on the system. Your previous experience with the jobs you intend to
automate should indicate the amount of power and the number of Agents that are required. Due to the nature of
GECS, you can always add more PCs as Agents to improve performance and job throughput.
It will take GECS just as long to run your jobs as it would if you were to run the jobs manually. GECS simply
does it on schedule, with fewer mistakes and less wasted time.
2-3
Getting Started
GECS Documentation
The GECS online manual (GECSMAN.PDF) is shipped on the Global ECS Windows CD ROM. It can be viewed
using the Adobe Acrobat Reader. The Adobe Acrobat Reader (ACROREAD.EXE) can be installed separately from
the Global ECS Windows CD ROM. Installation information is described later in this chapter.
The GECS Client programs also contain separate help files that can be displayed when using the Client programs.
Microsoft Network
To run GECS on a Microsoft network, all computers running GECS client and Controller/DBMS programs must be
able to login to the network running the Microsoft Network. From the Workstation Setup program, set the “Use ..
networking for security and messaging ” field to “Microsoft” to configure Microsoft networking features.
NetWare Network
To run GECS on a NetWare network, all computers running Windows client program or the Controller/DBMS
program must be able to login to the network running Advanced NetWare 2.15 or above. When used with NetWare
version 4 or 5, Bindery emulation is required. Each PC that will access the GECS data must have the NetWare
Client software (from Novell) installed. The NetWare Client for Windows software puts a number of DLLs in the
\WINNT subdirectory that GECS needs in order to work with NetWare. Set the “Use .. networking for security and
messaging” field to “NetWare” in the Workstation Setup program to configure NetWare networking features.
LAN Server Network
To run GECS on a LAN Server network, all computers running the Windows Client programs or the
Controller/DBMS program must be able to login to the network running LAN Manager 1.0 or above or LAN Server
1.0 or above. Set the “Use .. networking for security and messaging” field to “ Manager” in the Workstation Setup
program to configure LAN Server or Lan Manager networking features.
No Network
Any computer running Windows Client programs or the Controller/DBMS program can be run with no network.
Set the “Use .. networking for security and messaging” field to “No” in the Workstation Setup program when not
using network features.
If you choose “No” networking, you will be prompted to login to every Windows client program (.e. a Login
window will appear prompting you for a GECS User Name and Password). If you do not wish to login each time you
open a Windows client program, choose one of the networking options mentioned above.
TCP/IP
A Transmission Control Protocol/Internet Protocol (TCP/IP) stack must be running in any machine that will be
running GECS programs.
Mail
In order for GECS to send and receive mail, a copy of the MHS, NetWare Global Messaging or NetWare Messaging
must be installed and configured on the file server. You must create a mail user for GECS that will interface with the
mail system.
2-4
Getting Started
cc:Mail (VIM)
In order for GECS to send and receive cc:Mail (VIM) messages, cc:Mail must be installed and configured on a file
server. The PC that will be running the GECS Controller/DBMS software must have the cc:Mail Workstation
software installed on the local hard drive. VIM32.DLL and the other 32 bit cc:Mail DLLs must be in a subdirectory
in your search path. You must create a mail user for GECS that will interface with the mail system. Versions 8 and
higher of cc:Mail use MAPI. If you are using version 8 or higher, refer to the MS Mail/Exchange (MAPI) sections
for setup information.
Lotus Notes Mail
In order for GECS to send and receive Lotus Notes Mail messages, Lotus Notes must be installed and configured on
a Notes Server. The PC that will be running the GECS Controller/DBMS software must have Lotus Notes
Workstation software installed and configured on the local hard drive. VIM32.DLL and the other 32 bit Notes
DLLs must be in a subdirectory in your search path (i.e. c:\notes). You must create a mail user for GECS that will
interface with the mail system.
MS Mail (MAPI)
In order for GECS to send and receive MS Mail () messages, the MS Mail client software must be installed and
configured on each Workstation that will be running the Controller/DBMS software. MAPI32.DLL must be in a
subdirectory in your search path. You must create a mail user for GECS that will interface with the mail system.
Note that other mail systems such as Groupwise and cc:Mail version 8 or higher also use MAPI. When using these
mail systems with GECS, choose the Microsoft mail system option.
Internet Mail (SMTP / POP3)
In order for GECS to send and receive Internet Mail messages, WSOCK32.DLL must be in a subdirectory in your
search path. You must have an email address for GECS that will interface with internet mail.
SNMP Traps
In order for your GECS DBMS to send SNMP trap messages when certain GECS Events occur, you must install the
SNMP service on the Windows computer that will be running your DBMS program. You then configure the
appropriate Event Definitions. See the Events chapter of this manual for more details.
Audio WAV files
GECS Events can be configured to play WAV files when an Event occurs. Use the Event Definitions to specify the
fully qualified path and WAV file name to be played when the specified Event occurs.
Help Files and Tutorial
A Help file (GECSHELP.HLP), including a tutorial, can be accessed from the GECS Windows Client programs
from any ‘Help’ pull down menu or by pressing the <F1> key while your cursor is positioned on a data field within
the GECS Windows Client programs.
GECS HTML help is available via the GECS browser based clients by clicking the “Help” option(s).
2-5
Getting Started
What’s Different from Standard ECS
Global ECS is very similar to, but incompatible with ECS. DO NOT mix Global ECS with any versions of ECS.
Global contains many programs that closely resemble programs included with ECS version 5.1. One major
difference between using Global ECS and standard ECS is that you use the GECS Administrator program to setup
Agents and a Controller and DBMS rather than setting up Job Servers with Server Edit. With Global ECS, the Job
Server has been cut in half. Part of the Job Server functionality is performed by the Agent and part by the Controller
and DBMS. You must set up each Agent, Controller and DBMS using the Administrator program.
Another major difference is the method by which GECS components communicate. The Controller, DBMS,
Agents and Client monitoring programs use TCP/IP to communicate with one another.
Additionally, when you set up Agents, there are two new required fields: IP Address and IP Port which tell GECS
how to communicate with the Agent. You must enter the IP Addresses of the computers that will run the Agent
program. The IP Port of the computer must also be specified. An Agent can ONLY be serviced by one Controller.
A single GECS Controller will control all Agents. As far as the other fields go in the Agent, Controller and DBMS
programs, you need to think of the fields from the perspective of either the Agent, the Controller or the DBMS. For
example, the Pulse Rate field is entered for a Controller. How often should the Controller pulse? On the other hand,
the Operating System field is entered for the Agent. What operating system is the Agent running on?
Jobs are entered the same. When selecting which job server should run the job, you should select the Agent that
should run the job, not the Controller. When you look at the Completed Jobs, you will see the Agent that ran the job,
not the Controller. When entering information about Agents running on Unix or jobs that should run on Unix, be
sure to specify the right command line type and operating system.
The GECS Administrator is updated in version 3.10. It allows you to manage your entire GECS installation from
one utility. The utilities that it replaces (e.g. Job Edit, Batch Manager) are no longer available.
GECS does not utilize Btrieve. A database manager program has been added to the system.
Agent programs can run on a variety of new operating systems.
A new Web Manager program makes it possible for users to access the GECS system remotely using a browser from
most computers.
What’s Different from GECS 3.0x
The major differences from GECS v3.0x have been broken down into several categories below.
Events: Sentry has been eliminated. Its functionality has been incorporated into Administrator through the use of
Views, Events and the DBMS. Sentry Events have been replaced with GECS System Events. New GECS Events
make it easy for users to choose which Events they care about and what actions or notifications they would like
generated when the particular Event occurs. Ability to send SNMP Trap numbers and messages when a particular
Event occurs. Jobs can depend on the occurrence of Events. User can create and define your own Events. Ability to
activate jobs based on specified Events occurring. Ability to customize notifications, using Event Definitions you
can customize the messages sent when specific Events occur. Ability to play specified WAV files when specified
Events occur.
Job Views: Sentry lists have been replaced with new customizable views. New Job Views to allow customized
filtering of jobs displayed in lists. Users can add and share an unlimited number of separate job views. Ability to
display jobs within specified windows of time. Ability to sort job lists by job number, date/time or job status.
Ability to display job's schedule time, start time or finish time in views. More responsive list population. New
Batch Summary views allow jobs to be displayed at the batch or job level. Customizable background and
foreground color in Job views. Lists can be sorted ascending or descending by clicking column headers. Delete and
Insert buttons can be used in lists and multiple items can be selected in lists.
2-6
Getting Started
Event Views: New Event views to allow customized filtering of Events displayed in lists. Users can add and share
an unlimited number of separate Event views. Users can be alerted to special Events. User Event indicator button at
the bottom right corner of the Administrator program. Customizable background and foreground color in Event
views. Lists can be sorted ascending or descending by clicking column headers. Delete and Insert buttons can be
used in lists and multiple items can be selected in lists.
Job Changes: Job record now contains the new Minimum Good Return Code field. Job record now contains the
new Never Late field. Job record now contains the new Job Notes field contains an ASCII text file that can be edited
and used for notes or documentation relative to the job. Job record now contains the new Generate Event on success
and on failure fields. Job status of Waiting Approval has been renamed to On Hold. New Capture Output field. New
login as submitting user fields.
Controller Error File: No more controller error logs (CONTROL.ERR). It has been replaced by Events.
Log File: No more log file. Log information is now maintained with jobs and by Events. Jobs run only once,
repeating jobs create a new instance for each time scheduled to run. New Job statistics information in the job record
contains completed job information.
Security: Optional Enhanced 128 bit Data Encryption for communications when the optional Certificate
Management for added security is enabled. New Security Profiles.
SNMP: The DBMS can now generate SNMP traps for Events that occur. The new GECSMIB.DLL can be used
with Microsoft's SNMP service to monitor GECS from network management software programs.
Starndard Out and Standard Error: Agents can now capture Standard Out and Standard Error. This information
can be saved to a file and displayed in the Job Detail screens.
Other:
• Ability to send Internet Mail attachment(s).
• DBMS data backup option adds the ability click a button to quickly backup GECS data or run a com-
mand line utility to backup GECS data.
• New Command Line Utilities GECSCHNG, GECSEVNT, GECSBKUP, GECSCERT, GECSSIZE
and GECSEDEL.
• Enhanced Web Client programs.
• SDK Updates.
• New Substitution Variables - @BATCH for batch name, and MANY MORE …
• Allowing the use of formatting strings in substitution variables such as (%m).
• You can no longer simulate a job. This has been replaced with the ability to change the job's return code
or skip and reschedule the job.
• The DBMS handles loading WRK files not the Controller and the DBMS now sends and receives all
email. The DBMS now handles most system maintenance tasks such as purging old Jobs.
• Job detail now has the new This Jobs History toolbar button and Events toolbar button
• Job detail can display Standard Out in the Job Detail Output tab.
• Ability to ping Agents, Controller, or DBMS from the Administrator program.
• All lists can display a record count by right clicking on the column header. Left clicking column headers
in Jobs, Events and Event Definition lists sorts data ascending or descending. Multiple items in lists can
be selected. Delete and Insert Keys work in lists.
• For faster performance, Client machines can be configured to bypass the DBMS and access the GECS
data files directly. For direct data access, specify the data path using the Client Programs page of the
Workstation setup program.
2-7
Getting Started
Installing GECS
IMPORTANT: If you’re upgrading an existing installation of ECS or GECS, see page 2-19 thru 2-22 of
this manual. Do not follow the express installation directions when upgrading.
All GECS programs are shipped on the Global ECS Windows CD ROM or can be downloaded from our web site.
Agent software for Unix systems are shipped on either a CD ROM or can be downloaded from the Global ECS web
site. This media contains the Agent program (GECSAGNT) along with command line utility programs. For details
on installing Agents see the Agents chapter of the GECS manual.
When installing from the Global ECS CD ROM, your installation options are as follows: Complete Installation,
Install Agent Only or Install Client Programs Only.
GECS Express Installation
Evaluators and first time GECS users should follow the installation directions below.
These instructions are for the Express Installation. They will quickly install and configure all components of the
GECS System on one computer.
IMPORTANT: If you’re upgrading an existing version, see page 2-19 thru 2-22 of this manual.
1. Determine which Windows Workstation or Server will be your primary GECS computer. This computer will
run the Controller, DBMS, Web Manager, one Agent and store the GECS data files. This computer must have a
TCP/IP protocol stack loaded.
2. Go to the primary GECS computer and login as Administrator or an administrator equivalent user.
3. Insert the Global ECS Windows CD ROM. If the installation program does not automatically start, click the
Start button, select Run and enter:
D:\SETUP.EXE
2-8
(Where D: is your CD ROM drive).
Getting Started
4. The default settings on this screen are fine. Click the “OK” button to continue.
5. Once the files have been copied, choose “Express” from the Global ECS Setup screen and click the “Next”
button.
6. Enter your Company Name and License Number, then click the “Next” button. Your license number is in
the format of: XXXXX-XXXXXXXXX.
7.
Finally, click the “Configure” button to complete the configuration.
On your Windows desktop you should see a shortcut folder for your Global ECS icons. Express configuration
automatically starts your GECS Controller, DBMS and Web Manager, as services under the system account. One
Windows Agent is created and configured to run on the desktop. You can now begin creating, scheduling and
running jobs on this machine.
Install Agent Only
The Install Agent Only installation option will install the GECS Agent for Windows. To set up additional Agents on
other operating systems see the Agents chapter of the GECS manual.
Install Client Programs Only
Browser based Client programs do not require configuration or installation. Users can access the GECS system via
a web browser as long as the GECS Web Manager program is running. See the Web Manager chapter of the GECS
manual for details on the GECS Web Manager and browser Client programs.
GECS Windows Client programs can be installed locally on users computers or installed on a sharable drive and run
over your network. Installing Client programs locally offers the best performance. To install the GECS Windows
Client programs, see the “Configuring GECS Client Computers” section of this chapter.
2-9
Getting Started
Creating and Scheduling Test Jobs
Suppose you have three jobs that need to run every morning at 6am. You can use GECS Batches to create a Batch
containing your three jobs.
For testing purposes, all three Batch jobs will automate the same task.
DIR
(DIR will temporarily display a directory listing).
1. To create a new Batch, start the Global ECS Administrator. Right click on the Batches folder from the list on
the left of the screen. Then select New.
2. Type the name of the test Batch you wish to create
TESTBATCH
then click the Add button.
3. To create the first job for your Batch, click the Add... button on the Batch Jobs tab.
4. Type the name of the test job you wish to create
TESTJOB1
then click the Create button.
2-10
Getting Started
5. On the Command Line field enter: DIR
6. Set the Command Line Type to NT Console.
7. Ensure the Job Status field is set to Pending.
8. Save the job by clicking on the File pull down menu and selecting Save.
9. To create two more jobs, for your Batch, you can copy the first job by clicking on the Copy pull down menu and
selecting Copy Batch Job. Copy As: TESTJOB2 then from the File pull down menu select Copy Batch Job.
Next Copy As: TESTJOB3 and again from the File pull down menu select Copy Batch Job. Then from the File
pull down menu select Exit. You can use the blue arrow buttons to reorder the display of the batch jobs.
10. To set up your jobs to repeat every day at 6am, click on the Scheduling Options tab. Set the Beginning On
date to today’s date at 06:00:00. Set the Scheduling Model field to Dynamic. Set the Schedule Type field to
Day of the Week Schedule. Enter check marks next to Monday, Tuesday, Wednesday, Thursday and Friday.
11. Save the Batch by clicking on the File pull down menu and selecting Save.
12. To schedule the Batch for execution, click on the File pull down menu and select Schedule Batch Jobs.
13. Continue by clicking Next. Then to complete the process click Finish.
Your test jobs are now scheduled for execution. Once your Agent is started, and if the current time of day is after
6am, these jobs will run immediately. Otherwise, they will wait until 6am to run.
14. Start your GECS Agent by double clicking on the Agent icon from your Global ECS folder.
2-11
Getting Started
Checking the Status of your Jobs
Use the GECS Administrator program to check the status of your jobs. From the Jobs folder look at the “Batch
Summary” View. You will see a list of your jobs. These lists are moveable, sizable and configurable.
The information displayed in the lists can be sorted ascending or descending by clicking on the column headers of
the lists. You can also right click on list column headers to display a record count or print the list.
You can select multiple items in lists by highlighting the items or by clicking the shift key and using the up and
down arrow keys. An arrow will denote which items are selected.
You can update Job Views or add your own. Right click on the View name (such as Batch Summary) and select
View Properties to update the filtering that can be applied to the view of jobs. You can double click on a job from
the list to view the Job Detail screens. By default, GECS ships with the views displayed in the screen below.
1. On the left side of the GECS Administrator, double click on the Jobs folder then click on the “Batch
Summary ” view.
2. Click on the File pull down menu and select Refresh to update the screen.
After the jobs run, their status will be set to complete and a new instance of each job will be created for tomorrow at
6am. Right click on one of the Pending Jobs scheduled to run tomorrow then select ‘why this job can’t run’. The
reason should be future start time. Experiment with some of the other options.
2-12
Getting Started
Viewing GECS Events
The Administrator program will display Event views by double clicking on the Events folder. You can use the
default ‘All Events’ view to display a list of All Events.
The last column on the right side of the Events list displays the status of each Event. The status is either open or
closed. Next to the status will be a green or red dot. This color indicates whether this Event is included in your
‘Users Events’ view. A red dot mean that the Event exists in your ‘Users Events’ view. A green dot means that the
Event is not included in your ‘Users Event’ view.
Click on the Event indicator dot on the bottom right corner of the Administrator program to jump to the ‘User’s
Events’ view.
You can view all Events associated with each job from the job detail screen via the ‘This Jobs Events’ toolbar
button.
The Event lists are moveable, sizable and configurable. You may wish to filter the Events displayed in these list or
create you own views and customize them. To customize your views, right click on the view name and select View
Properties.
The information displayed in the lists can be sorted ascending or descending by clicking on the column headers of
the lists. You can also right click on list column headers to display a record count or print the list.
You can select multiple items in lists by highlighting the items or by clicking the shift key and using the up and down
arrow keys. An arrow will denote which items are selected.
By double clicking on an Event from this list you can display the Event Edit information. Right clicking on an Event
from the list will give you additional options such as:
Close Event - Update the status of the Event from open to closed.
Delete Event - Delete the Event from the GECS system.
Remove My Name - Remove this Event from my ‘User’s Events’ View list (in other Views that may still display
this Event, this will also change the color of the status dot from red to green).
View Event Detail - Display the Event Edit information screen.
2-13
Getting Started
1. From the GECS Administrator, double click on the Events folder then click on the default view All Events.
2. You should see a list of Event records. Double click on an Event to display the Event Edit screen.
3. When you are finished viewing you can close the Event record.
By default, one GECS user, one Controller, one DBMS and one Agent were installed on this computer during the
GECS “Express” Installation. These records were created using default settings. If you wish to make changes to
these records or create additional users or Agents follow the instructions below.
Setting Up GECS User Records
Double click on the Users folder then click on the user record. Review the user created by the Workstation Setup
program. Notice that this user was assigned to the ADMIN Security Profile. This ensures that this user has access
to all GECS components.
1. To add an additional user, click on the File pull down menu and select New User. Enter the user name then
click the Add button.
2. Select a Security Profile from the Security Profile Lookup. This field is used to set a profile for GECS security
access into the GECS Client program modules.
Each GECS User record is assigned a GECS Security Profile. The Security Profile will allow access to whichever
GECS Client programs the Security Profile record has defined. By default an ADMIN and OPERATOR Security
Profiles are defined.
You can create as many GECS Security Profiles as necessary. The ADMIN default Security Profile can be
modified but cannot be deleted. The OPERATOR default Security Profile can be modified and/or deleted.
3. Save the record by pressing the F10 key or click the File pull down menu and select Save.
4. Set up records for additional GECS users, as needed.
2-14
Getting Started
Review or Create Agent Records
Review the Agent record created by the Workstation Setup program by opening the GECS Administrator icon and
double clicking on the Agents folder on the left side of the screen.
1. Click on the Name of your Agent under the Agents folder.
2. Review your Agent information. You can press the F1 key for online help.
3. Set up records for additional Agents, as needed. To add a new Agent record, click on the File pull down menu
and select New. Enter the GECS name of your Agent (i.e, NTAGENT or HPAGENT) then click the Add
button.
4. Enter the IP Address or IP Name of this Agent. (DNS server will resolve names). On the Agent tab, most of
the default settings can be used.
IP Address:
IP name or address of Agent
Port:
Port number used when starting Agent (2000)
5. On the Characteristics page set the following fields:
Operating System:
choose the operating system that applies
Job Types:
choose applicable job type(s)
6. Save the record by pressing the F10 key or click the File pull down menu and select ‘Save’.
7. Set up records for additional Agents, as needed. For details on installing the Agent software, see Agents
chapter of the GECS manual.
2-15
Getting Started
Controller and DBMS Settings
Review the Controller and DBMS Settings created by the Workstation Setup program by opening the GECS
Administrator and clicking on the Controller Settings and DBMS Settings options on the left side of the screen.
You can press the F1 key for online help. All default settings are fine for now.
Event Definitions
Review the default Event Definitions by opening the GECS Administrator and clicking on the Event Definitions
option on the left side of the screen. Each Event is numbered and contains parameters to allow for special
notifications. These notifications include: email, SNMP, network message, Windows event logging, job
activation, audible wav file, and color highlighting in the GECS Administrator Events lists.
Use the Event Definitions folder to update Event parameters. GECS system Events are numbered from zero to
500 and cannot be deleted. User definable Events can be numbered starting from 1000. You can press the F1 key
for online help. Default settings are fine for now.
2-16
Getting Started
Configuring GECS Client Computers
Once you have installed all components of the GECS system, you can configure additional computers to run the
GECS windows Client programs from remote Windows computers. Remember to set up appropriate GECS Users.
Clients must have appropriate security profiles established or they will not be allowed into the GECS components.
These computers must have a TCP/IP protocol stack loaded.
1. To configure remote client computers, insert the Global ECS CD ROM and “Install Client Programs Only”
into the default directory on each target machine then click the “OK” button.
2. After the new files are installed, click the “Finish” button to begin setting up this Client computer. You will
need to enter information about your GECS system components into the following screen.
3. Enter IP Address or IP name of the computer that is running your DBMS.
4. If this Client computer can directly access the GECS data files, check the “Enable Data Path” field. Enable
this option if you wish to allow your GECS Client programs to access the GECS data files directly for faster
performance. When this field is enabled you must also specify the path to use for client access to the data files.
Because using this direct data access method is performed by the operating system and network drivers, the GECS
data encryption is NOT available even if a certificate is installed.
When this field is not enabled, your client programs will use TCP/IP to request data from your GECS DBMS.
Using this method you can install optional certificates to enable a very strong 128 bid data encryption algorithm.
5. When you are finished, click the “Configure” button then click the “OK” button.
2-17
Getting Started
GECS Documentation & Installation
When you install the GECS Client software for Windows the GECS documentation is automatically installed. The
GECS documentation file is named GECSMAN.PDF. An icon for this document is created in your GECS folder
along with other GECS icons. Adobe Acrobat Reader software should be used to view the GECS documentation
file. If you get an error message trying to open this file you probably need to install the Adobe Reader.
The Adobe Acrobat Reader must be installed separately. You can use \Acrobat\SETUP.EXE from your Global
ECS Windows CD Rom or install from your own Acrobat CD.
Once the Adobe Reader and GECS documentation files have been installed, you can view the GECS documentation
by double clicking on the Online Manual icon in your Global ECS desktop folder.
Refer to the documentation and/or help supplied with the reader for information about the readers features and how
to use the viewer for searching the documentation.
Upgrading from ECS 5.1
1. If using Job Dependencies, allow all Job streams to finish before upgrading and/or Remove Scheduled Batch
Jobs from the Jobs queue. Log records are no longer used for verifying Job Dependencies. A new method is used.
Therefore, if you upgrade in the middle of a job stream, your remaining jobs may run out of sequence.
2. Make a note of each User’s security access into the Client programs. This information will need to be
reassigned using Security Profiles after upgrading.
3. Stop all ECS programs.
4. Go to a computer that can run ECS 5.1 and that will run your new GECS Controller and DBMS programs.
This computer must have a TCP/IP protocol stack loaded. Login as Administrator or an administrator equivalent
user.
5. The ECS.INI file MUST exist in the local C:\WINNT directory before you continue.
6. Backup your ECS data. (ECS 5.x data files have no extension, i.e. JOBS., USERS., etc.).
7. Insert the Global ECS Windows CD ROM. If the installation program does not automatically start, click
the Start button, select Run and enter:
D:\SETUP.EXE (Where D: is your CD ROM drive).
Or download the programs from our web site at www.globalecs.com
8. A message will display prompting you to upgrade. Click “Yes” to upgrade. Program Files will be copied into
the default GECS directory.
9. GECS Workstation Configuration screen will appear. To configure this computer to run the new GECS 3.x
DBMS program, use the default settings. Click the “Next” button..
10. Configure the computer to run the new GECS 3.x Controller program.
The default settings
should be used. Click the “Next” button.
11. You should configure this computer to run the new GECS 3.x Web Manager program. The default settings
should be fine. Click the “Next” button.
12. To install an Agent to run on this computer, you may either leave the default settings or make modifications to
reflect a name used by an ECS 5.1 Job Server. (ECS Job Server names should become GECS Agent
2-18
Getting Started
names. It is important to keep your job server names if you have jobs required to run on specific job servers
because now they will need to run on specific Agents). Then click the “Next” button.
13. Click the button to create icons for Client programs on this computer then verify the type of networking (for
security and messaging) then click the “Next” button.
14. There is a new option to Enable SNMP messaging for Event notifications.
15. There is also a new option to allow your GECS Client programs to access the GECS data files directly. To get
faster performance, check the Enable data path field. When this field is enabled you must also specify the path to
use for client access to the data files. (Note that because using the direct data access method is performed by the
operating system and network drivers, the GECS data encryption is NOT available even if a certificate is
installed). Click the “Next” button to create icons for Client programs on this computer
16. Verify the desktop folder name you would like for your GECS 3.x icons, then click the “Next” button.
17. Enter your Company Name and License Number then click the “Next” button. Your license number is
printed on the label attached to your Global ECS Windows CD ROM case in the format of:
XXXXX-XXXXXXXXX
18. Click the “Configure” button to complete the configuration.
19. On your Windows desktop you should see a shortcut folder for your Global ECS icons. This
configuration automatically starts your GECS Controller, your DBMS and Web Manager, as
services under the system account. One Windows Agent is created and configured to run on the
desktop. These are all the components you need for your GECS system.
20. After converting your data, review your GECS 3.x Agent and Controller and DBMS records. Next, review
and modify all jobs and Batch jobs to include your new Agents and resources. Jobs that were previously setup
to run on specified job servers should now be modified to run on specified Agents. Jobs requiring job server
resources should be modified to require Agent resources.
21. All upgraded User records are converted to Administrative (ADMIN) Security Profiles giving them access to
all GECS components. Modify your User records as needed to associate each User with the appropriate
Security Profile.
22. If your Job Server and or Sentry was set up to send email you now need to configure your DBMS Settings to
reflect email. The DBMS will now send email and the Event Definitions will tell it on which Events to send it.
Next, review all Jobs and Batch Jobs and verify their schedule information.
23. You can use the new Job and Event Views to customize your lists to display the same type of information you
were used to seeing in the old GECS Sentry program.
24. Look through the Event Definitions module to configure job completion, job failure and other Events that you
wish to be notified of.
Upgrading ECS 5.1 Job Servers to GECS 3.11 Agents
1. Go to a Windows computer that runs an ECS 5.1 Job Server. Make note of the Job Server name.
This computer must have a TCP/IP protocol stack loaded. Login as Administrator or an administrator
equivalent user.
2. Stop the Job Server program.
3. Install GECS 3.11 Agent software on this computer. Insert the Global ECS Windows CD ROM (or insert a
GECS Windows Agent diskette or download the Agent software from our web site). (See the Agents
chapter of the GECS manual for instructions on Agent Installation). If the installation program does not
automatically start, click the Start button, select Run and enter: D:\SETUP.EXE (Where D: is your CD ROM
drive).
2-19
Getting Started
4. Click the “Install Agent Only” option. Then click the “OK” button.
5. After the new files are installed, click the “Finish” button to begin setting up this Agent.
6. Enter the Name of your Agent (this should be your Job Server name).
7. Click the “Configure” button to complete the configuration then click “OK”.
8. Once you have verified Agent names and Agent parameters you can start your Agent.
Upgrading ECS 5.1 Clients to GECS 3.11 Clients
1.
Go to a Windows computer. This computer must have a TCP/IP protocol stack loaded.
Login as Administrator or an administrator equivalent user.
2. Stop any ECS programs.
3. Insert the Global ECS Windows CD ROM or download the GECS software from our web site. If the
installation program does not automatically start, click the Start button, select Run and enter:
D:\SETUP.EXE (Where D: is your CD ROM drive).
4. Click the “Install Client Programs Only” option. Then click the “OK” button.
5. After the new files are installed, click the “Finish” button to begin setting up this Client computer.
6. Enter the IP Address of the DBMS for your GECS system.
7. Set the ‘Enable Data Path’ option if you wish to allow your GECS Client programs to access the GECS data
files directly for faster performance. When this field is enabled you must also specify the path to use for client
access to the data files. Note that when using direct data access method, the GECS data encryption is NOT
available even if a certificate is installed.
8. Click the “Configure” button to complete the configuration then click the “OK” button.
2-20
Getting Started
20. Click the “Configure” button to complete the configuration.
21. On your Windows desktop you should see a shortcut folder for your Global ECS icons. This configuration
automatically starts any GECS components that were configured to run as services.
22. All upgraded User records are converted to Administrative (ADMIN) Security Profiles giving them access to
all GECS components. Modify your User records as needed to associate each User with the appropriate Security
Profile.
23. Review your GECS Agent, Controller and DBMS records. If your Controller and or Sentry was set up to send
email you now need to configure your DBMS Settings to reflect email. The DBMS will now send email and the
Event Definitions will tell it on which Events to send it. Next, review all Jobs and Batch Jobs and verify their
schedule information.
24. You can use the new Job and Event Views to customize your lists to display the same type of information you
were used to seeing in the old GECS Sentry program.
25. Look through the Event Definitions module to configure job completion, job failure and other Events that you
wish to be notified of.
Upgrading Agents from GECS 2.0 or Later
1. Go to your Agent computer. Make note of the Agent name.
2. Stop the Agent program.
3. Uninstall the GECS 2.0x Agent Software.
4. Once all GECS 2.0x programs are removed, you can install GECS 3.11 Agent software from the Global ECS
Windows CD ROM (Agent Subdirectory), from Agent diskettes or you can download the Agent software from
our web site. (See the GECS Agents chapter of the GECS manual for instructions on Agent Installation).
Upgrading Clients from GECS 2.0 or Later
1. Go to a Windows computer where GECS 2.0x has been installed. This computer must have a TCP/IP protocol
stack loaded. Login as Administrator or an administrator equivalent user.
2. Stop any GECS 2.0x programs.
3. Uninstall the GECS 2.0x software.
4. See the instructions for Configuring GECS Client Computers section of this chapter to install new GECS 3.11
clients.
2-22
Getting Started
Updating your GECS License Number
Your GECS license number can be updated after the programs are installed. You will receive a new license number
whenever your license is changed. Changing an evaluation license to a full license, upgrading to Unix operating
systems or changing the maximum number of Agents that are allowed to run at one time will require that you receive
a new license number. When you receive a new license number, it must be installed in order to become effective.
You will find your license number on the label attached to the printed license agreement.
When updating, you should stop all of your GECS components and exit all client and utility programs. From the
DBMS machine, open the Workstation Setup program, enter the new license number including the dash in the
license number field, then click on the Configure button. To verify your update, start the Administrator Client
program, open one of the modules, then click on the Help pull down menu and select Help About. Your new license
information should be displayed in the About box.
Read Me File
The READ.ME file contains late breaking news for each new GECS version which may not be included in this
manual.
2-23
Getting Started
2-24
User Guide
User Guide
3-1
User Guide
3-2
User Guide
GECS System Overview
The Global Event Control Server® (GECS) provides a framework where jobs are set up and run in a controlled
fashion. GECS DBMS, Controller, Web Manager and Windows Client software must run on a Windows machine.
Browser based Clients can be run from most any computer running a browser. GECS Agent software is available
for Windows, NetWare NLMs, SCO UnixWare, Linux, HP-UX, Solaris, AIX, Tru64 Unix and SGI IRIX. A single
operating system or a combination of operating systems can be used.
GECS is made up of a series of software programs and data files. The software programs fall into five categories;
the Client programs, DBMS, Controller, Web Manager and the Agent programs. A typical system configuration is:
GECS can be run on a single PC or across a network using TCP/IP. The Client programs are typically run on desktop
workstations. The DBMS, Controller and Web Manager are run on a Windows NT 4 or higher workstation or server
machine. The Agent programs are run on the machines where the jobs are run. The Client programs are stored on a
shared drive of a file server, usually on the DBMS/Web Manager/Controller machine, that all the client
workstations can access.
The GECS Workstation Setup “Express” installation option automatically installs every GECS component onto
one computer. This is the recommended setup for GECS evaluators or first time GECS users.
3-3
User Guide
Overview of Terminology
To fully understand the Global Event Control Server® there are several terms that need to be explained.
Client Programs
There are two types of Client programs. There are windows and browser based Client programs. These programs
yield a user friendly interface to access GECS data files.
The windows based client program is the GECS Administrator. It can be installed or configured using the GECS
Workstation Setup program. Once installed, it will appears as an icon in a Global ECS folder on your Windows
desktop.
The browser based Client programs do not require configuration or installation. While the GECS Web Manager
program is running, the browser based web clients can be used from most any computer running a browser.
DBMS Program and Data Files
The client and Controller programs access the GECS data files via the DBMS. The DBMS program
(GECSDBMS.EXE) can be run as a service or on the desktop and is designed to run continuously. The DBMS is
usually run on the same machine as the Controller and Web Manager where the data files are stored. The data
contained in these files is the heart of GECS. You can easily identify data files because they have .DAT and .IDX
extensions. For example: JOBS.DAT, JOBS.IDX, USERS.DAT, USERS.IDX, etc. This data can be queried for
reporting or accessed with third party programs using ODBC drivers supplied with the GECS SDK, which can be
purchased separately.
GECS Controller Program
A Windows Workstation or file server can be used to run the GECS Controller program (GECSPROC.EXE). The
Controller can be run as a service or on the desktop and is designed to run continuously. The Controller will
dispatch jobs users submit to available Agents. The Controller is usually run on the same machine as the DBMS
and Web Manager.
Agent Programs
A computer running a copy of the GECS Agent software will actually run the jobs users submit. The Agent
program (GECSAGNT) can be run as a service or on the desktop on Windows or in a terminal session or as a
daemon on Unix versions. Agents must be running to launch jobs and answer job status requests from GECS.
Web Manager Program
The Web Manager program, by default, runs on the DBMS/Controller computer. It allows users to access the
GECS system using a browser from any computer without having to install or configure the sometimes complex
3-4
User Guide
GECS windows Client programs. The Web Manager interfaces with the DBMS allowing users access via an http
site.
GECS Users
Any valid network user (if using networking features) who has been set up in the GECS User data file is a GECS
User. GECS users must be given rights to run the various components of the GECS system by being assigned a
GECS Security Profile. Only GECS users are allowed to schedule jobs and they are the only users allowed to run the
Client programs. If a person has not been added to the User file, they will be unable to use GECS. If you are using
GECS on a stand-alone PC (using “No” networking), GECS users will be prompted for their user name and
password each time they start a GECS client program.
GECS Security Profiles
GECS Security Profiles are used to assign security profiles to GECS Users. By default an ADMIN and
OPERATOR Security Profiles are defined. Once a Security Profile has been created and defined, Users can be
assigned to the specified Security Profile thus giving them access to the specified GECS Client program
components. You can create as many GECS Security Profiles as necessary.
Jobs
The easiest way to think about a job is as a command line. GECS executes these command lines. Jobs can be
executable programs, batch files or scripts. Although you can build a single job that runs a batch file that runs
multiple executables, GECS will be better able to control your job flow if you create separate jobs for each
executable with dependencies that sequence the jobs. When jobs are created, criteria such as the time to run and the
name of the user that is submitting the job are combined with the command line to create a scheduled job. Jobs can
be added in many ways in GECS. Client programs offer the most direct way of adding jobs to the GECS data files.
GECS Batches can be used to create job streams. Jobs can also be added by using text files called WRK files. GECS
will read these temporary files and convert them into real scheduled jobs. An Agent will then launch the job or jobs.
Batches and Batch Jobs
GECS Batches allow you to define a batch of processes in an off-line environment and schedule or remove them as a
whole unit. When a Batch is scheduled, job records are created and added to the GECS jobs file. When the Batch is
removed, these job records are deleted from the GECS jobs file. When Batches are defined, one Batch job is defined
for each scheduled job that should be created.
Batch Variables
Special Batch variables can be defined for each Batch. These variables are used in defining the Batch and Batch
jobs. At the time the Batch is scheduled, the user is prompted for the values that the variables should be changed to.
This allows Batches to be defined that are regularly scheduled, but with dates, times, accounting period numbers or
other information that changes.
3-5
User Guide
WRK Files
WRK (pronounced ‘work’) files are created and used as one method of scheduling jobs. They are simple ASCII text
files. GECS can be configured to look for these files and convert them to scheduled jobs. GECS can add jobs based
on information in WRK files. You can create your own programs to schedule jobs to GECS by using WRK files.
The definition of WRK files is included later in this manual.
Completed Jobs
GECS keeps a record of the jobs run by your Agents. This record is referred to as the job history or job statistics.
GECS can update the job records to reflect when an Agent executes a job. The completed job information displays
when a job started, finished, what Agent ran it and other information about the job. When GECS is configured to
automatically trim completed jobs, you can enable a GECS.INI setting to keep failed completed jobs on file.
Events
Events are things which may require special notice. Each GECS Event is numbered and contains parameters (detail
definitions) to allow for special notifications. GECS keeps track of special Events such as when a batch is scheduled
or removed, when a job is dispatched ignoring dependencies, when a job is skipped and rescheduled or when a WRK
file is converted into a real job, Controller started, Controller stopped, GECS tried to convert an invalid WRK file to
a real job, and many more. Given the unattended nature of GECS, the logging mechanism is designed to keep GECS
running whenever possible, even after encountering Events. Some Events represents things to which you should
pay attention. Besides recording the Event, GECS they can be sent as notifications including: email, SNMP,
network message, Windows event logging, job activation, audible wav file, and color highlighting in the
administrator Events lists.
Vacation Periods
Vacation periods represent periods of time when you don’t want jobs to run. Vacation periods are based on job
classes. Each job can be assigned a class when it is scheduled. If you don’t want a particular class of job to run on
Sundays for example, you could create a Vacation period for Sunday and have the vacation period repeat once a
week. In this case, jobs of the class specified won’t run on Sunday even if they are scheduled to run. When you
create the vacation period, you can specify what should happen when a job encounters a conflict with the vacation
period. You can have the conflicting jobs wait until the vacation period ends or you can have the jobs react as if they
had run, even though they hadn’t. In this case, conflicting jobs will reschedule themselves just as if they had run.
Vacation periods define times when jobs can’t run, even if scheduled.
Calendars
GECS allows you to define a virtually unlimited number of calendars. Each calendar is named. Each calendar
actually contains two calendars, one listing non-business days and the other listing defined months. Each job can be
assigned a calendar to be used in scheduling.
3-6
User Guide
Business Days & Non-Business Days
GECS allows you to define the days that are Business Days and those that are Non-Business Days. Once these are
defined, you can schedule jobs to run based on the calendar you’ve established. For example, you can schedule a job
to run on the last business day of each week, the 2nd to the last business day of each month or the first non-business
day of each week. Business Days and Non-Business Days are different from Vacation Periods, even though the two
can be used to accomplish the same thing. Vacation periods determine when jobs shouldn’t run. Business Days and
Non-Business Days determine how jobs are rescheduled after they run.
User Defined Months
Many businesses operate on a calendar that is different from the traditional calendar. For example, retail operations
frequently use a calendar where each month is 4 weeks long and there are 13 months in each year. The User Defined
Months feature lets you establish a calendar of your own for use in job scheduling. For example, you might want a
job to run on the 5th day of each retail month. To define your User Defined Months, identify the date that is the first
day of each month. The months can vary in length. Each month continues up to the date that is identified as the next
starting date.
Resources
Resources represent hardware, software or other things (hardware or software, physical or logical) that are needed
by jobs. Resources are limited in quantity either because only certain GECS Agents have them or there is a limited
quantity of them on the system. Consequently, resources are either assigned to specific Agents or they are system
wide resources. Resources are best described by using the following examples:
Example 1 - Agent Resource:
Only the GECS Agent named AGENTNT has a CD ROM player and you don’t want more than one job to
access it at a time. You would create a resource named CDROM assigned to AGENTNT and indicate it is
allowed a maximum of 1 job. You would then setup the jobs that require the resource named CDROM.
Should you later add a CD ROM player to AGENTHP, you could simply add that resource to the system
with maximum jobs equal 1 and the jobs would then be able to run on either Agent, but never more than one
at a time on each Agent.
Example 2 - System Resource:
You don’t want your jobs to ever use more than 5 database server connections. You would create a system
resource named DBCON and indicate it is allowed a maximum of 5 simultaneous jobs. Since this is a system resource, it consequently wouldn’t have an Agent name associated with it. Your Controller would
then check to see if there were already 5 jobs using this resource before dispatching any job that require the
resource DBCON.
Work Sheets
Work sheets are used to graphically represent one or more job streams. The Studio program allows you to create,
change, delete and save work sheets.
3-7
User Guide
GECS Licensing
The GECS System requires a valid license number to operate. This license number will allow one GECS Controller
to run and a limited number of GECS Agents. For more information, review your license agreement or contact your
sales representative. This license number is important and you should make backup copies and store it in a safe, but
accessible place. GECS will not operate if a license number has not been installed.
Supported Operating Systems
The GECS Controller and Client programs are available for Windows NT/2000/XP/2003. The GECS Agent
software is available for Windows NT/2000/XP/2003, NetWare NLMs, SCO UnixWare, Linux, HP-UX, Solaris,
AIX, Tru64 Unix and SGI IRIX.
Windows Client Program Interface
The GECS Windows Client programs have a common and easy to use interface. Most functions can be performed in
several ways. You can use the pull down menus, toolbar buttons, field lookups and function keys, as well as access
on line application help.
Pull Down Menus
Pull down menus can be accessed by either clicking on the menu item with your mouse or by simultaneously
pressing the Alt key and the underlined letter of the menu item.
Toolbar Buttons
Most of the GECS Client programs contain various toolbar buttons. A small balloon help box will appear for each
button on the toolbar after the mouse has set on the button for several seconds.
Field Lookups
Some fields in the GECS Client programs contain lookup lists from which you can choose valid values. Lookup
fields are denoted by a lookup button. This button displays a small arrow. To display a lookup list press the lookup
button.
3-8
User Guide
Tabs
Many of the GECS Client programs contain tabs to allow you navigate through various screens. When you use your
mouse to click on a tab the screen associated with that tab will be displayed.
Function Keys
A list of available function keys can be found in the GECS on line application help file.
Application Help
On line application help is available for the GECS Client programs from the help pull down menu, by clicking on the
help toolbar button or by pressing the <F1> function key.
Printing Lists
Most lists in GECS can be printed by simply right clicking on the column header of the list and selecting print.
Record Count
You can get a record count of most lists in GECS by simply right clicking on the column header of the list.
Column Sort
You can sort ascending or descending Jobs, Events and Event Definitions lists by left clicking on the column header.
GECS System Setup
The Getting Started chapter of this manual provides instructions for setting up a simple GECS installation. More
complex set up information can be found in the Technical Reference or Task Automation chapters.
3-9
User Guide
GECS Users
After running Workstation Setup for the first time a GECS user is created and automatically given rights to all
modules in the GECS system. Additional people who wish to use GECS must be added and given security
authorization to the system. Use the Users and Security Profiles modules from the GECS Administrator program to
create users for your GECS system.
When using GECS with Microsoft, NetWare or LAN Manager networking, your GECS user names should be the
same as your network names. When you choose “No” networking from Workstation Setup, user names can be
anything you want. The Add Users utility can also be used to load users from a comma separated file. Information
regarding GECS utilities are described in the GECS Command Line Utilities section of this manual.
GECS DBMS
The GECS DBMS must be running before any GECS programs can be started. If you attempt to start programs
without first starting the GECS DBMS you may get the following errors: “(3)Timeout connecting to host ...” and
“Unable to communicate with the Database Server, this program will be closed”.
GECS Express installation forces the DBMS to be run as a service. When run as a service it is automatically started
when the computer is turned on.
GECS Web Manager
The GECS Web Manager must be running before users can access the GECS system using the browser based
programs. The GECS Workstation Setup program configures the Web Manager program. The GECS “Complete”
“Express” installation option automatically configures and starts the Web Manager program as a service.
GECS Controller
The Workstation Setup program allows you to automatically create your Controller record. Your Controller can be
updated using the GECS Client programs. The Controller program should be running continuously to dispatch jobs
to Agents.
GECS Express installation forces the Controller program to be run as a service. When run as a service it is
automatically started when the Controller computer is turned on.
GECS Agents
The GECS Administrator program allows you to create your GECS Agent records. To run multiple Agents, you
must define an Agent record for each computer that will be running the Agent software. Each Agent is identified
with a unique name, IP Address and port number. The Agent record contains fields that allow you to define the types
of jobs that can be run by the Agents, the number of jobs it can run simultaneously, hardware of that computer, and
many other characteristics of how the Agent should behave.
3-10
User Guide
Automating Tasks using GECS Jobs
The GECS Client programs offer the most direct way of adding jobs to the GECS data files. You can use the GECS
Windows Administrator program or browser based clients to create jobs. (See also WRK files). You must enter a
unique job name or number, information such as the command line for the job, how it should behave, what it
depends on, how it should repeat, required hardware and or software and the name of the Agent(s) or Agent group
where the job should run. Much of the information in the job screens are only needed for more complex
configurations. The default settings can usually be used.
GECS Naming & Numbering Schemes
Most of the Client programs in GECS allow you to assign names or numbers to the items you are adding. These
include things like job name, Agent name, user name or Batch names. Most of these selections allow you to use any
alphanumeric name you want. Vacation numbers are one of the few keys that must contain only numeric characters.
As you enter names and numbers, the Client programs will frequently turn lowercase letters to uppercase and they
will prevent you from including characters that aren’t allowed. GECS maintains most of its data in alphabetic order.
You can ‘next & prev’ through the records in alphabetic order. This is accomplished by having the number left
justified before it is stored. For example, Agents would appear in the following order:
1
10
1A
2
20
2A
APPLE
BAKER
CHARLIE
In situations like the vacation number, where only numeric characters are allowed, the records are stored in numeric
order so they would be sorted as:
1
2
10
20
Even though the job numbers are alphanumeric, they are sorted differently than the other alphanumeric fields. This
field would be sorted as:
1
2
10
20
1A
10A
2A
20A
APPLE
BAKER
CHARLIE
3-11
User Guide
The logic behind this sorting scheme is as follows:
a) If the numbers contain ONLY numeric characters they are sorted in numeric order. This is accomplished by storing the number right justified.
b) If the numbers contain ANY alphabetic characters they are sorted in alphabetic order. This is accomplished by storing the number left justified.
This allows you to use all numeric numbers and have them come out in numeric order or to use numbers that contain
alphabetic characters and have them sorted in alphabetic order. Keep in mind that this sequencing only applies to
the order the numbers appear in when you ‘next & prev’ through the data on screen or the order it appears on reports.
Another unique feature of job numbers and Batch job numbers is in how leading zeros are handled.
a) If the number is all numeric, leading zeros are removed.
b) If the number contains alphabetic characters, the leading zeros are left on the number.
For example:
Entered As
1
01
1A
01A
Stored As
1
1
1A
01A
Keep in mind that the numbers ‘1’ and ‘01’ are the same and ‘1A’ and ‘01A’ are not the same. You can always use
the lookup windows to find the record you want, whether you know the number or not. For best results, you should
decide to use numbers that are all numeric or to use numbers that all contain at least one alphabetic character.
GECS can automatically generate job numbers on the entry screens for new jobs or Batch job entries. GECS
determines the highest all numeric value on file, adds one to the number and uses that as the default job.
3-12
Task Automation
Task Automation
4-1
Task Automation
4-2
Task Automation
Automating Tasks
Tasks are entered into the GECS system as jobs. At minimal, a job must have a name, a command line
containing the task to automate and a next run date and time. Additionally, jobs can be defined to:
• run at predetermined dates and times using “next run date and time”
• run once, a fixed number of times or indefinitely using “job scheduling”
• type predefined keys to your Windows applications using “key stuffing”
• run in a specified sequence using “job dependencies”
• run based on other jobs’ success or failure using “operation on return code”
• run based on the occurrence of Events using “Event Dependencies”
• run only during specified time periods using “valid times”
• run based on the presence or absence of single or multiple files using “trigger files”
• run based on file contents changing or file size changing using “command line utilities”
• run based on the availability of predefined resources using “Agent or system resources”
• generate Events on job success or job failure
• run special command files before and after “NT Console” jobs using “precmd.txt and postcmd.txt files”
• retry on failure using “retry on return code and times to retry”
• terminate a job if it takes too long to run using “maximum minutes”
• notify users of job completion or job failure using “Events”, and much more.
Create a new job by first defining a job name or number for your task. You can then specify the task by populating
the command line field. This chapter describes these and many other job parameters that can be used with GECS.
Job Creation
Once users are defined in the GECS system, there are several ways they can create and add jobs to be run on
defined Agents. GECS users can add jobs using:
1) Browser Based GECS Client Programs (Jobs or Batches/Batch Jobs)
2) Windows Based GECS Administrator Client Program (Jobs, Batches/Batch Jobs or Studio Worksheets)
3) WRK Files (ASCII text files)
4) Customized Job Entry Programs (created using the GECS SDK)
The browser based Client programs only require an internet browser. There is no need to have any GECS programs
installed or configured. Users can simply access the GECS system via http accessing the Web Manager program.
(See the Web Manager chapter). To use the Windows based Administrator client program, users must install or
configure it to run on their computer. ASCII text files called WRK files can be emailed to GECS or placed in a
specified directory where GECS is configured to check. When using wrk files, no GECS programs are required.
The WRK files use number or letter equivalent job parameters. WRK files can be created using most any text editor.
4-3
Task Automation
(See the end of this chapter). Customized job entry programs can be created by using the GECS SDK. The GECS
SDK must be installed and job entry programs must be written. (Contact GECS Sales for details).
Batch Jobs
When using GECS Batches it is very important to fully understand the concept of batches, batch jobs and scheduled
jobs. Batches can be created to define a batch of related processes in an off-line environment. Batches are like
templates. Each Batch can contain one or more Batch jobs. Batch jobs do not become real jobs until they are
scheduled. Once a Batch is scheduled then real jobs are created using the information in the Batch jobs. The result is
new job records that the GECS system will launch and the remaining untouched Batch and Batch job templates.
Therefore, you should create a Batch using the Batches folder. You add related Batch job records to the Batch.
When you are finished and ready to run these Batch jobs, you Schedule the Batch which creates real jobs available to
be run by your Agents.
Studio Worksheets
Studio Worksheets can be used to create, edit or delete job records. Worksheets can be automatically created during
the process of Scheduling a Batch. They can be viewed as a graphical display of your job streams showing lines and
arrows depicting job dependencies.
Worksheets do not display real time information about your jobs.
Job Views
GECS Job records can be displayed in customizable lists. You can use the View Properties to update the filtering
that can be applied to your view of jobs. You can double click on a job from the list to view the Job Detail screens.
Creating your own views can help you organize your jobs into manageable entities. Views give you flexibly by
allowing filtering on the items displayed in the lists. For more information on Job Views, see the Client Programs
chapter of this manual.
4-4
Task Automation
Job Name
Each GECS job must be assigned a unique name or number which may consist of three parts:
BATCHNAME.JOBNAME-Instance
The format is:
XXXXXXXXXXXXXXXXXXXX.XXXXXXXXXX-nnnnnnnnnn
The first section is optional and allows for an alphanumeric Batch name up to 20 characters in length. Batch names
are forced to uppercase and only letters or numbers are allowed. This section is used when jobs are created using the
Batches option.
The second section is required and allows for an alphanumeric job name up to 10 characters (valid characters are 0-9
and A-Z). When using Batches to create jobs, this section is derived from the Batch Job name.
The third section allows for a numeric instance of the job which can be up to 10 digits. This section is used when jobs
are scheduled to repeat.
You should try to devise a naming or numbering scheme that best suits your company’s needs. Examples of job
names and numbers include:
1
TESTJOB1
BATCH1.BKUP1
BATCH2.UPDATE-1
BATCH2.UPDATE-2
Command Line
Every GECS job must have a command line defined. The command line contains the actual task you wish to
automate. In general, any task that can be run by hand at the machine where a GECS Agent is running can be
automated by GECS.
With the Windows Agent, your command line can be an executable program, macro, batch file, etc. It can also
include caption text, GECS substitution variables, command line parameters and environment variables.
With the NetWare NLM Agent, your command line can be any System Console command such as ‘MODULES’ or
‘LOAD XYZ.NLM’.
With the Linux/Unix Agents, your command line must be the name of the executable program to be run such as ‘cp’
or ‘ls’. To run shell scripts, enter the shell name and script for the command line such as ‘sh xyz.sh’.
Remember that any paths specified in the command line field must be relative to the Agent.
The Windows Client Command Line field allows you to “Edit” a file or “Browse” for a command line by clicking on
the command line lookup button. This feature is only relevant to Windows commands.
Limits on the length of the GECS command line is determined in part by the operating system that the GECS Agents
are running on and in part by the “Command Line Type” defined for the job. Therefore, the number of characters
allowed on the command line varies. Most command lines can hold up to 120 characters.
4-5
Task Automation
Executable Programs and Shell Scripts
To automate running a program or shell script, enter the fully qualified path and program or shell script name as
follows:
C:\APPS\NOTEPAD.EXE
SH /APPS/Nightly.sh
Shell scripts or executables must be preceded by ‘SH’ or other shell name.
Long File Names on Windows Agents
Jobs run on Windows Agents that have command lines with long file names should be enclosed in double quotes.
For example:
“C:\Program File\Microsoft Office\Excel.exe” f:\excel\test.xls
Batch and Command Files
Use appropriate file extensions when applicable. For example, when automating batch files use .bat or .cmd, such
as:
C:\UTILS\TEST1.BAT
C:\UTILS\TEST1.CMD
You can specify the command interpreter used to run your .bat or .cmd job using the GECS job “Command Line
Type” field. You can choose a “Command Line Type” of DOS for the COMMAND.COM interpreter or choose
Windows NT/2000/XP/2003 or NT Console for the CMD.EXE interpreter.
Input / Output Redirection - Piping
On Unix Agents, any I/O redirection or piping must be done within a shell script. It should not be put directly on the
command line.
Caption Text
When a Windows program you need to automate requires you to type keys, GECS will automate the typing using
“Keystroke Stuffing”. See the Keystroke(s) fields. In addition to that, GECS can stuff keys to application windows
based on their “caption text” (the text that appears in the title bar of the window). When entering the command line
for the job, put the desired caption text between curly braces ({}) after the command such as:
C:\Excel\Excel.exe {Microsoft Excel}
This will force the keys to go to this window. Note that the entire caption need not be included. GECS will attempt
to match just as much of the caption text as is specified in the curly braces. The caption text must be entered exactly
as displayed. The comparison IS case sensitive (’A’ does not equal ‘a’). The caption text is circled on the window
below.
4-6
Task Automation
An additional side of this feature is that you can specify just the window caption as the command line:
{Microsoft Excel}
GECS will not attempt to start any new program. It will simply look for an already running program with the
specified caption text and will send the specified keys to that application. When all the keys have been sent to the
task, the job is logged as complete with a return code of zero.
Substitution Variables
Command lines can contain special GECS substitution variables. A complete list of these variables can be found
later in this chapter and in the on line application help. These variables can be entered on the command line as
follows:
TEST2.BAT @DATEL @TIME @USER
Substitution on these variables occurs just before the job is launched. In the example above @DATEL will be
substituted for the current date, @TIME will be substituted for the current system time and @USER will be
substituted for the name of the user that submitted the job.
Command Line Parameters
Command line parameters can also be included in the Command Line field. They should be entered just as they
would appear when you run the task by hand. For example:
dir /od
The example above would launch the directory command and display the list ordered by date.
Environment Variables
Optionally, you can substitute environment variables on your command line. The usage is %ENV%, where ENV is
the environment variable name.
%SystemRoot%\system32\progname.exe
Where the variable %SystemRoot% may be substituted with a predefined value such as c:\winnt.
These environment variables are the Agent environmental variables before “logging in as submitting user” on all
GECS platforms.
Command Line Type
The GECS job parameter called the “Command Line Type” determines the way your “Command Lines” get
executed by your Agents. The different platforms supported by GECS can run different types of programs as jobs.
Your options are:
- DOS
- Windows
- OS/2
- Windows NT/2000/XP/2003
4-7
Task Automation
- NLM
- Windows 95/98/ME
- NT Console
- UnixWare
- Linux
- AIX
- HPUX
- Solaris
- OS/400
- Tru64 Unix
- IRIX
Windows Agents will run Windows NT/2000/XP/2003, Windows 95/98/ME, Windows, DOS, OS/2 and NT
Console command line types. NetWare, SCO Unix Ware, Linux, HP-UX, Solaris, AIX, OS/400, Tru64 and IRIX
Unix Agents will run their own command line type.
If you choose a command line type that is unsuitable for your command line you may get several errors when your
Agent executes your job. For example:
Command Line Type: Windows
Command Line: DIR
You may get the following error:
Failed to launch task dir, WinExec returned 2
Or, your job might run returning an inaccurate return code. This is because DIR is not a valid Windows command.
To avoid these errors, always ensure your command line type is compatible with the command line you are trying to
run.
A more appropriate solution to the above example would be:
Command Line Type: NT Console
Command Line: DIR
Windows Agent Precmd.txt & Postcmd.txt
Windows Agents have the capability of defining a list of commands to be executed before and after every DOS,
OS/2 and NT Console “command line type” job. These commands will be executed for EVERY job defined with a
“command line type” of DOS, OS/2 or NT Console. The Windows Agent software looks for two ASCII text files
PRECMD.TXT and POSTCMD.TXT in the Agent’s GECS directory. If these files exist, their contents will be
executed similar to the way a batch file is executed. The lines in the PRECMD.TXT file are executed just before the
job’s command line and the lines in the POSTCMD.TXT file are executed after the job’s command line. When
these files don’t exist, the jobs execute just as they always have. Each line in PRECMD.TXT and POSTCMD.TXT
is limited to 128 characters in length for DOS, 255 for NT Console command line type jobs.
Windows Agent - CMD.EXE vs. COMMAND.COM
When using Windows Agents, your “Command Line Type” also determines the type of interpreter that your
Windows Agent opens to run certain jobs.
If you choose a command line type of “Windows NT/2000/XP/2003” or “NT Console”, your Agent will launch a
copy of 32-bit CMD.EXE to run your job. If you choose a command line type of “DOS”, your Agent will launch a
copy of 16-bit COMMAND.COM to run your job.
4-8
Task Automation
Determining if a Program is for Windows NT/2000/XP/2003,
Windows 95/98/ME or Windows 3.1
One method is to create an icon for the program under Windows NT/2000/XP/2003. After the program name is
entered, notice the questions about running the program in a separate address space. If this question is “grayed out”,
the program is a Windows NT/2000/XP/2003 or Windows 95/98/ME program. If you can set this question, it’s a
Windows 3.1 program.
Yet another method is to select the Start or File/Run option under Windows NT/2000/XP/2003 and enter the
program name, noticing the questions about running the program in its own address space. If this question is
“grayed out”, the program is a Windows NT/2000/XP/2003 or Windows 95/98/ME program. If you can set this
question, it’s a Windows 3.1 program.
It’s important to note that even some of the programs that come with Windows NT/2000/XP/2003 are actually
Windows 3.1 programs.
Capture Output
The “Capture output” field is used to enable standard output to be created and displayed on the Completed job
record’s Output tab. Agents capture standard output. When Jobs complete, the DBMS requests the output from the
Agents then saves the file to the GECS data directory. This feature only works when your Agents are configured to
run on the desktop. The Agents cannot be run as a service or daemon when using the Capture Output feature. The
output files are named BATCHNAME.JOBNAME-INSTANCE.OUT.
Next Run Time
The “Next Run Time” field is used to set the date and time your job should run next. Every GECS job must have a
next run time defined. If this time is in the past, the job should run immediately.
Jobs containing dependencies or resource requirements may not always run on time according to their next run time.
Sometimes, jobs are forced to wait. When a job’s next run time is in the past the job is considered to be in a
“backlogged” state. This means the job is scheduled to run but for some reason it can not. A list of reasons why a job
cannot run can be viewed. Reasons why a job cannot run may include:
• predecessor job had an invalid return code - the job this job depends on failed
• unable to find any required file - a required trigger file for this job is not yet available
• predecessor job hasn’t run - the job this job depends on is late and has not started yet
• event dependency - a required Event has not yet occurred
• resource unavailable - a required resource for this job is not yet available
Jobs setup to run in a specified sequence using job dependencies may all contain the same next run time. However,
as long as they have defined job dependencies they will always run in order.
A new job with a new next run time is automatically created for those setup to repeat. Repeating jobs are created
with new instance numbers.
4-9
Task Automation
Batch jobs use either the next run time specified in each Batch job screen or use the next run time specified for the
Batch as a whole on the Scheduling Options tab. A Batch job’s next run time gets overridden if a time is entered for
the Batch as a whole.
Job Status
The “Job Status” field displays the status of your job. Status options are:
• Pending
• Started
• On Hold
• Complete
Jobs ready to be run should be marked 'Pending'. While they are being executed, they are marked as 'Started'. GECS
users with User record security set to ‘Approval Required’, must save jobs with a status of ‘On Hold’. These jobs
must be manually approved by a user with authority ‘OK to Submit Jobs’. When your Controller is set up not to
delete completed jobs, they are marked 'Completed'. Only jobs marked 'Pending' will be executed.
WRK files can be used to launch a completed job by changing a job’s status from complete to pending. See the
WRK files section of this chapter for details.
Job Title
The “Job Title” field can be used to enter a title or short description for your job. The title entered here appears in
various GECS screens. Job titles are optional and can be up to 30 characters in length.
Start In Directory
Use the “Start In Directory” field if you need to change to a drive and directory other than where your program file is
located. Agents will change to this specified drive and directory before executing your jobs’ command line. Often
this directory will contain DLL files which may be required by a program you are automating from your command
line.
Environment variables and special GECS substitution variables can be used in the start in directory field. See the
command line field environment variable section for details on syntax.
From a Windows machine, you can display the start in directory for GECS programs by right clicking on the
shortcut icon, clicking properties then clicking on the shortcut tab.
GECS checks the start in directory when a jobs requires “minimum disk space” to run.
4-10
Task Automation
Enable Command Line Substitution
GECS can 'alter' job command lines, keystroke(s) fields, trigger files and start in directory before they are executed
if you include special GECS “Substitution Variables” in them.
If you want GECS to check for substitution variables, check mark (set to yes) the “Enable Command Line
Substitution” field. Enabling this field will have no impact on command lines or other areas that do not contain any
substitution variables.
Do not check mark (set to no) this field if your command line or other areas contain characters that match GECS
substitution variables though you do not want them substituted with special GECS substitution values.
Substitution Variables in Jobs
The Global Event Control Server® can manipulate job command lines, keystroke(s) fields, trigger files and start in
directory before jobs are executed using special GECS substitution variables. This is useful for passing parameters
to the programs being run. For example, if you want to execute a program called SAMPLE.EXE and pass it the
name of the user that submitted the job, you could enter the command:
SAMPLE.EXE USER=@USER
The @USER will be changed/substituted before the command is executed to the name of the user that submitted the
job. For example, if the job was submitted by a GECS user called FRED, the command would be changed to:
SAMPLE.EXE USER=FRED
Special GECS Substitution Variables:
Variable
Format
Description
@AGENT
text
Agent name.
@ANAME
text
Agent’s user name the Agent is running as.
@BATCH
text
Batch name.
@BEGCDEFMO
mm/dd/yy
Beginning date of current defined month.
@BEGCDEFMOL
mm/dd/yyyy
Beginning date of current defined month.
@BEGLMO
mm/dd/yy
The beginning date of the last month.
@BEGLMOL
mm/dd/yyyy
The beginning date of the last month.
@BEGMO
mm/dd/yy
The beginning date of the current month.
@BEGMOL
mm/dd/yyyy
The beginning date of the current month.
@BEGPDEFMO
mm/dd/yy
Beginning date of previous defined month.
@BEGPDEFMOL
mm/dd/yyyy
Beginning date of previous defined month.
@BEGNMO
mm/dd/yy
The beginning date of the next month.
@BEGNMOL
mm/dd/yyyy
The beginning date of the next month.
4-11
Task Automation
@BEGNDEFMO
mm/dd/yy
Beginning date of next defined month.
@BEGNDEFMOL
mm/dd/yyyy
Beginning date of next defined month.
@CMDLINE
text
The command line from the job record.
@DA
dd
Two digit day.
@DATE
mm/dd/yy
The current system date.
@DATEL
mm/dd/yyyy
Current date formatted as mm/dd/yyyy.
@DAY
dd
Today’s day of the month.
@ENDCDEFMO
mm/dd/yy
Ending date of current defined month.
@ENDCDEFMOL
mm/dd/yyyy
Ending date of current defined month.
@ENDLMO
mm/dd/yy
The ending date of the last month.
@ENDLMOL
mm/dd/yyyy
The ending date of the last month.
@ENDMO
mm/dd/yy
The ending date of the current month.
@ENDMOL
mm/dd/yyyy
The ending date of the current month.
@ENDNDEFMO
mm/dd/yy
Ending date of next defined month.
@ENDNDEFMOL
mm/dd/yyyy
Ending date of next defined month.
@ENDNMO
mm/dd/yy
The ending date of the next month.
@ENDNMOL
mm/dd/yyyy
The ending date of the next month.
@ENDPDEFMO
mm/dd/yy
Ending date of previous defined month.
@ENDPDEFMOL
mm/dd/yyyy
Ending date of previous defined month.
@ESTMINUTES
n
Estimated minutes.
@FILE
text
The name of the file that was found for jobs that depend
on the existence of a file. For jobs that depend on
multiple files, this variable will be the name of one of the
files found.
@HR
nn
Two digit hour in 24 hour format.
@JOBCOM
text
The job comments from the job record.
@JOBNUM
text
The job number from the job record.
@JOBTITLE
text
The job’s title field.
@LASTMO
mm
Last month’s month.
@MAXMIN
nn
Job’s maximum run time minutes.
@MI
nn
Two digit minute.
@MO
mm
Two digit month.
@MONTH
mm
Today’s month.
@MTIME
hh:mm:ss
Current time formatted as hh:mm:ss in 24 hour (military)
format.
@NEXTDAY
dd
Tomorrow’s day of the month.
@NEXTFRI
mm/dd/yy
Next Friday’s date.
@NEXTFRIL
mm/dd/yyyy
Next Friday’s date.
@NEXTMO
mm
Next month’s month.
4-12
Task Automation
@NEXTMON
mm/dd/yy
Next Monday’s date.
@NEXTMONL
mm/dd/yyyy
Next Monday’s date.
@NEXTSAT
mm/dd/yy
Next Saturday’s date.
@NEXTSATL
mm/dd/yyyy
Next Saturday’s date.
@NEXTSUN
mm/dd/yy
Next Sunday’s date.
@NEXTSUNL
mm/dd/yyyy
Next Sunday’s date.
@NEXTTHU
mm/dd/yy
Next Thursday’s date.
@NEXTTHUL
mm/dd/yyyy
Next Thursday’s date.
@NEXTTUE
mm/dd/yy
Next Tuesday’s date.
@NEXTTUEL
mm/dd/yyyy
Next Tuesday’s date.
@NEXTWED
mm/dd/yy
Next Wednesday’s date.
@NEXTWEDL
mm/dd/yyyy
Next Wednesday’s date.
@NOWDATE
mm/dd/yy
Current system date.
@NOWDATEL
mm/dd/yyyy
Current system date.
@PATH
text
The subdirectory to change to from the Start In Directory.
@PREVDAY
dd
Yesterday’s day of the month.
@PREVFRI
mm/dd/yy
The previous Friday’s date.
@PREVFRIL
mm/dd/yyyy
The previous Friday’s date.
@PREVMO
mm
The previous month’s month.
@PREVMON
mm/dd/yy
The previous Monday’s date.
@PREVMONL
mm/dd/yyyy
The previous Monday’s date.
@PREVSAT
mm/dd/yy
The previous Saturday’s date.
@PREVSATL
mm/dd/yyyy
The previous Saturday’s date.
@PREVSUN
mm/dd/yy
The previous Sunday’s date.
@PREVSUNL
mm/dd/yyyy
The previous Sunday’s date.
@PREVTHU
mm/dd/yy
The previous Thursday’s date.
@PREVTHUL
mm/dd/yyyy
The previous Thursday’s date.
@PREVTUE
mm/dd/yy
The previous Tuesday’s date.
@PREVTUEL
mm/dd/yyyy
The previous Tuesday’s date.
@PREVWED
mm/dd/yy
The previous Wednesday’s date.
@PREVWEDL
mm/dd/yyyy
The previous Wednesday’s date.
@PRIOR
nn
Job’s priority.
@SCHBEGLMO
mm/dd/yy
Beginning date of the month before the month the job is
scheduled in.
@SCHBEGLMOL
mm/dd/yyyy
Beginning date of the month before the month the job is
scheduled in.
@SCHBEGMO
mm/dd/yy
Beginning date of the month the job is scheduled in.
@SCHBEGMOL
mm/dd/yyyy
Beginning date of the month the job is scheduled in.
4-13
Task Automation
@SCHBEGNMO
mm/dd/yy
Beginning date of the month after the month the job is
scheduled in.
@SCHBEGNMOL
mm/dd/yyyy
Beginning date of the month after the month the job is
scheduled in.
@SCHDATE
mm/dd/yy
Job’s scheduled date.
@SCHDATEL
mm/dd/yyyy
Job’s scheduled date.
@SCHDAY
dd
Job’s scheduled day.
@SCHENDLMO
mm/dd/yy
Ending date of the month before the month the job is
scheduled in.
@SCHENDLMOL
mm/dd/yyyy
Ending date of the month before the month the job is
scheduled in.
@SCHENDMO
mm/dd/yy
Ending date of the month the job is scheduled in.
@SCHENDMOL
mm/dd/yyyy
Ending date of the month the job is scheduled in.
@SCHENDNMO
mm/dd/yy
Ending date of the month after the month the job is
scheduled in.
@SCHENDNMOL
mm/dd/yyyy
Ending date of the month after the month the job is
scheduled in.
@SCHMONTH
mm
Job’s scheduled date month.
@SCHNBDD
dd
The next business day’s day relative to the job’s
scheduled time.
@SCHNBDM
mm
The next business day’s month relative to the job’s
scheduled time.
@SCHNBDY
yy
The next business day’s year relative to the job’s
scheduled time.
@SCHNBDYL
yyyy
The next business day’s year relative to the job’s
scheduled time.
@SCHPBDD
dd
The previous business day’s day relative to the job’s
scheduled time.
@SCHPBDM
mm
The previous business day’s month relative to the job’s
scheduled time.
@SCHPBDY
yy
The previous business day’s year relative to the job’s
scheduled time.
@SCHPBDYL
yyyy
The previous business day’s year relative to the job’s
scheduled time.
@SCHPDD
dd
The previous day’s day relative to the job’s scheduled
time.
@SCHPDM
mm
The previous day’s month relative to the job’s scheduled
time.
@SCHPDY
yy
The previous day’s year relative to the job’s scheduled
time.
@SCHPDYL
yyyy
The previous day’s year relative to the job’s scheduled
time.
@SCHTIME
hh:mm:ss
Job’s scheduled time in 24 hr format (military time).
@SCHYEAR
yy
Job’s scheduled date two digit year.
4-14
Task Automation
@SCHYEARL
yyyy
Job’s scheduled date four digit year.
@SE
nn
Two digit second.
@SERVER
text
Same as @AGENT (Depricated).
@SNAME
text
The Controller’s network user name.
@SUPPLIES
text
Supplies required for this job from the Supplies field.
@TIME
hh:mm AM
The current system time.
@TOMO
mm/dd/yy
Tomorrow’s date.
@TOMOL
mm/dd/yyyy
Tomorrow’s date.
@USER
text
The user that submitted the job.
@YEAR
yy
Today’s year.
@YEARL
yyyy
Today’s year.
@YEST
mm/dd/yy
Yesterday’s date.
@YESTL
mm/dd/yyyy
Yesterday’s date.
@YR
yy
Two digit year.
Variables displayed in bold type can also be used to define environment variables in the GECS.INI file that
Windows Agents can set prior to job execution. @ANAME, Agent’s user name (text) is also included. See the
Technical Reference chapter of this manual for information on the GECS.INI file.
Remember that you must check mark the “Enable Command Line Substitution” field for your job if you want
GECS to check for and change substitution values for your job’s command line.
Substitution Variable Date Math
You can add and subtract days or months from any substitution variable that returns a date either in the format
‘mm/dd/yy’ or ‘mm/dd/yyyy’ by adding a plus or minus sign and a number to the end of the substitution variable.
For example:
@DATE+3
would be substituted as ‘08/04/97’ if the current system date was 08/01/97. Optionally, you can include the letter
‘D’ after the number to indicate days. To add or subtract months, include the letter ‘M’ after the number to indicate
months. For example:
@SCHDATEL+2M
would be substituted as ‘09/03/1997’ if the job’s scheduled date is 07/03/1997.
Note that if you are adding or subtracting months from a date near the end of a month, you may not get the expected
date due to months having variable numbers of days. For example, if you add 3 months to 01/31/97 you will end up
with 04/28/97 as follows:
01/31/97 plus 1 month = 02/28/97
02/28/97 plus 1 month = 03/28/97
03/28/97 plus 1 month = 04/28/97
Due to this situation, it is not recommended to add and subtract months from the last several days of the month. In
most cases other substitution variable combinations can be used to achieve the desired date.
Note that no space is allowed between the substitution variable and the plus or minus sign.
4-15
Task Automation
Substitution Variable Formatting
By default, substitution variables are formatted in standard U.S. format (i.e. mm/dd/yy or mm/dd/yyyy).
Default formatting:
@DATE
@DATEL
@TIME
@MTIME
12/31/02
12/31/2002
11:59:59 PM
23:59:59
Other formatting options are available by including the following entry in your local GECS.INI file.
[FORMAT]
DATES=n
where ‘n’ is a number 0 through 4 as follows:
‘n’
Format
Example
0
1
2
3
4
mm/dd/yyyy
dd-mm-yyyy
ddMMMyyyy
mm-dd-yyyy
dd/mm/yyyy
12/31/1999
31-12-1999
31DEC1999
12-31-1999
31/12/1999
Note that the substitution variable format is system wide and applies to all date substitution variables. If this section
is missing or invalid in a GECS.INI file, the system defaults to the ‘mm/dd/yyyy’ format.
You can use
[FORMAT]
DateFormatShort=string
DateFormatLong=string
TimeFormat=string
to override the default formatting or the formatting specified by ‘Date=n’. The ‘string’ is a formatting string that can
contain one or more of the following special fields:
%b
abbreviated month uppercase (JAN)
%c
abbreviated month capitalized (Jan)
%B
month (January)
%m
month (2 character)
%d
day (2 character)
%1
month (1 or 2 character)
%2
day (1 or 2 character)
%n
day with suffix (1st, 2nd)
%y
year (2 character)
%Y
year (4 character)
%A
day of week (Monday)
%a
day of week (Mon)
%H
hour in 24 hour format
%I
%M
hour in 12 hour format
minute
4-16
Task Automation
%S
second
%T
hundredths of seconds
%p
AM or PM
For example:
[FORMAT]
DateFormatShort=%m.%d.%y
DateFormatLong=%B %n, %Y
TimeFormat=%H:%M
would cause the following output:
@DATE
@DATEL
@TIME
12.31.02
December 31st, 2002
23:59
Note that ‘TimeFormat’ overrides the default formatting of @TIME and @SCHTIME, but not @MTIME.
@MTIME uses “%H:%M:%S” regardless of what ‘TimeFormat’ is set to.
Lastly, you can use formatting strings with the substitution variable to override any other formatting specified by
including the formatting string in parenthesis immediately after the substitution variable and before any date math.
For example:
@DATE(%m)
12
@DATEL(%1.%2.%y)
12.31.02
@TIME(%I o’clock)
11 o’clock
@DATE(%d)+1d
1
No spaces are allowed between the substitution variable and the parenthesis. Empty parenthesis will use the default
formatting.
Marking Jobs Complete Once Started
GECS can mark jobs complete when they actually complete or when they are started. This can be used when you
want to ‘load’ a program at the beginning of a job stream, execute one or more jobs that ‘use’ the loaded program and
then ‘unload’ the program. You would want to flag the job that ‘loads’ the program as “Mark Complete Once
Started”. This would allow the job(s) that ‘use’ the loaded program to be dependent on the ‘loading’ job. For
example, you might need to load a database server, print a report and then unload the database server program.
Job
Command Line
1
2
3
LOAD DB.NLM
REPORTER.EXE
UNLOAD DB.NLM
Depends On
(none)
1
2
Mark Complete Once Started
Yes
No
No
The example shows the loading and unloading of NLMs, but might involve the loading and unloading of programs
on Windows as well. The ‘unload’ portion might execute a command to unload the program or it might simply
‘stuff’ keys to the originally loaded program to cause it to quit using caption text.
When this feature is enabled, your Agent will execute your command line and GECS will immediately log a
successful, '0' return code.
4-17
Task Automation
Never Late
The “Never Late” flag is used for jobs that do not really relay on time as much as the presence or absence of such
things as Trigger Files, Job Dependencies or Events. Therefore, if you do not want your job to be considered late
when the job’s Next Run time is in the past, enable the Never Late field. This will keep any special notification on
late jobs from telling you about this particular job.
Show Activity
The “Show Activity” enables you to filter this job from displaying in your lists. When this field is set to no, this job
will not show up in your jobs listings.
Keep When Complete
The “Keep When Complete” field is used to override your Controller fields “Delete Jobs On Completion” and
“Days of Completed Jobs to Keep”. This flag allows you to delete most jobs on completion or that have completed
in the past, while having certain jobs remain on file after completion allowing them to be easily “activated”.
See also the delete only successful jobs on completion GECS.INI file entry. By setting this entry, [Controller]
DeleteOnlySuccessfulJobs=1, failed jobs will be left on file.
Execute
The “Execute” field is used to indicate how your job should be started. The different Agent operating systems are
only capable of particular job start modes.
• Normal - Use the applications default presentation.
• Hidden - Run the application invisible.
• Minimized - Display the application as an icon.
• Maximized - Display the application full screen.
Note that, when the “Execute” job parameter field is set to minimized or hidden, keystuffing will not operate.
Programs That Require User Input
The Global Event Control Server® is designed specifically to execute jobs without user input. When using in-house
developed programs, this shouldn’t present any problem. When using commercial applications or products
developed by others, this can present a problem. The GECS Windows Agent contains a “keyboard stuffing”
4-18
Task Automation
program that can feed most standard keystrokes to the programs being run as if you had typed them directly on the
keyboard.
In some unique situations, you might need more power or sophistication than is included in the keyboard stuffing
program included with GECS.
Sending Keystrokes to Programs
The job entry fields “Keystrokes 1-4” are used for key stuffing. Key stuffing is simply GECS feeding keystrokes to
programs being run just as if someone was typing them directly on the keyboard.
The Windows Agent will send keys to most Windows NT/2000/XP/2003, Windows 95/98/ME or Windows 3.1
programs. It will send keys to most DOS programs. Special commands can be stuffed to wait for a period of time or
to wait for a task to complete whether Windows NT/2000/XP/2003, Windows 95/98/ME, Windows 3.1 or DOS
programs are being run.
GECS for NetWare NLMs will send keys to most NLMs. Special commands can be stuffed to wait a period of time
before continuing the keys.
Unix Agents cannot send keys for key stuffing.
Windows Agent Keystroke Stuffing
GECS uses a special technique to send keys to DOS command line type jobs. It uses a completely different scheme
for sending keys to Windows command line type jobs which is substantially more powerful. Yet with certain
programs GECS is unable to determine which window in the program should receive the keys. The typical problem
is that temporary message boxes may get the keys intended for the main program window. The ‘W n’ key stuffing
command causes GECS to wait ‘n’ seconds before sending the next key to the Windows program. This may help
you get around the problem of keys going to the wrong window.
The ‘W n’ command can also help with the delays associated with printing. For example, if you know a report will
take about 2 minutes to print, you can put the delay of W 120 in the keys to allow the report to finish printing before
any other keys are sent to the program. Note that the ‘W n’ command can only be used with Windows command line
type jobs. If you are running a DOS command line type job, you should use the ‘@WT n’ command as described
under the DOS keystroke stuffing section.
You will note that at the end of the list of “stuffable” keys there are several that are only available to Windows
programs. These keys cannot be used by jobs automating DOS programs, when the command line type set to DOS,
even though, they are being run by a Windows Agent.
An additional feature of the Windows key stuffing mechanism is its ability to send keys to a window by specifying
its caption text. The ‘caption text’ is the text that appears on the title bar / on the top line of the window (in the
caption). Caption text is described later in this chapter.
DOS Keystroke Stuffing Programs
KSLOAD.COM is a TSR that is automatically loaded when keystrokes to execute are specified. The program
KS.EXE is then executed to actually “stuff” the keys. Your program is then run. After the program runs,
KSLOAD.COM is called again to unload the TSR from memory. The TSR is slightly larger than 1K and is only
loaded before jobs that specify keystrokes. DO NOT load KSLOAD.COM before starting the program.
4-19
Task Automation
Should the KS.EXE program encounter a problem, the job will stop and a return code of 255 will be recorded as the
job’s return code.
KS.EXE
KSLOAD.COM
There are two programs used for sending keys to DOS programs. These programs are used by your Windows Agent
to send keys to the DOS “command line type” jobs they run. KSLOAD is a small TSR (less than 3K in size) that is
loaded the first time it’s run and unloads the second time it’s run. The KS program actually sends the keys to the
programs. For example, you might create a batch file that contains the lines:
KSLOAD
KS ‘Hello World’
yourprog.exe
KSLOAD
The lines in this batch file would send keys to your program. These programs ‘hook’ the keyboard BIOS. They will
not work with programs that talk directly with the keyboard hardware. Though you can use these programs in your
own batch files, it is better to define the keys to be sent to your jobs using the Client program Keystrokes fields and
allow GECS to automatically call these programs to send keys to the programs in your jobs.
To test your keystroke stuffing, you can use the KSLOAD.COM and KS.EXE programs directly from a batch file
such as:
KSLOAD
KS ‘keys’ ENTER
yourprog
KSLOAD
The first line loads the TSR. The second line “stuffs” the keystrokes. The third line executes your program. Your
program will accept the “stuffed” keys as if you had typed them. The last line unloads the TSR. When KSLOAD is
executed, it loads only if it can’t find itself in memory. If it finds itself in memory, it unloads itself. No command
line options are required to specify loading or unloading.
By including the wait keyword, @WT n in the keys to be stuffed, the program can wait while reports or other
processing completes before sending the remaining keys. For example:
‘112233’ ENTER @WT 300 ENTER ESC F10
would send several keys, wait 5 minutes (300 seconds) and then send the remaining keys. Note that the @WT n
command must be outside any quotation marks to be effective.
Details of Keyboard Stuffing
The job entry screen contains four fields where “Keystrokes” to be executed are entered. Keystrokes can be entered
4 ways:
1) Normal typeable characters are entered in single quotes like:
‘abc’
You can include a single quote in a quoted string as long as it is the first character of the string. For example, to stuff
the characters:
4-20
Task Automation
I haven’t seen it.
you would enter:
‘I haven’ ‘’t seen it.’
The phrase is cut into two pieces. The first single quoted string is ‘I haven’ and there is nothing special about it. The
second string is ‘‘t seen it’. Note that the double single quotes at the beginning of the string is interpreted as a single
quote.
2) The special, non-typeable keystrokes such as the F10, Enter, Alt+F or Esc keys are entered using special words
outside the single quoted strings like:
‘abc’ENTER F10 A_F ESC’Joe’ENTER
The complete listing of special GECS keywords:
GECS Keyword
Keystroke
BACKSPACE
Backspace
BS
Backspace
C_BACKSPACE
Ctrl & Backspace
C_BS
Ctrl & Backspace
ENTER
Enter
CR
Enter
C_ENTER
Ctrl & Enter
SPACE
Space Bar
ESC
Esc
TABLEFT
Shift & Tab
TABRIGHT
Tab
TAB
Tab
LEFT
Left Arrow
RIGHT
Right Arrow
C_LEFT
Ctrl & Left Arrow
C_RIGHT
Ctrl & Right Arrow
DOWN
Down Arrow
UP
Up Arrow
PAGEDOWN
PgDn
PAGEUP
PgUp
C_PAGEDOWN
Ctrl & PgDn
C_PAGEUP
Ctrl & PgUp
HOME
Home
END
End
C_HOME
Ctrl & Home
C_END
Ctrl & End
4-21
Task Automation
INS
Ins
DEL
Del
F1-F10
Function Keys
A_F1-A_F10
Alt & Function Keys
S_F1-S_F10
Shift & Function Keys
C_F1-C_F10
Ctrl & Function Keys
A_1-A_0
Alt & Top Row Number Keys
A_-
Alt -
A_=
Alt =
A_A-A_Z
Alt & Alphabetic Keys
C_@
Ctrl @
C_A-C_Z
Ctrl & Alphabetic Keys
C_[
Ctrl [
C_/
Ctrl /
C_]
Ctrl ]
C_^
Ctrl ^
Windows Command Line Type Only Keys:
A_SPACE
Alt Space
F11,F12
Function Keys
A_F11, A_F12
Alt & Function Keys
S_F11, S_F12
Shift & Function Keys
C_F11, C_F12
Ctrl & Function Keys
Wn
Wait ‘n’ seconds before sending the next key
SUSPEND
Wait until the current foreground window changes. This keyword only
works when the Agent is running one job at a time.
DOS Command Line Type Only Keys :
@WT n
Wait ‘n’ seconds before sending the next key
@WC row col char
Wait until char appears at row and col on the screen
@WS ‘string’
Wait until string appears somewhere on the screen
NLM Command Line Type Only Keys :
@WT n
Wait ‘n’ seconds before sending the next key
3) Keystrokes can be entered with their ASCII codes numerically “outside” the single quoted strings like:
‘abc’13 13 27 ‘Joe’ 13
When more than one number is entered in a row, they must be separated by at least one space. Spaces outside the
single quoted strings are ignored and simply act as separators.
4-22
Task Automation
To enter the non-typeable keys numerically, you need to know the “scan code” for the key. The scan codes are
entered in the most significant byte of a two byte number. For example, the key Alt Z is not a typeable key and has a
scan code of 44. To calculate the number to use multiply the scan code number times 256. For example:
44 * 256 = 11264
Use this number to “stuff” the Alt Z keystroke:
‘abc’ 11264 ENTER
Note that the method shown in section B of using the A_Z keyword would be much simpler in this situation.
4) All of the special GECS substitution variables can be used in the keystrokes to stuff. For example:
‘@SCHDATE’CR’@SCHTIME’CR
would be translated to something like
‘08/01/97’CR’08:00:00’CR
These 4 methods can be combined into a single set of keystrokes such as:
‘abc’ENTER ESC 45 ‘xyz’ @YR F1
5) Environment variables can be used in the keystrokes to stuff. For example:
‘%ENV%’CR CR
DOS Command Line Type Jobs Keystroke Length
DOS command line type jobs keystrokes are passed on the command line to a program called KS.EXE. Because
DOS limits the command line length to 128 characters, the total keystroke string is limited to 125 characters for
DOS (128 - 3 for the “KS ”).
Key Stuffing Based On Caption Text
GECS can stuff keys to windows based on their caption text (the text that appears in the center of the top line of a
window header) sometimes called the ‘title bar’. When entering the command line for the job, put the desired
caption text in curly braces ({}) after the command such as:
C:\EXCEL\EXCEL.EXE {Microsoft Excel}
Note that the entire caption need not be included. GECS will attempt to match just as much of the caption text as is
specified in the curly braces. The caption text must be entered exactly as shown. The comparison IS case sensitive
('A' does not equal 'a').
This helps solve a problem associated with certain Windows programs. GECS knows the window handle of the
window associated with the program it launches. If this initial program launches another program and then goes
away, GECS is unable to find the program it launched to send keys to. By specifying the caption text of the second
window (it may be the first one you can see), GECS will be able to figure out which window to send the keys to.
Another benefit of this feature is that you can specify just the window caption as the command line:
{Microsoft Excel}
and GECS will not attempt to start any new program. It will simply look for an already running program with the
specified caption text and will send the specified keys to that application.
4-23
Task Automation
Key Stuffing Using SUSPEND
SUSPEND is used to help simplify key stuffing with GECS on Windows Agents.
When the SUSPEND command is encountered, the Agent takes a snapshot of the windows that are active for the
job. The Agent then waits until the active window goes away or the window focus changes from the snapshot before
it continues sending keystrokes. This will solve the problem of not knowing how long a process will take and how
long to wait before continuing key stuffing. For example, the command line:
C:\EXCEL\EXCEL.EXE TEST.XLS
and the keystrokes of:
A_F 'P' ENTER SUSPEND A_F 'X'
This would cause Excel to start and load TEST.XLS. The keys to print the spreadsheet (A_F 'P' ENTER) would then
be stuffed and the Agent would then take a snapshot of the windows. Once the 'Printing' dialog box goes away, the
Agent would send the keys to exit Excel (A_F 'X'). This keyword only works when the Agent is running one job at a
time.
Key Stuffing on Windows Agents
The ability of GECS Windows Agents to send keystrokes to programs depends on the type of program being run and
the mode the GECS Agent is running in as shown below:
Job Command Line Type
Running From A Desktop Icon
Windows Running As A
Service
Windows NT/2000/XP/2003
Keys
No Keys
Windows 95/98/ME
Keys
No Keys
Windows 3.x
Keys
No Keys
DOS
Keys
Keys
OS/2
No Keys
No Keys
NT Console
Keys
No Keys
Known Keystroke Stuffing Problems With Windows
The Windows operating system provides no guaranteed method of sending keystrokes to applications. In most
cases, the keys sent by GECS to the jobs will get to the job without any problem. It is conceivable that from time to
time programs will not properly get the keystrokes you’ve told GECS to send. The following is a list of the things
you can do to reduce the likelihood of this occurring and/or to work around them:
• Add RAM to the machine or use a machine with a faster processor or hard drive.
• Reduce the number of “Simultaneous Jobs” to 1.
• Update the GECS.INI configuration file.
Also note that keys will not stuff if the Windows “Lock Workstation” feature is enabled.
4-24
Task Automation
Special DOS Key Stuffing Commands
There are two special commands for DOS command line type key stuffing routines used for Windows Agents to
help deal with programs that take an unknown amount of time. The @WC and @WS commands cause waits to
occur much like the @WT command, except that they wait until something happens on the screen. The @WC
command waits until a particular character appears on the screen at a particular location. Its syntax is:
@WC row col char
where ‘row’ and ‘col’ are the location of the character on the screen (1-25 and 1-80 respectively) and ‘char’ is the
character to look for at that location (case matters). For example:
CR CR @WC 1 1 A F10
would cause the Enter key to be pressed twice, the program would wait until the letter ‘A’ appeared in the upper left
corner of the screen and then the F10 key would be pressed.
The @WS command waits until a particular string appears somewhere on the screen. It’s syntax is:
@WS ‘string’
‘string’ is the word or phrase to look for. The word or phrase MUST be enclosed in single quotes (‘), the phrase must
match exactly (case matters) and the phrase must be found on a single line. For example:
CR CR @WS ‘Good Morning’ F10
would cause the ENTER key to be pressed twice, the program would wait until the phrase Good Morning appeared
somewhere on the screen and then the F10 key would be pressed.
These commands ONLY work when the video adapter is in 80x25 Color mode. They will not work when the video
adapter is in Mono or Graphics modes or when resolutions other than 80x25 are used.
Job Return Code Overview
Return codes can be a terrific way to monitor program execution, determine job success or failure and manage job
dependencies.
GECS does not generate return codes. It simply captures return codes produced by the programs or jobs your
Agents execute. By default, GECS recognizes ‘0’ as success and ‘255’ as a failure. Any other number is a result of
the program or application your GECS Agent ran. Job success or job failure can be defined for each job using the
Maximum good return code and Minimum good return code fields.
- Every well behaved EXE or COM program generates a return code when it finishes.
- Some programs don’t appear to generate a return code, though in reality they do. They just always return ‘0’.
- Internal commands such as COPY or DIR do not tend to generate return codes on most operating systems.
- Return codes generally work best when used with programs you develop yourself, rather than with off the
shelf programs you purchase.
- Most Unix programs return significant error codes on failure.
A specific scheme has been established to help make it easier to send return codes back from jobs for recording by
GECS. GECS can capture the actual program return code, the value of an environmental variable or the contents of
a disk file as the return code for a job, depending on the GECS operating system platform and command line type.
GECS first checks for a value sent from your program or executable. If this value exists, then GECS will record this
value as the job’s return code.
4-25
Task Automation
Next when the job “Command Line Type” is set to DOS, GECS looks for an environmental variable EL. If one
exists, GECS will override the value from the program, executable or shell script and record the environmental
value of EL as the Job’s return code.
Because many programs return meaningless return codes, GECS can use an ASCII text file named jobnum.EL,
found in the GECS Agent directory, for capturing meaningful return codes.
jobnum.EL is the name of your GECS job with a .EL extension added. Instance numbers must be omitted from the
job name before adding the .EL. For example, BATCH.JOB-1 would be:
BATCH.JOB.EL
GECS checks for a value in the jobnum.EL. If a value exists, GECS will override the value from the program,
executable or environmental value and record the value of jobnum.EL as the job’s return code. GECS automatically
deletes the jobnum.EL file after it is read.
Valid GECS Return Code Range
Valid return codes are determined in part by the operating system, in part by the GECS command line type and the
scheme used to capture return codes.
Command Line
Type
Valid Return Valid Range Using
jobnum.EL
Code Range
Windows
NT/2000/XP/2003
+/- 2 billion
+/- 2 billion
Windows
95/98/ME
+/- 2 billion
+/- 2 billion
Windows 3.1
0-255
+/- 2 billion
DOS
0-255
N/A
NT Console
0-255
+/- 2 billion
OS/2
0-255
N/A
NLM
N/A
N/A
UnixWare
0-255
0-255
Linux
0-255
0-255
AIX
0-255
0-255
HPUX
0-255
0-255
Solaris
0-255
0-255
Tru64 Unix
0-255
0-255
IRIX
0-255
0-255
4-26
Task Automation
Capturing Return Codes from Executables
GECS ships with a program to demonstrate how it deals with return codes from executables. The program is called
gecsret. A version of gecsret is shipped with every Agent.
GECSRET
This utility can be used to test your job streams with various job return codes. (Other variations of this utility
include: DOSRET, OS2RET, WINRET and WINRET32) Your “command line” should be as follows:
c:\gecs\gecsret retval
where retval is the return code you’d like the program to return. This program simply returns the specified value as
its return code. For example, create a GECS job named “TEST” and specify the following job parameters:
Command Line: c:\gecs\gecsret 8
Command Line Type: choose the appropriate operating system
Where c:\gecs is your Agent directory and 8 is the value you would like the program to return.
When you have finished, save your job and exit. After your job has run, ensure your job returned 8 by viewing your
completed job statistics return code for this job.
Capturing Return Codes within a Windows Batch or CMD
file
It is recommended that you run the commands you need to automate directly from the GECS job command line
when you can, rather than trying to launch several commands within a batch or CMD file. This way GECS can better
control your job stream and manage return codes. However, when it is necessary to use batch files or when dealing
with software you purchase you can test return codes by using a batch file similar to this one. TESTBAT.BAT:
4-27
Task Automation
@ECHO OFF
theprog.exe
IF ERRORLEVEL 255 goto 255
IF ERRORLEVEL 254 goto 254
IF ERRORLEVEL 253 goto 253
“
copy for all numbers
”
IF ERRORLEVEL 2 goto 2
IF ERRORLEVEL 1 goto 1
IF ERRORLEVEL 0 goto 0
:255
set el=255
goto d
:254
set el=254
goto d
”
copy for all numbers
”
:1
set el=1
goto d
:0
set el=0
goto d
:d
WINRET32.EXE -j:C:\GECS\jobnum.EL %EL%
ECHO %EL%
NTFS file system is required on the Agent PC if job names greater than eight characters are used.
For a test you could substitute “.exe” with “C:\GECS\GECSRET 1” and “C:\GECS” with your GECS Agent
directory. Your GECS job name could be CODETEST with:
Command Line: c:\gecs\TESTBAT.BAT @JOBNUM
Command Line Type: DOS
Because, in this example, you substitute WINRET32 retval with “1”, this job should return 1.
Note that you cannot use ECHO in your batch file to capture return codes if you are using long job names with DOS
command line type jobs. Instead, you must use the following command in your batch files to set the return code.
WINRET32 -J:jobnum.EL retval
Capturing Return Codes from Windows Environment
Variables
To retrieve meaningful return codes from DOS batch files (BAT), set an environmental variable named “EL” to a
number in your batch file with a line similar to:
SET EL=n
GECS will record the value of EL as the job return code in the completed job statistics for that job.
For example, you create a job named VALUEEL with the following job parameters:
4-28
Task Automation
Command Line: c:\gecs\ELTEST.BAT
Command Line Type: DOS
The batch file ELTEST.BAT contains the following lines:
SET EL=42
ECHO %EL%
PAUSE
This job named VALUEEL should capture the value of EL which is “42” and return 42 as the return code. You can
check your completed job statistics to verify.
Capturing Windows Return Codes using the jobnum.EL file
The special ASCII text jobnum.EL file makes it very easy to setup return codes for jobs that normally would not
return meaningful values. For example:
If you have a job named “BATCH.123-1” that executes a Windows NT/2000/XP/2003 batch file (CMD) with the
following job parameters:
Command Line: c:\gecs\123TEST.CMD
Command Line Type: Windows NT/2000/XP/2003 (not NT Console or
DOS)
you might include in the 123TEST.CMD file the line:
ECHO 5 >BATCH.123.EL
When the job is complete and GECS finds the file named ‘BATCH.123.EL’ which contains the number 5, it will
record a return code of 5, regardless of the value returned by the program, then automatically delete the
BATCH.123.EL file.
Another example could be a job named “BATCH.456-1” with the following job parameters:
Command Line: c:\gecs\456TEST.CMD @JOBNUM
Command Line Type: Windows NT/2000/XP/2003
The 456TEST.CMD file might contain the following:
yourprog.EXE
ECHO 12 >%1.EL
GECS would use the @JOBNUM substitution variable from your command line and substitute its value in your
CMD file thus replacing the “%1” with the name of your GECS job “BATCH.456”. You can then view your
completed job record to verify that your job named “BATCH.456-1” records 12 as its return code.
4-29
Task Automation
Windows Return Codes and Command Line Types
The following describes the various command line types and how GECS handles program return codes.
Command Line Type
Return Codes
Windows NT/2000/XP/2003 Batch File (CMD)
Contents of jobnum.EL is captured.
Windows NT/2000/XP/2003 or Windows 95/98/ME
EXE return code or contents of jobnum.EL is captured.
executable
Windows 3.x Executable
EXE return code (use LAUNCH16) or contents of
jobnum.EL is captured.
DOS Executables
EXE return code is captured
DOS Batch File (BAT)
Value of the environmental variable EL is captured or
contents of jobnum.EL is captured.
OS/2 Executable
EXE return code or contents of jobnum.EL is captured
NT Console Job
Value of the environmental variable EL is captured or
contents of jobnum.EL is captured.
Windows 3.1 Command Line Type Jobs
As mentioned previously, GECS can capture and record return codes directly from 32-bit programs.
However, GECS does not capture return codes sent directly from 16-bit Windows 3.1 programs. They always
record a return value of zero. To address this issue, you may use a special utility called LAUNCH16.EXE.
Using LAUNCH16.EXE to Capture Return Codes
The LAUNCH16 utility can be used to run and capture return codes from 16-bit Windows 3.1 applications run by
GECS.
LAUNCH16 captures return codes by writing the jobnum.EL file to the specified GECS directory. As mentioned
previously, GECS will look for the jobnum.EL file on job completion, read it, log the return value then delete the
file.
The LAUNCH16 program requires the following command line parameters:
LAUNCH16 <GECS Agent directory> <job number> <command line>
<GECS Agent directory>
-The fully qualified path to your Windows Agent programs.
LAUNCH16 writes the jobnum.EL file to the specified directory.
<job number>
-The job number of the job being executed. Pass this on the GECS
command line using the @JOBNUM substitution value.
<command line>
-The 16-bit Windows command line you need to automate.
4-30
Task Automation
Running a 16-bit program from a GECS command line
For example, create job named 16PROG with the command line type of Windows NT/2000/XP/2003 and
command line as:
C:\GECS\LAUNCH16.EXE C:\GECS @JOBNUM yourprog.exe
Where C:\GECS is your GECS Agent directory and yourprog.exe is the name of your 16-bit program. In this
example you could use “C:\GECS\WINRET32.EXE 1”. When run as a GECS job, this command line would return
1.
Running a 16-bit program from a Windows NT/2000/XP/2003
CMD file
For example, a job named 16BCMD with the command line type of Windows NT/2000/XP/2003 and a command
line as follows:
TEST16.CMD C:\GECS @JOBNUM
Contents of TEST16.CMD:
C:\GECS\Launch16.EXE %1 %2 yourprog.exe
Where yourprog.exe is the name of your 16-bit program you are automating. In this example you could use
“C:\GECS\WINRET.EXE 33”. This GECS job would return 33.
DOS and NT Console Command Line Type Jobs
Your Windows Agents execute DOS command line type jobs and Windows NT Console command line type jobs
quite differently from other types of jobs. These command line type jobs not only create and execute special
temporary batch files before launching your command line, they also execute different batch files depending on the
type of command line you have defined for the job. For instance, if your command line automates a DOS batch file
versus if your command line automates a DOS program or executable. Each special temporary batch file is created
in your GECS program directory and is assigned a random name such as “$T000001.BAT”.
DOS and NT Console Command Line Type Jobs that
Automate Batch Files
If your GECS job has a command line that automates a batch file GECS will create a special temporary batch file as
described below:
1. It executes the lines for PRECMD.TXT
2. It changes to the start in directory defined for the job.
3. It executes the command line using a CALL statement:
CALL TEST.BAT
4. It changes back to the GECS drive and subdirectory:
C:
CD \gecssubdir
5. It executes a special program for capturing return codes:
WINRET32 -J:JOBNUM.EL retval
4-31
Task Automation
6. It executes the lines from POSTCMD.TXT.
DOS Command Line Type Jobs that Automate DOS Programs
The special temporary batch file that gets written for jobs that have command lines setup to run DOS programs or
executables (not batch Files) can be described as follows:
1. It executes the lines from PRECMD.TXT.
2. It “stuffs” the keystrokes for the job:
KSLOAD
KS keystrokes
3. It changes to the drive and subdirectory for the job:
F:
CD \subdir
4. It executes the command line:
THEPROG.EXE
5. Sets EL to the ERRORLEVEL
6. It changes back to the GECS drive and subdirectory:
F:
CD \gecssubdir
7. It unloads the keyboard “stuffer”:
KSLOAD
8. It executes a special program for capturing return codes:
WINRET32 -J:JOBNUM.EL retval
9. It executes the lines from POSTCMD.TXT.
Other Command Line Type Jobs
When programs are executed as Windows NT/2000/XP/2003, Windows 95/98/ME and Windows 3.1 command
line type jobs, no special GECS batch file is written.
1. The Agent changes to the drive and subdirectory for the job.
2. The Agents directly launch the EXE file.
3. The Agent sends keystrokes to the launched program.
4. When the program ends, the Agent records the programs return code directly.
Defining Job Success and Failure
Each GECS job can define what it considers a success by setting the “Minimum Good Return Code” and failure by
setting the “Maximum Good Return Code” from the Actions tab on a job entry screen.
4-32
Task Automation
Job Comments
The “Job Comments” field is an optional field that can be used to enter a miscellaneous comment about your job. Job
comments can be up to 128 characters in length.
Job Notes
The “Job Notes” field is an optional field. It contains an ASCII text file can be edited and used for notes, comments
or documentation relative to the job. The files are named:
BATCHNAME-JOBNAME.note
Instance numbers are excluded.
Job notes are not deleted when a job is deleted. Job Notes can be up to 4k in size. The notes must be stored in the
GECS data directory because they must be accessible by the DBMS.
These job notes are automatically backed up with the GECS data is backed up.
Creating Jobs Using WRK Files
WRK (pronounced ‘work’) files are one of the most powerful features of GECS. WRK files are used to add jobs to
the GECS system without using the GECS Client programs. This is the easiest way to interface with GECS from
other programs. WRK files are also used to transfer jobs from a test environment to a production environment.
GECS can be configured to look for these files. When it finds one, it reads it, validates it and creates a GECS job
based on it, just as if a user had manually created a job using the Client programs.
For example, if you want users to easily submit a job that prints a report, you could write a program or batch file that
simply creates the appropriate WRK file. GECS finds it, adds it as a jobs and then dispatches it to an Agent. The
user wouldn’t need to run the sometimes complex GECS Client programs. WRK files are simple to create. They are
ASCII text files, the type created by programs like Notepad. Almost any language or 4GL tool can write an ASCII
text file.
Every job parameter that you can enter in the Job record screens can be included in your WRK file. Press the F1
function key on each Job field to display online help which contains each equivalent WRK file parameter.
Conversely, existing GECS jobs can be dumped into WRK files. See the Job Export Utility in the GECS Command
Line Utilities chapter of this manual for details.
As GECS adds the WRK files as jobs, it validates your entries. Information you have left out of your WRK file is set
to the defaults. Some of the defaults can be defined by you from the defaults tab in the (Controller) record. For the
others the defaults are simple blanks or zeros.
You can also submit .WRK files via supported mail systems. For details see the Submitting Jobs Via Mail section of
this chapter.
4-33
Task Automation
File Format for WRK Files
The Global Event Control Server® can automatically add new jobs by looking for files that end in the extension
WRK. If one of these files is found, GECS reads it and adds new jobs based on the information in the file. These
files are standard ASCII text files, like those created by EDLIN, NOTEPAD or other word processors. Each line
contains a command that describes the job to be added. The lines all have the format of:
X:yyyyy
where x tells the Global Event Control Server® what kind of data is on the line and yyyyy is the data for the line. The
various types of commands that can be entered in a WRK file are described in detail later in this manual.
As an example, a WRK file that contains these two lines:
C:DIR F:\*.*
N:FRED
would cause the Global Event Control Server® to add a job submitted by user (N:) FRED and the command to
execute (C:) is DIR F:\*.*. All WRK files must contain a name line (N:name). Commands for multiple jobs can be
put in a single WRK file if you wish. The commands for the different jobs are separated by beginning the line with
the pound sign (#). Additionally, you can put comments in the WRK file as well. Any line that begins with a
semicolon (;) is considered a comment line. For example:
; the first job
C:COPY F:\X F:\Y
N:FRED
#
; the second job
C:DEL F:\X
N:FRED
This WRK file would cause GECS to add two separate jobs to your jobs file. Remember that when commands are
omitted, the Controller that adds the job using default values. WRK file values can be obtained from each field in the
Job record by pressing the F1 key while your cursor is positioned on the field.
The following list is organized in numerical/alphabetical order by WRK file command:
Command
Values
Description
1:totaltimes
0-9999
number of times to execute
2:remaining
0-9999
remaining times to execute
2n:execafter
text
job ‘name’ to execute after in multi-job WRK file
(20:-29:)
3:substcmd
0-1
substitute command line 0=No, 1=Yes
4:filespec
text
filespec to check for
4n:relationship
0-5
return code relationship (40:-49:)
0 <=, 1 <, 2 =, 3 >, 4 >=, 5 <>
5:fileexist
0-6
0=no file exists, 1=if any file exists, 2= if any file can be
opened sharably, 3=if any file can be opened exclusively,
4=if all the files exist, 5=if all files can be opened
exclusively, 6=if all files can be opened sharably
5n:resource
text
required resource (50:-59:)
6n:timeafterjob
hh:mm:ss
time to wait after execafter job ‘n’ (2n:) finishes before
executing this job (60:-69:)
7:jobnumber
text
add the job with this job number
8:class
text
the job class for use in figuring vacations
4-34
Task Automation
9:relaabso
0-3
0=relative repetition, 1=absolute repetition, 2=day of
week repetition, 3=special
number of variable units
10:nth
0-366
11:daytype
0-11
0=reg,1=business,2=non-business,3=weeks,4=months,
5=sundays, 6=mondays, 7=tuesdays, 8=wednesdays,
9=thursdays, 10=fridays, 11=saturdays
12:begend
0-3
0=from beginning, 1=from end, 2=on or after beginning,
3=on or before end
13:period
0-5
0=week, 1=month, 2=defined month, 3=quar
ter, 4=half, 5=year
14:osver
0-99.99
the required minimum operating system version required
15:keystostuff
text
the keys to stuff into keyboard buffer
16:retryreturn
17:notifyretcode
0-999999999999 retry job if the return code is = this number, 0=no retry
0-255
minimum retcode to notify on
18:maxjobminutes
0-9999
maximum minutes for job to run
19:exectype
0-12
command line type 0=DOS, 1=Win31, 2=OS/2,
3=WinNT/2000/XP/2003, 4=NLM, 5=Win95/98/ME,
6=NT Console, 7=UnixWare, 8=Linux, 9=AIX,
10=HPUX, 11=Solaris, 12=OS/400, 13=Tru64,
14=IRIX
30:jobname
text
‘name’ of this job in multi-job WRK file
31:showactivity
0-1
show activity 0=No, 1=Yes
32:estjobminutes
0-9999
estimated minutes for job to run
33:keystostuff2
text
the keys to stuff into keyboard buffer
34:keystostuff3
text
the keys to stuff into keyboard buffer
35:keystostuff4
text
the keys to stuff into keyboard buffer
36:escalateminutes
0-9999
minutes before escalation of priority
37:failjob
text
job to activate on failure
38:maxminlate
0-9999
maximum minutes late before activating, 0=none
39:keepdone
0-1
keep job when done 0=no, 1=yes
70:latejob
text
job to activate if this job is late
71:lateskipmin
0-9999
skip job if this many minutes late, 0=none
72:launchmode
0-3
0=normal, 1=hidden, 2=minimized, 3=maximized
73:maxgoodreturn
0-255
return greater than this and activate latejob
74:message
text
execute message to prompt before job
75:sun
0-1
run on Sunday 0=no, 1=yes
76:mon
0-1
run on Monday 0=no, 1=yes
77:tue
0-1
run on Tuesday 0=no, 1=yes
78:wed
0-1
run on Wednesday 0=no, 1=yes
79:thu
0-1
run on Thursday 0=no, 1=yes
80:fri
0-1
run on Friday 0=no, 1=yes
4-35
Task Automation
81:sat
0-1
run on Saturday 0=no, 1=yes
82:caltype
text
calendar type to use
83:escalpriority
0-9
amount to escalate late jobs priority by 0-9
84:oninvalid
0-1
on conflict with valid period 0=wait until end,
1=reschedule
85:juststart
0-1
mark complete once started 0=no, 1=yes
86:timestoretry
0-99
times to retry on failure
87:businessonly
0-2
0=all days ok, 1=business days only, 2=non-business days
only
88:skiplate
hh:mm:ss
skip this job if it will finish after this time - 00:00:00 =
don’t skip
89:afterspecial
0-4
0=complete, 1=complete & warn, 2=relative, 3=absolute,
4=day of week
90:bval1
hh:mm:ss
beginning of valid time 1
91:bval2
hh:mm:ss
beginning of valid time 2
92:bval3
hh:mm:ss
beginning of valid time 3
93:bval4
hh:mm:ss
beginning of valid time 4
94:bval5
hh:mm:ss
beginning of valid time 5
95:eval1
hh:mm:ss
end of valid time 1
96:eval2
hh:mm:ss
end of valid time 2
97:eval3
hh:mm:ss
end of valid time 3
98:eval4
hh:mm:ss
end of valid time 4
99:eval5
hh:mm:ss
end of valid time 5
A:status
0-3
job status 0=pending, 1=started, 2=on hold,
3=completed, 4=pending as of next scheduled time after
now
An:dephours
0-99
predecessor ‘n’ must have run in the last ‘dephours’ hours
(A0:-A9:)
B:repeatbase
0-2
repeat base 0=from start time, 1=from end time, 2=from
scheduled time
Bn:spdaten
mm/dd/yyyy
special schedule ‘n’ date (B0:-B9:)
C:cmdline
text
command line to execute
Cn:sptimen
hh:mm:ss
special schedule ‘n’ time (C0:-C9:)
D:date
mm/dd/yyyy
date to execute
E:priority
0-9
job priority
F:comment
text
comment to put on job
G:group
text
execute by Agent group
H:pathname
text
start in directory /path to change to/working directory
J:jobnumber
text
re-run job number - if used, the only other ones that can
be used are D:, N: or T:
4-36
Task Automation
M0:filename
text
file attachments may be used when using mail features
with GECS.
M5: - M9:mailto
text
mail to: user or group names on job completion. Include
an asterisk * before group names.
N:username
text
user name
O:os
0-10
operating system required 0=Other, 1=Any,
2=WinNT/2000/XP/2003, 3=UnixWare, 4=NetWare,
5=Win95/98/ME, 6=Linux, 7=AIX, 8=HPUX, 9=Solaris,
10=OS/400, 11=Tru64 Unix, 12=IRIX
P8:supplies
text
supplies necessary
P9:premesg
text
message to send before job
P0:postmesg
text
message to send after job
Q1:depfilesize
0-99999999
minimum file size in bytes of trigger file
Q2:unscheduled
0-1
never late - is this an unscheduled job 0=no, 1=yes
Q3:createevent
0-1
create events for this job 0=don’t, 1=create
Q4:loginuser
0-1
login as a specified user 0=no, 1=yes
Q5:loginname
text
login network user name
Q6:loginpswd
text
password
Rn:retval
0-255
max return code for execafter (R0:-R9:)
Sn:Agent
text
Agent name to execute (S0:-S9:)
T:time
hh:mm:ss
time to execute
U:repeatunit
0-9
units of repeat interval 0=seconds, 1=minutes, ..
V:repeatvalue
0-99999999
repeat value
W:diskspace
0-9999
minimum megs of disk required
Xn:execafter
text
job to execute after (X0:-X9:)
Y:title
text
job title
Zn:eventn
0-999999999
depends on event (Z1:-Z9:)
Note that some WRK file parameters are shown in the format Xn:, where ‘n’ is a number from 0 through 9 indicating
that there are 10 possible values for the field.
#
end of job/beginning of next job
;
Comments
Adding Dependent Jobs Via WRK Files
Typically you need to know the job number that a job depends on in order to setup the job dependency. When jobs
are added via WRK files, you may not know the number that will be assigned to the job. If you don’t know a job’s
number, you can’t make other jobs dependent on it.
The ‘2n:’ and ‘30:’ WRK file commands allow you to add dependent jobs via WRK files, as long as all the jobs
involved in the dependency are added via a single WRK file with the ‘#’ character as a separator between jobs. The
‘30:’ command allows you to assign a logical name to each of the jobs in the WRK file. For example, the WRK file:
4-37
Task Automation
N:USER
C:DIR
30:Step1
#
N:USER
C:DIR
30:Step2
#
N:USER
C:DIR
30:Step3
#
N:USER
C:DIR
30:Step4
would define four separate jobs and would give each of them a name by using the ‘30:’ command. This name by
itself is useless unless it is used in conjunction with one or more ‘2n:’ commands. For example, the WRK file:
N:USER
C:DIR
30:Step1
#
N:USER
C:DIR
30:Step2
;this job should run after the first one
20:Step1
#
N:USER
C:DIR
30:Step3
;this job should run after the first one
20:Step1
#
N:USER
C:DIR
30:Step4
;this job should run after the second & third ones
20:Step2
21:Step3
uses the ‘20:’ command to define the dependencies between the jobs in the WRK file. The second job depends on
the first job finishing. The third job also depends on the first job finishing. The fourth job won’t run until both the
second and third jobs have run.
Note that the names must be defined in the file with a ‘30:’ command before they can be referenced with a ‘2n:’
command or the WRK file will be rejected. Also note that case is unimportant in the names. Step1 is the same name
as STEP1. Names can be up to 128 characters in length. You should view the ‘2n:’ commands as equivalent to the
‘Xn:’ commands which are used to define dependencies when job numbers are known. You can use the ‘6n:’ and
‘Rn:’ commands along with the ‘2n:’ commands to indicate the return codes and delays for the dependencies just as
they would be used with the ‘Xn:’ commands.
4-38
Task Automation
Submitting Jobs via Mail
WRK files can be sent to GECS via mail in one of two ways. Either the text of the message can contain the WRK file
commands or the WRK file can be sent directly as an attached file. The following mail systems are supported:
• Microsoft Mail
• cc:Mail
• Internet Mail
• Novell MHS
Submitting jobs via Lotus Notes mail is not supported.
Submitting Jobs Via Microsoft Mail, cc:Mail, Internet Mail
or MHS Mail
To submit WRK file commands as the text of the message, simply send a message to the email user you’ve defined
for GECS as if it were another email user with the text of the message as the WRK file. For example,
C:command to execute
N:users_gecs_name
n:other options
Or For MHS Mail
From:users_mhs_name
To:GECS_mhs_name
C:command to execute
N:users_gecs_name
n:other options
To submit WRK files as attachments to a message, simply send a message to the email user you’ve defined for
GECS as if it were another email user with no text in the message, but with an attachment of a WRK file. Press the
Attach button to add the attachment to the message similar to:
From:users_mhs_name
To:GECS_mhs_name
Attachment:wrk_file_name
If an attachment is sent with the message, the message text is ignored. If there are no attachments, the message text is
assumed to contain WRK file commands.
In order to preserve security, GECS checks to see that the sending email user name, defined in the “Mail User or
Address” field, is the same as the mail user name defined for the user referenced in the WRK file N: parameter. For
example, if the email message:
From:JohnDoe
To:GECS_1
C:DIR
N:JDOE
was sent to submit a job, it will only be accepted if the GECS user JDOE has an email name, defined in the “Mail
User or Address” field, defined as JohnDoe. If the email name is different, the WRK file will be rejected.
When WRK files are received from email, they are written to disk as WRK files and are then added as jobs just as
any WRK file might be added.
4-39
Task Automation
GECS will not send return receipt messages to the sending email user.
When Your GECS Job Won’t Run...
Here are a few suggestions to try if you are having difficulty automating your command line in GECS.
1. Test Your Programs by Hand If you experience problems running a command line using GECS you should verify that you are able to run it by
hand on the computer where your Agent is running. If you can not walk up to the Agent and launch the task, your
GECS Agent will not be able to launch it either.
2. Display the “Why this job cannot run” List Click on the “Why this job cannot run” toolbar button from the job record
3. Test a different Job Test a different, simple job and ensure it will run. For instance, on Windows run a DOS Directory (DIR) ensure
you can get any job to run.
4. Check your Command Line Type Ensure you have defined an appropriate “command line type” for the job “command line” you are trying to run.
5. View your Completed Job’s Statistic Check your completed job record. Analyze the completed job detail record, specifically the return code,
launch error and message fields. If using substitution, check to see if substitution has worked by
viewing the command line or appropriate field.
6. Run your agent from a desktop icon
7. Do not “Login as Submitting User”
8. Populate the “Start In Directory”
Automating Programs
When defining jobs, you must accurately specify the “Command Line”, “Command Line Type” and “Start In
Directory”. GECS will not properly run jobs if these job parameters are not correct. In order to properly define a
job, you must know the following:
• What is the name of the executable, script or batch file?
• If you are going to run an executable, what type of executable is it? If you are going to run a script, how is
it launched? If you are going to run a batch file, is it a Windows NT/2000/XP/2003 batch file (CMD)
containing Windows NT/2000/XP/2003 commands and Windows NT/2000/XP/2003 and/or DOS programs or is it a DOS batch file (BAT) containing only DOS commands and executables?
• What is the drive and subdirectory where the executable, script or batch file is located?
4-40
Task Automation
Editing Text Files from GECS Job Entry Screens
The GECS client job entry programs allow direct access to ASCII text files to be edited. This is accomplished by
either pressing the “<F8>” function key when your cursor is positioned on the “command line” field or by pressing
the command line lookup button and selecting the “Edit” option. GECS accomplishes this under Windows by
calling the Windows Notepad program.
Guide To Developing Job Programs
GECS can run most types of programs as jobs just as if they were run by hand and most of the programs you run as
jobs will likely be off the shelf programs built by others. In situations where you are writing the programs that will
be run as jobs, there are several things to keep in mind that will help you create programs that run optimally as jobs.
1. Pass parameters to the programs on the command line.
Though keystuffing works well with most programs, passing parameters to your programs on the command line is the most reliable method of sending runtime parameters to programs. The GECS substitution
variables can all be used as command line arguments as well.
2. Limit or eliminate the user interface.
The CPU time spent producing a ‘pretty’ user interface will be wasted when the job is run unattended. The
work your program needs to do will happen faster if time isn’t wasted updating a user interface.
3. Whenever possible write text applications that use redirectable standard I/O.
Though text applications are not as attractive or intuitive, their ability to take input from standard in and
send their output to standard out can be useful for monitoring applications. The ‘printf’ and ‘scanf’ standard ‘C’ functions are both simple and functional for unattended operation. Sending status messages out to
standard out which has been redirected to a file provides an easy method of logging the progress of your application.
4. Return meaningful return codes.
Many of GECS’s features become much more powerful when the programs being run as jobs return meaningful return codes. GECS can record return codes in the completed job statistics and make decisions
based on their value. Job dependencies and processing of failures are two features that are more powerful
when meaningful return codes are used. At a minimum, try to have your programs return 0 for success and
non-zero for failure.
Windows
NT/2000/XP/2003
Architecture
Windows NT/2000/XP/2003 runs most programs in their own protected address space. However, 16 bit Windows
programs can be run either in their own address space or in a common address space shared with other 16 bit
Windows programs. GECS Agents for Windows runs all jobs in their own address space. This architecture has
several implications that are worth understanding:
4-41
Task Automation
All jobs are protected from other misbehaved jobs, even if they are DOS or 16 bit Windows programs.
16 bit Windows programs are protected from the unpredictable problems associated with the Windows On
Windows (WOW) layer when shared with multiple 16 bit Windows applications.
Once started, 16 bit Windows programs run faster than if WOW is used.
GECS can safely terminate programs that run too long.
16 bit Windows programs running in their own address space consume more system resources than if
WOW was used.
The time required to start 16 bit Windows programs is increased when run in their own address space.
16 bit Windows programs that are run as jobs cannot communicate with other 16 bit Windows programs
that are running either in the shared WOW address space or in a separate address space using DDE. If the
program that is launched by GECS starts the program it wants to communicate with as its “child”, both programs will be in the same address space and they can communicate using DDE.
GECS Agents for Windows will launch OS/2 1.x text programs, though key stuffing is not supported. Any
OS/2 program that you can run by hand, can be run by GECS.
By default, DOS programs are launched using the DOS command interpreter in the format of :
command.com /E:1024
This can be changed by using an entry in the GECS.INI file. To change the launching command for DOS
programs to:
command.com /E:1536
you would add the following lines to the GECS.INI file:
[Agent]
SHELL=c:\winnt\system32\command.com /E:1536
You can also use this setting to indicate a different DOS command interpreter or the location of your command interpreter if it’s not located in your search path.
Windows NT/2000/XP/2003 and Windows 95/98/ME jobs can automatically be terminated if the “maximum job minutes” is exceeded or if the GECS for Windows Agent is closed while jobs are still running.
4-42
Scheduling Jobs
Scheduling Jobs
5-1
Scheduling Jobs
5-2
Scheduling Jobs
Scheduling Concepts
GECS is designed with the concept that many jobs need to be run repeatedly according to some schedule. Jobs can
be defined in GECS to run once, a fixed number of times or indefinitely.
Multiple Method Scheduling (MMS) allows for simple programming and management of tasks with a widely
varying repetition schedule.
All jobs can be set up to repeat using a scheduling model called “Dynamic” scheduling. When jobs are created, the
date and time that the job should run next is entered. When a recurring job completes the system automatically
creates a new job with a new instance number based on rescheduling information entered for the job. For example:
"BATCH1" contains batch job "JOB1" which is scheduled to run at 7pm, daily Monday thru Friday forever.
Run BATCH1.JOB1 today at 7pm then reschedule BATCH1.JOB1 to run tomorrow at 7pm by creating
BATCH1.JOB1-1. Then after it runs create job BATCH1.JOB1-2. After it runs create BATCH1.JOB1-3 and so on.
New job records are created only after the run of each job.
Batch jobs can be scheduled using a scheduling model called “Static” scheduling. Static scheduling is different
from dynamic scheduling in that the next instance of the job is immediately created when the Batch is Scheduled.
Like Dynamic scheduling, a separate job record is created for every instance of when the job should run next but, the
instance is generated immediately. Likewise, each job created using static scheduling is set up to run only once and
is marked complete when it finishes. For example:
"BATCH1" contains batch job "JOB1" which is scheduled to run at 7pm, weekly Monday thru Friday for the rest of
the year.
Run BATCH1.JOB1-1 11/02/1998 at 7pm then mark it complete.
Run BATCH1.JOB1-2 11/03/1998 at 7pm then mark it complete.
Run BATCH1.JOB1-3 11/04/1998 at 7pm then mark it complete.
Run BATCH1.JOB1-4 11/05/1998 at 7pm then mark it complete.
Run BATCH1.JOB1-5 11/06/1998 at 7pm then mark it complete.
Run BATCH1.JOB1-6 11/09/1998 at 7pm then mark it complete.
Run BATCH1.JOB1-7 11/10/1998 at 7pm then mark it complete.
Run BATCH1.JOB1-8 11/11/1998 at 7pm then mark it complete...
All job records are created for static are created immediately when the Batch is scheduled. The advantage of using
static scheduling is that it gives you the ability to alter a job stream on a particular day, with or without affecting
other days.
In addition to the scheduling model, GECS supports several different methods of rescheduling; Relative, Absolute,
Day Of The Week and Special. Given the power of these different methods, you may actually find there is more than
one way to accomplish the same rescheduling.
Jobs That Repeat
Jobs can be set up to repeat in a variety ways. Jobs records can be setup to repeat by filling out scheduling
information displayed on the Schedule tab. These jobs will use dynamic scheduling. Batch jobs can be set up to
repeat by filling out scheduling information displayed on the Scheduling Options tab prior to scheduling your Batch
5-3
Scheduling Jobs
jobs. These Batch jobs can be set up to use either dynamic or static scheduling. The two fields described below can
be used with both types of scheduling.
Reschedule on
The “Reschedule on” field is used to assign the type of day your job should run. You may choose to reschedule your
job on “all days”, “business days” or “non-business days”. Business and non-business days must be defined using
the Calendar module. See the Defining Calendars section of this chapter.
With Calendar
The “with calendar” field is used to assign a calendar for rescheduling to your job. A calendar is required when
rescheduling your jobs on “Business Days”, “Non-Business Days” and or “Defined Months”. See the Defining
Calendars section of this chapter for details.
Job Scheduling
GECS offers four different methods of rescheduling jobs:
• Relative
• Absolute
• Day of the Week
• Special
Relative Scheduling
Relative scheduling is used when you want your job to run some period of time after the last time it ran or was
scheduled to run. It can be described with the sentence:
“Schedule the job to the date and time that is ‘n’ periods of time after the last time the job was scheduled, started or
finished.” For example:
15 seconds after the last time it finished
1 day after the last time it was scheduled
1 month after the last time it was started
Note that when using Batches static scheduling, relative scheduling is different in that the repeat interval must be
greater than or equal to a one day period. Because jobs are scheduled before they run, they are always scheduled
relative to their scheduled time, not start or finish time.
Absolute Scheduling
Absolute scheduling is used when you want your job to run at a fixed point in time. It can be described with the
sentence:
“Schedule the job to a date and time that is ‘n’ periods of time from the beginning or end of another period of time”
5-4
Scheduling Jobs
For example:
1 day after the beginning of the next week
3 business days on or after the end of the next month
5 non-business days after the beginning of the next quarter
When jobs are defined to reschedule using the absolute method, there are four choices for the offset within the next
period.
1.
2.
3.
4.
after the beginning of
before the end of
on or after the beginning of
on or before the end of
The difference between ‘after the beginning’ and ‘on or after the beginning’ is whether the first day is counted, when
it’s qualified. The difference between ‘before the end’ and ‘on or before the end’ is whether the last day is counted,
if it’s qualified. The following jobs show the differences:
1.
2.
3.
4.
The job should reschedule to the date that is 1 Thursday after the beginning of the next month.
The job should reschedule to the date that is 1 Thursday on or after the beginning of the next month.
The job should reschedule to the date that is 1 Thursday before the end of the next month.
The job should reschedule to the date that is 1 Thursday on or before the end of the next month.
The jobs run on Jan 15, 1996 and Feb 1, 1996 and Feb 29, 1996 which are all Thursdays.
The jobs would be rescheduled to:
1.
2.
3.
4.
Feb 8, 1996 (Feb 1 is not after the first day of the next month)
Feb 1, 1996 (Feb 1 is on or after the first day of the month)
Feb 22, 1996 (Feb 29 is not before the last day of the month)
Feb 29, 1996 (Feb 29 is on or before the last day of the month)
On the other hand, if the same 4 jobs were setup for Wednesdays instead of Thursdays, they would reschedule to:
1.
2.
3.
4.
Feb 7, 1996
Feb 7, 1996
Feb 28, 1996
Feb 28, 1996
In most cases, you will find the ‘on or after’ or ‘on or before’ selections will tend to deliver the results you expect.
Use the ‘after’ and ‘before’ selections when you specifically do not want the first or last day to be chosen.
Day Of The Week Scheduling
Day of the week scheduling is probably the simplest of the methods. Pick the days of the week the job should run and
it gets rescheduled on the next day of the week it’s supposed to run. It can be described by the sentence:
“Schedule the job to the same time on the next valid day such that the new date and time are after the date and time it
finished.” For example:
every Monday
every Monday, Wednesday and Friday
every Saturday
Special Scheduling
Special scheduling allows you to enter up to 10 dates and times when the job should run. With this capability you
can cause jobs to be rescheduled in a completely random fashion. As the Special times are ‘used up’ or if they fall in
the past, they are cleared from the Special Schedule. Additionally, you can use Special scheduling for temporary
changes to your regular schedule. Once the special dates and times have been ‘used up’, jobs can be configured to
5-5
Scheduling Jobs
revert to a regular schedule using relative, absolute or day of the week or they can be marked complete, with or
without notification.
Checking Job Schedules
Job Schedule Lookups
To help you set up job schedules, the job record screens allow you to view the next 20 iterations of the schedule
you’ve defined for a single job. From the job screen you may click on the File pull down menu and select ‘This Jobs
Schedule’ or click on the toolbar button shortcut for this jobs schedule. This lookup is used for jobs scheduled to
repeat using the dynamic scheduling model. Vacation periods do not show up when viewing job schedules.
Advanced Scheduling Features
GECS allows you to create very simple or very complex schedules. Job parameter information input from the
various job entry screens along with information entered in GECS Calendars, Vacations, Resources, Agents and
Events can work together to orchestrate a very wide range of schedules.
Defining Calendars
Defining Business Days and Defined Months Calendars
GECS allows you to create custom calendars defining “Business Days” and/or “Defined Months”. These calendars
are used for scheduling jobs. Jobs are assigned a calendar name to determine which business day and/or defined
month the job should use for rescheduling.
Calendars can also be assigned “effective” and “expiration” dates. Batch jobs created using static scheduling use
the effective and expiration dates to determine the range of jobs that should be created for a scheduled Batch.
Calendar features are typically used for complex rescheduling that doesn’t fit the other built-in rescheduling
methods GECS offers. You may not need to define custom calendars.
To define business days, you actually identify non-business days. When a non-business day is indicated, all other
days, by default, are then considered business days. A defined month requires a start and end day to makeup the
beginning and ending of the month.
Use the Calendars screens to define calendars or use the “Add Calendar” command line text utility to load a calendar
from a comma separated file.
Job Scheduling Day Types
Regardless of the method of rescheduling defined for a job, you can indicate that a job should only be rescheduled
for business days or non-business days. For example:
5-6
Scheduling Jobs
Reschedule the job to the time that is 23 hours after the last start time, but only on a business day.
or
Reschedule the job to the day that is 3 days after the beginning of the next quarter, but only on a business day.
or
Reschedule the job to the next Saturday, but only on a non-business day.
or
Reschedule the job to 02/02/98, but only on a business day.
When GECS encounters a conflict where the principle job scheduling rules generate a day that is contrary to the
required type of day, they simply reschedule the job again until the resulting day is the correct type. When the
rescheduling scheme is based on the job’s finish time, the job’s estimated minutes is added to the previously
calculated start time for each rescheduling. Using the first example above, if Saturdays and Sundays are
non-business days and the job starts on Friday at 23:00:00, the job would reschedule as follows:
22:00:00 Saturday Fails
21:00:00 Sunday
Fails
20:00:00 Monday
Success
As you can see, it is possible to define jobs that can’t accurately reschedule. For example:
Reschedule the job to the day that is 2 business days after the beginning of the next month, but only on a
non-business day.
This schedule would result in an infinite loop where GECS would be unable to derive a good next scheduled date, no
matter how many times it tries. GECS will stop trying to reschedule a job, mark it complete and record an error
when the following conditions have been met:
1. The derived date is at least 31 days after the last scheduled date, and
2. GECS has rescheduled the job at least 12 times.
Once BOTH of these requirements have been met, GECS will stop trying to reschedule the job and will mark the job
complete and record an error.
Valid Time Periods
Regardless of the method of rescheduling defined for a job, you can indicate that a job should only be rescheduled
for certain hours of the day. This is sometimes referred to as ‘interval’ scheduling or “Valid Times” your job can
run. For example:
Reschedule the job to the time that is 23 hours after the last start time, but between 15:30:00 and 20:30:00
and on conflict reschedule.
or
Reschedule the job to the time that is 1 hour after the last finish time, but only between 8:00:00 and
17:00:00 or 23:00:00 and 05:00:00 and on conflict wait.
When GECS encounters a conflict where the principle job scheduling rules generate a time that is contrary to the
valid times, they either:
1. Reschedule the job for the beginning of the first valid period after the invalid scheduled time (wait).
2. Reschedule the job again until the resulting time is in a valid period (reschedule).
Using the first example above, if the job starts on Friday at 23:00:00, the job would reschedule as follows:
22:00:00 Saturday Fails
21:00:00 Sunday
Fails
20:00:00 Monday
Success
As you can see, it is possible to define jobs that can’t accurately reschedule. For example:
5-7
Scheduling Jobs
Reschedule the job to the time that is 1 day after the last scheduled time, but only between the hours of 08:00:00
and 09:00:00. The job is scheduled for 07:00:00 and ran at 08:10:00 and on conflict, reschedule.
Times to Execute
The “Times to Execute” field is an optional field that can be used to limit the number of times your job can run. If you
enter a number of times to execute, you should also enter a number of “Remaining Times”. The number of
remaining times field defaults to '0'. If this is not updated, your job will think it has 'X' number of times to execute
and '0' times remaining to run. If this occurs, the job will not run at all.
Remaining Times
The “Remaining Times” field is an optional field that can be used in conjunction with the “ Times To Execute” field.
This field is decremented each time your job is executed. If you are entering a new job, these should be the same.
Job Class
The “Job Class” field can be used to accomplish two different objectives.
1. To limit the number of jobs of a given class that can be run at once.
2. To assign vacation periods to jobs of a given class.
When using the job class field to limit the number of jobs of a given class that can be run at once, you need to specify
the “Maximum jobs of a Class” in the Agent record. This will limit the number of jobs that your Agent(s) will run of
any given class.
For example, if you have your Agent set up with a maximum number of “Simultaneous Jobs” of 5, you might want to
set the “Maximum Jobs of a Class“ to 4. This would keep a single class of jobs from hogging the entire Agent. If you
have jobs you never want to have running at the same time, you could set this number to 1 and schedule the jobs with
the same class. Entering 0 will eliminate any class restrictions. You need to set up your Agent with a number of
“Maximum Jobs of a Class”.
When using the job class field with vacation periods (periods of time your job shouldn’t run even if scheduled), you
need to use the vacations screens to create a vacation period. Your job’s “job class” should then match your vacation
class.
Vacation Periods
Vacation Periods are setup to indicate periods of time when jobs of a particular class should not run, even if they are
scheduled for that time. Each vacation period is distinguished by number and the job class it applies to. You must
enter how the job should behave when it encounters a conflict with the vacation period. The system can keep the job
pending until the vacation period ends, or it can reschedule it as if it ran. You also need to setup how the vacation
5-8
Scheduling Jobs
period should repeat when it completes. For many situations, vacation periods may not be necessary. Note that
vacation periods are not taken into account when viewing job schedules.
Trigger Files
Jobs can depend on the presence or absence of single or multiple files. These files are relative to the Agent machine.
Use the Trigger File(s) field to tell the Agents to look for a filespec and only dispatch your job if the criteria specified
in the Execute if field is true and optional Minimum File Size field is true. For example:
F:\GECS\TEST.DAT
If the Trigger File(s) field is left blank, GECS will not check for any files. Drive letters or UNC are acceptable. This
field is limited to 128 characters. All files are relative to the Agent.
Multiple files may be specified, separated by semi-colons (much like the DOS PATH command). Special GECS
substitution variables can also be used. For example:
F:\GECS\file1.txt;F:\GECS\file2.txt;F:\GECS\@MO@DA@YEARL
However, only one fully qualified file may be specified in the Trigger files field when using the Minimum File Size
option. Minimum file size is not supported when using multiple files in the Trigger Files field.
If you want a job to run every day when a file appears, simply schedule the job to repeat daily, at a time earlier than
when you expect the file to appear. The job will wait for the trigger file, run, and then reschedule for the next day.
When trigger file dependencies have not been met, the reasons Why This Job Cannot Run will temporarily display
Unable to Find Any Required File. Keep in mind that GECS will check again for this file each time the GECS
pulses.
The Agent must be running and the Agent machine must have sufficient rights to access files entered into this field.
Insufficient security rights can cause trigger file dependencies to fail. Rights include: read, write create, erase
modify and file scan.
Trigger File Command Line Utilities
The GECSCHNG command line utility allows dependencies on files changing. The GECSSIZE command line
utility will wait for a file size to change before returning. See your GECS online manual for more details.
File Dependency Caveats
Wildcards
Our file dependencies scheme is designed to handle fully qualified filenames WITHOUT wildcards. By accident,
not by design, our file dependencies scheme will handle filenames with wildcards in a limited number of situations.
Wildcards can be used ONLY with 'if no files exist' and with 'if any files exist'. You may receive unexpected results
in any other situation.
Sharable/Exclusive
Sharability and exclusivity are concepts in the 'Microsoft file system' world. In general they have no parallel in the
'Unix file system' world. We have implemented them under Unix as follows:
Sharably If we can 'open(name, O_RDONLY)' the file, it can be accessed 'sharably'. If for some reason we can't
'open(name, O_RDONLY)' it, it cannot be accessed 'sharably'.
Exclusively For all the Unixes, except AIX, exclusivity is based on locks. If we can 'flock(fd, F_TEST, 0)' the entire
file, it can be accessed 'exclusively'. If for some reason we can't 'flock(fd, F_TEST, 0)' the entire file, it cannot be
5-9
Scheduling Jobs
accessed ' exclusively'. For AIX, exclusivity is based on the 'non sharable' bit that can be set when files are opened.
If we can 'open(name, O_RDONLY | O_NSHARE)' it, the file can be accessed 'exclusively'. If we can't
'open(name, O_RDONLY | O_NSHARE)' it, the file cannot be accessed 'exclusively'.
In general, it is not recommend that you use sharable or exclusive on Unix Agents unless you fully understand what
they mean.
NLM
The NLM Agent doesn't support file dependencies at all.
Any vs. All
Understanding as described above that the scheme was designed for fully qualified file names, WITHOUT
wildcards, the concepts of 'Any' and 'All' are implemented around the ability of the user to put multple filenames on
the 'file dependencies' line, for example:
filename1;filename2;filename3
If the desired condition, for example 'exists', is TRUE for either filename1, filename2 or filename3, then the
condition 'any exists' would be true. If the desired condition, for example 'exists', is TRUE for filename1 and
filename2 and filename3, then the condition 'all exists' would be true.
Execute
Use the “Execute” field to tell GECS whether or how to look for the filespec specified in the “Trigger File(s)” field.
Indicate whether this job should only run:
• if no file exists
• if any file exists
• if any file can be opened sharable
• if any file can be opened exclusively
• if all the files exist
• if all files can be opened exclusively
• if all files can be opened sharable
This field is only valid if the 'Trigger File(s)' field is filled in, otherwise it is ignored.
The exclusive options work well when required files may not yet exist in their entirety. For example, files in the
process of being copied or transferred. However, by design, wild card characters are not allowed as trigger files if
any or all files can be opened exclusively.
Minimum File Size
Use the “Minimum File Size” field to specify the minimum file size in bytes required for this job to meet the trigger
file(s) requirement specified.
This is an optional field and is only valid if the 'Trigger File(s)' field is populated, otherwise it is ignored.
File Contents Change Utility
The “GECSCHNG” utility allows dependencies on file contents “changing”. This program accepts a file name as
an argument. When GECSCHNG.EXE first starts, it records (in memory) the time/date stamp of the file that was
passed on the command line. It then periodically checks the time stamp of the file. When the time stamp does not
match the one in memory, that means the file has been edited/changed. At that point GECSCHNG.EXE returns a
zero to the OS and terminates. If the file passed on the command line cannot be found, GECSCHNG.EXE returns a
non-zero value and terminates. See the Command Line utility Chapter for more details. The syntax for use is:
5-10
Scheduling Jobs
GECSCHNG filespec
where filespec is the fully qualified path of the file to be watched. For example:
C:\GECS\GECSCHNG C:\TESTFIL.TXT
File Size Change Utility
The “GECSSIZE” utility allows dependencies on file size “changing”. This program accepts a file name as an
argument. When GECSSIZE.EXE first starts, it records (in memory) the size of the file that was passed on the
command line. It then periodically checks the size of the file. When the size does not match the one in memory, that
means the file has been changed. At that point GECSSIZE.EXE returns a zero to the OS and terminates. If the file
passed on the command line cannot be found, GECSSIZE.EXE returns a non-zero value and terminates. See the
Command Line utility Chapter for more details. The syntax for use is:
GECSSIZE filespec
where filespec is the fully qualified path of the file to wait for a size change. For example:
C:\GECS\GECSSIZE C:\TESTFIL2.TXT
Job Dependencies
Job Dependencies force your jobs to run in sequence. When defining a job that needs to run after one or more other
jobs, GECS allows you to use job dependencies. You can assign up to 10 job dependencies for each job. Each
dependency may be set up to require successful completion of dependent jobs, a delay between dependent jobs and
completion of dependent jobs within a specified amount of time. When scheduling dependent jobs that repeat, each
job should be set up with the same repeat schedule.
Predecessor Job Parameters
When defining a job that needs to run after one or more other jobs, you can enter a variety of parameters in addition
to the job numbers of the jobs that need to run first. The parameters are: Depends on Job, Operation on Return Code,
Job Delay and Within Hours.
The “Depends on Job” fields indicate the job that must run before this job can run.
The “Operation on Return Code” fields indicate the value that the predecessor job must return, before this job can
run. If the predecessor job returns 0 when it’s successful and non-zero when it encounters a problem, you would
want to indicate that the predecessor job’s return code should be ‘= 0’.
The “Job Delay” fields are used to indicate the minimum amount of time that must have lapsed since the predecessor
job finished. For example, if your job stream needs a minimum 30 minute wait between the jobs, you would enter
‘00:30:00’.
The “Within Hours” fields are used to indicate the maximum amount of time that may have lapsed since the
predecessor job finished. For example, if the predecessor job runs every day and this job runs every Friday, you
would want to put in a Within Hours value 8 hours to make sure that the predecessor job has run in the last 8 hours.
This would insure that this job ran after the Friday occurrence of the predecessor job, and not before the Friday
occurrence (after the Thursday occurrence).
5-11
Scheduling Jobs
Depends On Event
The Depends On Event field is used to keep a job from running until specified Events occur. Enter the number of the
Event this job depends on. Up to 10 Events can be entered. This job will not run until each Event listed has occured.
Resource Requirements
Resources represent hardware, software or other things (hardware or software, physical or logical) that are needed
by jobs. Resources are limited in quantity either because only certain Agents have them or there is a limited quantity
of them on the system. Consequently, resources are either assigned to specific Agents or they are system wide
resources.
Each resource is defined with a unique name and optional Agent name. When you want to define a system resource,
you simply leave the Agent name portion blank. You cannot have a system resource and Agent resource with the
same name. Besides the resource and Agent names, you must indicate the maximum number of simultaneous jobs
that should be allowed to use this resource. For resources that are assigned to Agents, this maximum is for that
Agent. For system resources, this maximum is across all running Agents. The use of resources are typically only
needed on complex multi-Agent installations and therefore, are not needed for all systems. For example: A system
resource for limited database logins.
Job Requirements
Each GECS job can be setup to run on specified Agents or on Agents belonging to specified Agent groups. Use the
Requirements tab from the job record to setup requirements for your jobs.
Execute By Agent
The execute by Agent fields are used to limit your job to only run on one of the Agents listed. You may specify
up to 10 Agents. This job will run on the first available Agent.
Use Agent Group
This optional field is to be used in a multi-Agent environment. If your job should only be executed by Agents
that belong to a particular Agent group, enter that group name in this field. For example: This group of Agents
have special software configured.
Login as Specified User
Enable the login as specified user field if you would like your job to login as a specified user before running.
When this field is enabled, you must specify the login user account name and password to be used. You must
also edit the GECS user record and enter the appropriate user name and password. The login as specified user
works when your Agent is configured to run as a service.
When a job is exported into a text file via the GECSDUMP utility, the login password is not exported.
5-12
Scheduling Jobs
Job Priority
In the event that two or more jobs are scheduled to begin at the exact same date and time, you may use job priorities
to yield execution to higher priority jobs. Priority takes precedence over lateness. Priority is set using values 0-9;
where '0' is the highest possible priority and '9' is the lowest. For example:
When jobs are scheduled to run at the exact same time, a job with priority = '0' will execute before a job with priority
= '9'. Job priority can be set for each job by filling out a value in the job “Priority” field found on the job Actions tab.
Priority can be escalated based on job lateness as well.
Maximum job priority can additionally be set for each GECS user. You can set “Maximum Priority” from the
Profile tab in user record. If you enter '5' for a user’s maximum priority, the user will only be allowed to add jobs
with a priority of '5' through '9'.
Minimum Disk Space
Use this field to indicate the minimum disk space that must be available for this job to run. The disk space is
checked, by the Agent, on the drive specified in the 'Start In Directory' field if one exists, otherwise the current drive
is checked. Disk space is relative to the Agent. The minimum disk space field can be found on the Requirements tab
in the Job record screens.
Things that keep jobs from running
There are a variety of things that may keep your jobs from running.
- Trigger File Dependencies
- Job Dependencies
- Resources Requirements
- Job Requirements
- Vacation Periods
- Minimum Disk Space Requirement
- Events
Resolve Scheduling Issues
When necessary, you can determine why a job won’t run, run a job ignoring dependencies, skip and reschedule a
job, rerun a job, change a completed job’s return code and much more.
5-13
Scheduling Jobs
5-14
Events
Events
6-1
Events
6-2
Events
Events
Events are things that can cause a job to run or things which may require special notice. Events can be generated by
the GECS system or they can be user definable. Such as Job started, Job finished with bad return code or Agent set to
offline. Each Event is numbered and contains parameters to allow for special notifications. These notifications
include: email, SNMP, network message, Windows event logging, job activation, audible wav file, and color
highlighting in the GECS Administrator’s Events lists. Use the Event Definitions folder to update Event
parameters.
Event Definition Details can be modified using the GECS Administrator client program to configure the special
notifications mentioned above.
Depending on how you use the GECS system, many Events you will not care about and others you will want to know
about if they occur.
Scroll through your list of Event Definitions and edit them where you deem necessary.
More examples of Events include things associated with the GECS system such as an Agent set to online, job
completed successfully or a job finished with a problem. Events that are user definable may be associated with out
side events or other systems. For example, you could create your own Event for a file transferred from your
mainframe. This Event could cause one of your GECS jobs to run.
Jobs can depend on the occurrence of up to 10 specified Events. When configured, jobs will not run until each Event
listed has occurred since the last time the job has run. Events can also be used to link GECS Batches together. Set
the last job in the first Batch to generate an Event that the first job in the second Batch requires.
Specified Jobs can generate an Event on successful completion or failure.
When an Event occurs the following information may be provided about the Event.
Event Edit
Events associated with GECS jobs can be generated if a job is late, when a job starts, when a job finishes and many
more. Job Events are defined in Event Definitions but can be turned off individual jobs using the “Should this job
create Events” field from the Actions tab in the job record.
Generated By - Displays the name of the GECS component that generated this Event. The components can be any
of the following: DBMS, Controller, Agent, Web Manager, Administrator client program or Other.
Priority - Displays the priority that was assignted to this particuar Event in the Event Definition.
Component - Displays the specific name of the GECS component that generated this Event. For example, the
Event may be Generated By an Agent but the specific name of the Agent is AGENT2.
Job Number - Displays the name of the GECS job associated with this Event, if one exists.
Began - Displays the date and time this Event was generated.
Ended - Displays the date and time this Event ended.
Message - Displays the alert message that was defined for this Event in the Event Definition.
Status - displays the status of this particular instance of this Event. The status is either open or closed. You can
update the status when you have determined that this Event has been taken care of or is no longer an issue. The
Status of an Event can be updated in the Event Definition to be Closed as soon as it occurs.
Closed By - This field should be populated with the name of the person who closed this instance of this Event. When
an Event is Created Closed in the Event Definition, the Closed By name is SYSTEM.
6-3
Events
Comment - This field can be used to enter any comments about this particular instance of this Event.
Event Follow up
Once an Event has occurred, you can follow up with the Event by updating the Event’s “Status” from open to closed.
GECS automatically logs the GECS user who closes the Event. You can also include optional comments with this
follow up. By following up with Events that occur you can save the Event information while at the same time
documenting that the Event has been taken care of by closing it. Closing Events also allows you more flexibility in
filtering the Events you wish to display in your Event View lists.
Viewing Events in Lists
Use the GECS Administrator program to check the status of your GECS jobs and system by viewing your Events.
The Administrator program will display Event views by double clicking on the “Events” folder. You can use the
default “All Events” view to display a list of All Events.
The last column on the right side of the Events list displays the status of each Event. The status is either open or
closed. Next to the status will be a green or red dot. This color indicates whether this Event is included in your
User’s Events view. A red dot mean that the Event exists in your User’s Events view. A green dot means that the
Event is not included in your User’s Event view.
You can view all Events associated with each job from the job detail screen via the “This Job’s Events” toolbar
button.
The Event lists are moveable, sizable and configurable. You may wish to filter the Events displayed in these list or
create you own views and customize them. To customize your views, right click on the view name and select View
Properties.
By double clicking on an Event from this list you can display the Event Edit information.
Right clicking on a job from the list will give you additional options such as:
Close Event - Update the status of the Event from open to closed.
Delete Event - Delete the Event from the GECS system.
Remove My Name - Remove this Event from my User’s Event View list (in other Views that may still display
this Event, this will also change the color of the status dot from red to green).
View Event Detail - Display the Event Edit information screen.
From the GECS Administrator, double click on the Events folder then click on the default view “All Events”. You
should see a list of Event records.
User’s Events View and the Event Indicator
In the GECS Administrator Client Program there is a special Event View named ‘User’s Events’. Information
displayed in this view controls the ‘Event Indicator’ button at the bottom right corner of the Administrator window.
When Events are displayed in the ‘User’s Events’ view, the ‘Event Indicator’ button is red. When Events do not
exist in the ‘User’s Events’ view the ‘Event Indicator’ button is green.
6-4
Events
You can click on the Event Indicator button to quickly jump to the User’s Events list. If you wish to be notified of various
Events and have them included in your User’s Events list, update the Event Definition and include you GECS User name in
the ‘Send Alerts to’ field. This will cause the occurrence of this Event to display in your User’s Events view. You can clear an
Event from your view by either “Removing your Name” from the occurrence of the Event or Delete the Event. If you delete
the Event it will obviously no longer show up in anyone’s Events list.
Event Definitions
Events are defined in the GECS system using the Windows Administrator Client program using the Event Definitions
module. Each Event is assigned a unique Event number. GECS system Events are numbered from zero to 500 and cannot be
deleted. User definable Events can be numbered starting from 1000. Event Definition parameters are defined below.
Event Tab
Description - an optional field to enter a brief description of the Event.
Color - Fore/Back - You can modify the foreground and background colors of your Events that will be displayed in your
GECS Events lists. This can help make special Events stand out in the lists.
Create Event -You can enable this field if you wish to have this GECS Event created and displayed in your GECS Events
lists.
Create Closed - You can enable this field if you wish to have this GECS Event’s status automatically closed when it is
created.
Priority - You can use this field to set this Events Priority to be used for filtering in the lists displaying this GECS Event (0 =
highest, 9 = lowest). Priority is commonly used to filter Users Events to display only high priority Events.
Activate Job - Use this optional field to activate a selected GECS job to be activated if this Event occurs.
WAV Filename - Use this optional field to enter a fully qualified wav filename to be played at your GECS DBMS machine
when this Event occurs.
Alert Message - By default this field contains a short description of this GECS Event. This description is displayed in your
Events list and is used when no Message is entered in the mail and network messages fields for this Event. You can use this
optional field to enter a customized alert message to display if this GECS Event occurs.
Send Alerts To - Use this optional field to enter up to five GECS user or GECS user mail group names of people to be sent
GECS Alerts if this GECS Event occurs. The GECS user or mail group must be defined in the GECS user record. GECS Mail
groups are defined in the user record on the Mail tab. Examples of GECS user or mail groups include: *ADMIN,
JAMES_SMITH, GINA and/or *OPERATIONS. Sending an Alert will cause this Event to be displayed in the specified
Users Events folder. The * asterisk denotes GECS User ‘Mail Group’ names.
Mail Tab
Subject - Use this optional field to enter a customized subject for the email message to be sent to the specified people if this
GECS Event occurs.
Message - Use this optional field to enter a customized email message or short description of this Event to be sent to the
specified people if this GECS Event occurs. If you do not enter a message in this field, the Alert Message from the Event tab
will be used.
6-5
Events
Send Mail To - Use this optional field to enter the GECS User Name of up to five people to be sent notifications that
this GECS Event has occurred. For GECS Job related Events, you can enter %USER% into these fields to use the
names specified on the Jobs GECS Users or Groups to Notify fields. For example, %USER1%, %USER2%,
%USER3%, %USER4% and/or %USER5%. This allows each Job to specify different users to be notified of the
particular job related Event.
Network Tab
Network Message - Use this optional field to enter a customized network message or short description of this Event
to be sent to the specified people if this GECS Event occurs. If you do not enter a message in this field, the Alert
Message from the Event tab will be used.
Send Message To - Use this optional field to enter the Network User names of up to five people to be sent network
messages if this GECS Event occurs.
Generate Windows Event Log - GECS can interface with the Windows Event Log. Enable this optional field if
you would like to generate a Microsoft Windows Event Viewer Log for this GECS Event if it occurs. You can use
the Windows Event Viewer to see the Events.
Windows Event Type - Use this optional field to select the Windows Event type you would like displayed in the
Microsoft Windows Event Viewer for this Event when this GECS Event occurs. Your options are; Information,
Warning or Error.
Windows Event Message - Use this optional field to enter a message that you would like to appear in the Microsoft
Windows Event Viewer when this GECS Event occurs. If you do not enter a message in this field, the Alert Message
from the Event tab will be used.
Generate SNMP - Enable this optional field if you want GECS to Generate an SNMP Trap when this GECS Event
occurs.
Trap Number - Use this optional field to enter an SNMP Trap Number to use when this GECS Event occurs. This
number will be an Enterprise Specific Trap number. Valid numbers are 0 to 4 billion.
SNMP Trap Message - Use this optional field to enter a SNMP Trap Message for this GECS Event number. If you
do not enter a message in this field, the Alert Message from the Event tab will be used.
Adding User Event Definitions
You can add User Event Definitions from the Administrator program, Event Definitions module. User definable
Events can be numbered starting from 1000.
Generating User Defined Events
Once you have defined an Event, GECS can generate your Event when you specify to generate it based on job
success or job failure. Use the Events fields located on the Actions tab of the job record to have GECS automatically
generate Events. Likewise, you can generate Events using the GECSEVNT command line utility. See the
Command Line Utilities chapter of this manual for more details.
6-6
Events
Event Definitions List
The Event Definitions List displays all defined GECS System and User Events. GECS System Events include:
0 No alert
1 OS error
2 TCP/IP error
3 Error changing window
4 Communications timeout
5 Invalid packet signature
6 Invalid packet name
7 Access denied
10 Added job from WRK file
11 No colon in wrk file line
12 No user name in wrk file
13 Invalid user name in wrk file
14 Bad mail username in wrk file
15 No command line in wrk file
16 Copied wrk file to BAD file
17 Can’t copy wrk to BAD file
18 Error creating wrk file
20 Controller is licensed
21 Unable to read license info
22 License expired
23 Agent set offline for bad OS
30 MAPI logon error
31 MAPI send error
32 VIM error
40 Scheduled batch
41 Removed batch
50 Job late
51 Job start
54 Job complete
55 Job failed due to ctrl stop
56 Bad return code
57 Over run max job minutes
58 Overrun est job minutes
59 Under run max job minutes
60 Under run est job minutes
62 Manual skip and reschedule
63 Job terminated by user
64 Job terminated due to overrun
65 Job overrunning est. Minutes
66 Executed ignoring dependency
67 Activated due to failure
68 Activated due to lateness
69 Resched. due to vacation
70 Completed due to vac. Period
71 Deleted due to vac. Period
72 Resched due to invalid period
73 Complete due to inv. Period
74 Deleted due to invalid period
75 skipped due to late start
76 Resched due to late start
77 Skipped due to late finish
6-7
Events
78 Resched due to late finish
79 Pre job message
80 Post job message
81 No special schedule dates
82 Unable to reschedule job
83 Re-ran job
84 changed return code
85 Set job to terminate
86 Terminated by message
100 Controller online
101 Controller offline
102 Controller start
103 Controller stop
104 Controller reset
106 Controller paused by file
107 Controller halted by file
108 Controller exited by file
109 Controller unpaused
110 Received pause message
111 Received unpause message
112 received quit message
113 Received test message
114 Received minimize message
115 Received hide message
116 Received show message
117 Unable to substitute
118 Unable to reschedule vacation
120 Controller name too long
121 controller name undefined
200 Agent no online & responding
201 Agent set to offline
202 Agent not responding
203 Agent set to not process jobs
205 Agent start
300 DBMS online
301 DBMS offline
302 DBMS start
303 DBMS stopped
304 Database error
305 Data backup started
306 Databackup error
307 Data backup complete
308 SMTP error
309 Bad SMTP request
310 Bad SMTP authentication
400 Web Manager online
401 Web Manager offline
402 Web Manger started
403 Web Manager stopped
6-8
Events
Setting Up Event Email Notifications
GECS logs into the mail system when a notification is required. Email systems must be installed and tested at the
DBMS machine prior to setting up Global ECS. Vinzant recommends using a unique mail account for GECS.
GECS users can be created solely for notification. Up to five GECS users or GECS Mail Groups can be selected for
each Event notification. Press the F1 key in any field for more information.
In order for GECS to interface with your mail system you must add a user to your mail system for GECS.
Notifying Users Via Microsoft Mail
GECS can interface with the MS Mail systems via MAPI. GECS uses the MAPI interface to access MS Mail and
Exchange. Because the MAPI interface is used, GECS should be able to interface with any mail system that has a
MAPI driver, though GECS has only been tested with the MAPI interface for MS Mail and Exchange. The MAPI
driver must be installed before GECS can interface with the mail system. The MAPI interface is included as part of
the mail system and consequently, the MS Mail client software must be installed on any computer that is acting as
your DBMS. Microsoft mail will only work when your DBMS is running from a desktop icon. Microsoft mail will
not work if your DBMS is running as a service.
To setup Microsoft MAPI mail systems: Exchange, Outlook, etc.
MS Profile names maintain the email friendly name, password and post office directory.
DBMS Settings:
1. Go to the DBMS Settings screen and set ‘Mail System’ to Microsoft Mail
2. Populate the ‘Mail User Name’ field with the desired Microsoft Profile Name using the exact Profile syntax
(upper and lower case make a difference). To verify the MS Profile Name: Right click on Desktop MS Mail Icon.
Select Properties. Click on “Show Profiles”.
3. Leave the ‘Password’ field and ‘Mail sub directory’ fields blank then save the record (the password field will
automatically be filled in with asterisks).
Event Definitions:
1. On the Event Definitions Mail Tab, enter a ‘Subject’ for this particular Events Mail ‘message’ then enter a
message about this Event in the Message field.
2. Specify up to 5 GECS users or GECS User Mail Groups to be notified of this particular Event then save and exit
the record.
GECS User Records:
1. For the desired GECS user, go to the user record and click on the Mail tab
2. Populate the “Mail User or Address” with the email account associated with this GECS User. Enter the name
exactly as you would in the Mail system.
3. Enter an option GECS mail Group Name.
Notifying Users Via cc:Mail
GECS can interface with the cc:Mail mail system. GECS uses the VIM interface to access cc:Mail. The Windows
VIM drivers are implemented as DLLs. These DLLs are provided by mail system vendor (IBM for cc:MAIL) and
consequently a copy of the Windows cc:Mail must be installed on the computer that is acting as your DBMS. The 32
bit VIM drivers (VIM32.DLL) are required for Windows. cc:Mail version 8 and higher use MAPI, see the Microsoft
mail section for details.
6-9
Events
Notifying Users Via Lotus Notes Mail
GECS can interface with the Lotus Notes mail system. GECS uses a VIM interface to access Lotus Notes. The
Windows VIM drivers are implemented as DLLs. These DLLs are provided by mail system vendor and
consequently a copy of Lotus Notes Mail must be installed on the computer that is acting as your DBMS. The 32 bit
VIM drivers (VIM32.DLL) are required for Windows. C:\Notes must be in the DBMS computer’s search path.
Set up Instructions for Sending Lotus Notes Mail:
It is required that the GECS DBMS machine System Environment Path includes the local Lotus Notes programs
directory. For example, “C:\NOTES”.
DBMS Settings:
1. Go to the DBMS Settings screen and set Mail System to Notes Mail
2. Leave the Mail User Name field and Mail Subdirectory fields blank
3. Populate the password field and press the Enter key. Note: Asterisks will be displayed. Save the record.
4. Use the instructions given above in the setting up Microsoft mail section to configure the Event Definitions and
GECS User records.
Submitting GECS Jobs via inbound Lotus Notes mail is not supported at this time.
Notifying Users Via Internet Mail
GECS can interface with Internet Mail (SMTP / POP3). A copy of TCP/IP sockets drivers must be installed on the
computer that is acting as your DBMS.
To setup GECS for Internet Mail:
DBMS Settings:
1. Go to the DBMS Settings screen and set ‘Mail System’ to Internet Mail
2. Populate the ‘Mail User Name’ field with the Internet address to be used to send Event notification.
3. Populate the ‘Password’ field and press the Enter key. Note: Asterisks will be displayed.
4. Leave the ‘Mail sub directory’ field blank and save the record..
5. Use the instructions given above in the setting up Microsoft mail section to configure the Event Definitions and
GECS User records.
Notifying Users Via MHS Mail
When GECS notifies users of Events, it sends an SMF-64 format message. The message is not locally delivered. It
is written to the \MHS\MAIL\SND subdirectory. An MHS server is required to deliver the message to the user.
GECS has been successfully tested with MHS 1.5 and NetWare Global Messaging.
For MHS installations, the mail user name MUST be 8 characters or less in length.
The message sent for Event notification is in the format:
SMF-64
From:Controller_mhs_name
To:users_mhs_name
Subject:GECS Notification
Job n Returned n - job_title
6-10
Events
Mail Issues
Microsoft Mail Issues
A copy of the MS Mail client software must be installed on the computer that will act as your GECS DBMS.
When using MS Exchange as your email delivery system, profiles are used instead of directly using mail user
names. To enable GECS to logon to MS Exchange, a profile created specifically for GECS MUST be used. MS
Exchange profiles created on Windows are owned by the user who is currently logged in and may be viewed only by
that user. Therefore, in order for GECS to access MS Exchange, profiles must be created so that the user account
that you created for GECS has access to the profile.
To enable mail to work with MS Exchange, choose MS Mail from the Mail System list and in place of the Mail User
Name and Password, enter the profile name created for GECS. Leave the Mail Subdirectory field blank.
Mail sent by GECS will use the Mail User Name entered in each GECS User record. These User record fields must
contain your mail systems user names NOT profile names.
cc:Mail Issues
A copy of cc:Mail must be installed on the computer that will act as your DBMS. VIM32.DLL is used.
MHS Version Issues
The MHS capabilities built into GECS were originally designed to work with SMF v64. This is the SMF version
implemented by NetWare MHS v1.5. With the introduction of NetWare Global MHS, Novell changed the SMF
specification and labeled it SMF v71. On the front of every MHS message is the SMF version it was created under.
GECS will read (receive) MHS messages created under any version of MHS (v64, v70, v71). When GECS creates
(sends) messages, it must put an SMF version number (signature) on the front of the message. By default, it uses
“SMF-64" as the signature. NetWare Global MHS will not send messages created with this signature. It generates
an ”Invalid Version" error. Other versions of MHS may also have problems with v64 signatures. If you are using a
version of MHS that won’t send v64 messages, you must create a file named SMF.SIG that contains the signature to
be used by GECS on messages it sends. If this file exists in the Controller’s default subdirectory (\GECS) the first
six characters of this file will be used as the signature instead of “SMF-64". If you are using NetWare Global MHS
or MHS that comes with NetWare 4.x, you need to create this file using a text editor with the first six characters
being:
SMF-71
Once created, GECS will use the first six characters of this file as the signature on messages it sends.
6-11
Events
Event SNMP Trap Messages
GECS can send SNMP Trap messages when specified Events occur.
Global ECS interfaces with the Simple Network Management Protocol (SNMP) Service on Windows
NT/2000/XP/2003 in two ways. First, Global ECS can generate ‘traps’ when certain events occur. These traps are
sent to your network management software by the SNMP service. You can also use SNMP from your network
management software to query the Management Information Base (MIB) maintained by Global ECS to see what
components are installed on the computer, what their name is and whether they are running at this time. This
diagram shows how the various parts interact:
There are a large number of network management software programs available. We are not supporting any one in
particular, though over time we will develop some familiarity with the most popular ones. This paper is not about
how to configure ‘Computer A’ as shown in the diagram. We are concerned about how to configure ‘Computer B’.
Note that though it’s theoretically possible that Computer A and Computer B could be the same computer, I’ve
experienced problems sending traps from GECS to OpenView when a single computer is used. I haven’t
experienced these problems with Net-SNMP or WhatsUp when used with GECS on a single computer
configuration. I believe it has something to do with the services installed by OpenView.
6-12
Events
Configuring Computer B:
Step 1:
Install Global ECS. Do not indicate that you want to use SNMP at this time.
Step 2:
Check and see if the SNMP service is installed on the computer. It will show in the ‘Services’ screen similar to this if
it is installed. If it is installed, skip to step 4.
Step 3:
Install the SNMP service. This done slightly different on NT, 2000 and XP. On 2000 and XP, use Add Remove
Programs, Add/Remove Windows Components and click on Management and Monitoring Tools. Click Details and
check the checkbox next to ‘Simple Network Management Protocol’ and continue to install the service.
6-13
Events
Step 4:
Configure the SNMP Service. This is done slightly different on NT, 2000 and XP. On 2000 and XP, double click on
the SNMP Service line in the Services list. On NT it is done in Networking from Control Panel. The ‘Traps’ tab
must be configured with the name of your Community and the IP address where traps should be sent. This is the IP
address of the node or nodes that will be running your Network Management Software (Computer A in our
diagram). The ‘Community’ name is like a password. The SNMP services will only communicate with computers
with the same Community name.
You will also want to configure the Security tab with the access that should be allowed from others in your
Community.
Step 5:
Run Workstation Setup. Check the Checkbox to indicate you want to interface with SNMP.
6-14
Events
Step 6:
Run Administrator. Select Event Definitions and edit the events for which you want GECS to generate SNMP
Traps. Enter the trap number and text to be sent. You may want to select different trap numbers based on how you
use your network management software.
Step 7:
Test to see that GECS is sending traps properly.
Go to ‘Computer A’.
Be sure the ‘SNMP Trap Service’ is stopped.
Create the C:\GECS\SNMP subdirectory.
MD \GECS
MD \GECS\SNMP
Change to the C:\GECS\SNMP subdirectory
CD \GECS\SNMP
Copy the C:\GECS\SNMP subdirectory from Computer B to Computer A.
COPY \\computerB\C$\GECS\SNMP\*.*
Start the SNMPTRAPD software using the supplied batch file:
GETTRAPS
Go back to ‘Computer B’.
Run GECS Admin and edit the ‘Controller Start’ event (102) in Event Definitions.
Change to the ‘Network’ tab.
Check the box to send SNMP traps.
Enter a trap number (i.e. 11) and a description.
6-15
Events
Save your entries.
Exit Admin.
Start your Controller (stop it first if it’s already running).
Go back to computer A and you should see a message displayed in the SNMPTRAPD window.
Step 8:
Test to see that the GECS MIB can be queried properly.
Go to Computer A.
Change to the C:\GECS\SNMP subdirectory (created in Step 7 above).
CD \GECS\SNMP
Query the MIB by entering:
DISPMIBS ipname community
where ipname is the name or number of Computer B and community is the community name you use for SNMP. For
example:
DISPMIBS 192.168.0.100 public
You will see information from the MIB similar to:
enterprises.vinzant.products.gecs.isGECSDBMSInstalled.0 = Yes(1)
enterprises.vinzant.products.gecs.GECSDBMSName.0 = “DBMS”
enterprises.vinzant.products.gecs.isGECSDBMSRunning.0 = No(0)
enterprises.vinzant.products.gecs.isGECSControllerInstalled.0 = No(0)
enterprises.vinzant.products.gecs.GECSControllerName.0 = “unknown”
enterprises.vinzant.products.gecs.isGECSControllerRunning.0 = No(0)
enterprises.vinzant.products.gecs.isGECSWebMgrInstalled.0 = No(0)
enterprises.vinzant.products.gecs.GECSWebMgrName.0 = “unknown”
enterprises.vinzant.products.gecs.isGECSWebMgrRunning.0 = No(0)
enterprises.vinzant.products.gecs.isGECSAgentInstalled.0 = Yes(1)
enterprises.vinzant.products.gecs.GECSAgentName.0 = “CALVIN”
enterprises.vinzant.products.gecs.isGECSAgentRunning.0 = No(0)
As shown, the 12 lines are actually 4 groups of 3 lines organized like this:
MIB Information
Meaning
isGECSDBMSInstalled.0 = Yes(1)
DBMS installed?
GECSDBMSName.0 = “DBMS”
DBMS name?
isGECSDBMSRunning.0 = No(0)
DBMS running?
isGECSControllerInstalled.0 = Yes(1)
Controller installed?
GECSControllerName.0 = “CONTROL”
Controller name?
6-16
Events
isGECSControllerRunning.0 = No(0)
Controller running?
isGECSWebMgrInstalled.0 = Yes(1)
WebMgr installed?
GECSWebMgrName.0 = “WEBMGR”
WebMgr name?
isGECSWebMgrRunning.0 = No(0)
WebMgr running?
isGECSAgentInstalled.0 = Yes(1)
Agent installed?
GECSAgentName.0 = “CALVIN”
Agent name?
isGECSAgentRunning.0 = No(0)
Agent running?
Each group represents a particular GECS component. The first group corresponds to the DBMS, the second to the
Controller, the third to the Web Manager and the fourth group to the agent. The first line of each group indicate
whether the component is installed in this computer. A 0 indicates that it’s not installed and a 1 indicates that it is
installed. The second line of each group indicate the name of the component. The third line of each group indicate
whether the component is running at this time. A 1 indicates that it’s running and a 0 indicates that it’s not running.
You can also use your network management software to see the Management Information Base (MIB) maintained
by GECS.
The objectID to use for querying the MIB is:
1.3.6.1.4.1.10884.1.1
or
iso.org.dod.internet.private.enterprises.10884.1.1
or
iso.org.dod.internet.private.enterprises.vinzant.products.gecs
The ‘private enterprise number’ 10884 is registered to Vinzant, Inc.. The next number (1) corresponds to ‘Products’
and the next number (1) corresponds to ‘GECS’. A MIB named C:\GECS\SNMP\GECS-MIB is included. You
should be able to use this file with your network management software.
Step 9:
Install your Network Management Software if you haven’t already on ‘Computer A’.
6-17
Events
Net-SNMP Utilities
Installation Tips:
GECS includes two programs, SNMPTRAPD.EXE and SNMPWALK.EXE, from the Net-SNMP utilities for
Windows NT. See the SNMPLICE.TXT file for license information. The complete set of shareware programs is
available off the internet.
The Zip file that includes the two programs can be found at
http://net-snmp.sourceforge.net as ucd-snmp-4.2.3-win32.zip Note that the SNMPTRAPD.EXE program does
NOT want the ‘SNMP Trap Service’ to be running.
Viewing SNMP Traps Sent from GECS
If you have installed HP OpenView on this computer, be sure to stop the ‘SNMP Trap’ service and the two ‘SNMP
Emanate...’ services that are installed by Openview.
C:
CD \GECS\SNMP
GETTRAPS
Viewing the MIB:
If you have installed HP OpenView on this computer, you must START the two ‘SNMP Emanate...’ services that
are installed by Openview.
C:
CD \GECS\SNMP
DISPMIBS machine community
Change ‘machine’ to the IP name or number of the machine whose MIB you’d like to view and change ‘community’
to the community you are using for SNMP (i.e. public).
HP OpenView Network Node Manager
Installation Tips:
Install as per the installation guide. Pay attention to the ‘preinstallation’ steps to follow. You MUST reinstall all
available Service Packs for NT/2000/XP/2003 after installing OpenView. If OpenView GPF’s on startup, you
haven’t installed sufficient Service Packs. Note that this program DOES want the ‘SNMP Trap’ and ‘SNMP
Emanate...’ services to be running.
Loading GECS-MIB into OpenView
Click ‘Options’ and ‘Load/Unload MIBs:SNMP’.
Click ‘Load’
6-18
Events
Enter:
Location: C:\GECS\SNMP
Click ‘Open’
File name: GECS-MIB
Click ‘Open’, ‘Ok’, ‘Ok’ and ‘Close’
Viewing SNMP Traps Sent from GECS
Click ‘Options’ and ‘Event Configuration’.
Slide down the top list & click on the ‘gecstraps’ Enterprise.
Click ‘Edit’, ‘Events’ and ‘New’.
Enter:
Event Name: TestEvent (no spaces)
Enterprise: gecstraps
Generic Trap: Enterprise Specific
Specific Trap Number: 11 (the number of the trap being generated in GECS)
Description: Test Trap from GECS
Click ‘Next’.
Click ‘All sources’ and ‘Next’.
Click ‘Log and display in category’ and select ‘Application Alert Alarms’.
Enter:
Severity: Normal
Event Log Message: Received trap: generic #$G specific #$S. $# args: $*
Click ‘Next’
Click ‘Next’
Click ‘Next’
Click ‘Finish’
Click ‘File’, ‘Save’ and ‘File’, ‘Close’ in the ‘Event Configuration’ window.
Generate the trap from GECS.
In the ‘Alarm Categories’ dialog box, click on the button next to ‘Application Alert Alarms’.
You should see the GECS generated ‘Alarm’ in the list.
6-19
Events
Viewing the MIB:
Start HP OpenView Network Node Manager. Click Options, MIB Application Builder:SNMP, Edit and New.
Enter:
Application ID: GECS
Application Type: Form
Application Title: GECS Information
‘Next’
Add the ‘fields’ to the form:
‘Add’
MIB object ID: .iso.org.dod.internet.private.enterprises.vinzant.products.gecs
Click on isGECSDBMSInstalled (the first entry in the section).
With the mouse, slide the list down so you can see isGECSAgentRunning (the last entry in the section).
Press down the Shift Key.
With the mouse, click on isGECSAgentRunning (the last entry in the section).
All 12 of the GECS entries should be highlighted.
Click ‘Add’
‘Close’
When complete press ‘Next’
Menu path: Configuration->GECS
Selection Rule: (isSNMPSupported || isSNMPProxied)
‘Finish’
Close the MIB Application Builder:SNMP
Highlight a computer on the network map that has been configured to use SNMP with GECS.
Click ‘Configuration’ and ‘GECS’.
The information from the MIB will be displayed.
What’s Up Gold
Installation Tips:
Install as per the installation guide. Note that this program does NOT want the ‘SNMP Trap Service’ to be running.
Check in ‘Services’ and stop it, if it is running.
6-20
Events
Loading GECS-MIB into What’s Up Gold:
Change to the WhatsUp subdirectory
C:
CD “\Program Files\WhatsUp”
Load the GECS-MIB information
MIBEXTRA C:\GECS\SNMP\GECS-MIB
Ignore any ‘Failed to open DEFS.TXT’ error messages.
Restart What’s Up Gold, if running.
Viewing SNMP Traps Sent from GECS
If you have installed HP OpenView on this computer, you must STOP the two ‘SNMP Emanate...’ services that are
installed by Openview.
Click ‘Configure’ and ‘Program Options’.
Click on the ‘SNMP Traps’ category icon.
Check ‘Enable SNMP Trap Handler’ and verify the port is set to 162.
Click ‘Ok’.
Perform a GECS operation that should generate a trap.
Click ‘Logs’ and ‘SNMP Trap Log’
You should see the trap generated by GECS.
Viewing the MIB:
If you have installed HP OpenView on this computer, you must START the two ‘SNMP Emanate...’ services that
are installed by Openview.
Click ‘Tools’ and ‘SNMP Viewer’.
Enter the IP name or number of a computer that’s been configured for GECS and SNMP and click ‘Ok’.
Right click on the icon for the computer displayed and select ‘View MIB’.
Click on ‘iso.org.dod.internet.private.enterprises.vinzant.products.gecs’
on the left and you can see the MIB on the right.
6-21
Events
GECSTSND.EXE
The GECSTSND.EXE command line utility can be used to send a trap number and message. Usage:
gecstsnd index "text"
index
text
The trap index number.
The trap text to send.
For example:
GECSTSND 1115 “This is the trap message”
6-22
Monitoring & Managing
Monitoring & Managing
7-1
Monitoring & Managing
7-2
Monitoring & Managing
Monitoring the GECS System
The GECS system is designed to run unattended. However, if an Event occurs that requires notice, GECS has a
variety of ways to notify someone that they may need to do something. GECS keeps track of Events and uses Event
definitions to determine what to do when a particular Event occurs. For example, an Event such as ‘an Agent is not
responding’ could be defined to notify someone via mail, send an SNMP trap, and cause a log to be written to the
Windows event log. A Job that fails can also cause an Event to occur.
Browser Based Client Programs
You can check the status of your GECS system from anywhere in the world you have access to an Internet browser.
The web enabled programs do not require any program installation or configuration. As long as the GECS Web
Manager program is running on the DBMS/Controller machine, users with access into the GECS system can view
the status of the GECS system remotely from most any computer using an Internet browser. Users simply enter the
IP Address, HTTP Port number and name of the of GECS Web Manager. See the chapter on Web Client Programs
for more information.
GECS Windows Based Administrator Client Program
GECS Windows based Administrator Client program provides a user friendly single point of control to access the
GECS system via TCP/IP. Computers running the GECS Administrator client program must have access to the
shared directory where the GECS data files are stored (on the DBMS/Controller computer). GECS Users must be
set up in the GECS system with appropriate security enabled and their computer must be configured to run the
Administrator program. See the Getting Started chapter on configuring GECS PC’s for more details.
Events
Events are definable and configurable. There are default GECS Events such as an Agent not responding, job
finished with a bad return code, job was skipped due to lateness etc. You can optionally define your own custom
Events. See the Events chapter of this manual for more information. See the Getting Started chapter of this manual
for information on “Viewing GECS Events”.
Checking the Status of Jobs
Use the GECS Administrator program to check the status of your jobs. The Administrator program will display jobs
by clicking on the Jobs folder. You can use the default Job Sentry view to display a list of Jobs that are Pending,
Running, On Hold or Completed within one hour. The default Batch Summary view may also be used. The last
column on the right side of the jobs list displays the last Event associated with each job record. You can view all
Events associated with each job from the job detail screen via the This Jobs Events toolbar button.
The Jobs lists are moveable, sizable and configurable. You may wish to filter the jobs displayed in these list or
create you own views and customize them.
To customize your views, right click on the view name and select view properties.
By double clicking on a job from this list you can display the job detail information. Right clicking on a job from the
list will give you additional options such as the following:
7-3
Monitoring & Managing
Pending Jobs
From a list of Pending jobs, you can right click to perform the following functions:
Add new job
Delete job
View detail
Why this job can’t run
This jobs history
Copy Job As
Ignore Job dependencies
Ignore Job and File Dependencies
Respect Job and File Dependencies
Run Job As
Skip and Reschedule
Put On Hold
Running Jobs
From a list of Running jobs, you can right click to perform the following functions:
Add New Job
Delete Job
Terminate Job
View Detail
This Jobs History
Completed Jobs
From a list of Completed jobs, you can right click to perform the following functions:
Add New Job
Delete Job
View Detail
This Jobs History
Copy Job As
Run Job As
Rerun Job
Change Return Code
On Hold Jobs
From a list of On Hold jobs, you can right click to perform the following functions:
Add New Job
Delete Job
Release Hold
View Detail
Copy Job As
Run Job As
7-4
Monitoring & Managing
Customize Job And Event Views
Customize Job and Event Views so people can be as efficient as possible. Simply right click on the view to make
changes.
Create your own Job Views then use the Job View Properties to filter out specific jobs, filter to display jobs
scheduled for specific times, Batch Job summaries and much more.
Create your own Event Views then use Event View Properties to filter out specific Events, filter Events for specific
times, view open Events, Closed Events and much more.
Views can be shared with other GECS users or kept private.
7-5
Monitoring & Managing
Monitoring GECS Using a Browser
The GECS System can be monitored from remote computers that do not have any GECS programs installed or
configured. The GECS Web Manager program makes this possible.
While the Web Manager program is running on the DBMS/Controller computer, you can access the GECS data
files.
To access the GECS system from a browser, enter the IP address and port number of the Web Manager. For
example:
http://200.200.201.25:2013
Before accessing the system the user will be prompted for a GECS user name and password. After entering this
information, a web page similar to the following should appear.
In addition to using the Web Manager for access the GECS system via a browser, the status of several GECS
components can be accessed directly using their predefined HTTP port numbers.
The four main components of the GECS system (Agent, Controller, DBMS and Web Manager) each use 2 IP ports.
One port is used for communication between GECS components. The use of a port for communications between
GECS components is required. The other port is used for HTTP communications between GECS components and
browsers. The use of a port for HTTP communications is optional and can be disabled by entering a port number of
zero (0). The Workstation Setup program will default to the following port numbers.
Component
GECS Port
HTTP Port
Agent
2000
2010
Controller
2001
2011
DBMS
2002
2012
Web Manager
2003
2013
7-6
Monitoring & Managing
GECS Administration Overview
Since GECS can run continuously, you should design logical job streams to keep your GECS Agents occupied, thus
allowing them to fully utilize your hardware and increase your company’s productivity.
In a perfect world, your jobs would always run on time with no errors. However, in the event that things don’t run as
planned, corrective action may be necessary. GECS was developed to react to various Events that could otherwise
require user intervention or keep your jobs from running on schedule.
GECS allows you to take pro-active measures when creating your jobs to keep user intervention to a minimum. We
recommend that you plan ahead. Determine possible problems which could occur with your jobs.
Lets say you have file transfer tasks that needs to run every business day at 8pm. When the files are available, you
need to copy them to a new directory and send them via modem to the home office. You could create a GECS job
with trigger files that requires the resource of a modem. If the files are not available, there is nothing to transfer. If
the files are available but the modem is busy the files will not be transferred. Problems may include: jobs starting
late (i.e. due to lack of trigger file), jobs finishing late, jobs taking too long to run or jobs failing with a bad return
code. Once you have determined possible problems, you can create jobs that actually react to these Events.
Minimizing User Intervention
To maximize the amount of work GECS can do and minimize the amount of time you spend worrying about the
successful completion of your job streams, we recommend you setup jobs that take care of themselves. As you
automate jobs, try to imagine possible problematic Events and plan ahead for those Events. GECS can be set up to
react to job run time (amount of time it takes a job to complete), job lateness and job failure. The Actions tab from the
Job record is displayed below.
7-7
Monitoring & Managing
Job Run Time Issues
Setting the Maximum Minutes a Job can Run
GECS can limit the time allowed any particular job. Each job can be assigned a maximum run time using the
“Maximum Minutes” field found on the Actions tab in the Job record.
When jobs run longer than their maximum run time, the Agent software terminates the process and all its threads.
GECS then records that the job is complete with a return code of 255 and will reschedule it, if necessary. Having a
job time out is an error Event that will cause GECS to send Event notification if GECS is configured for error
notification.
There are various features and limitations in the operating systems on which GECS runs that cause this to get more
complicated. Yet in most cases, GECS can ‘stop’ jobs that run too long and mark them with a “Bad” (255) return
code. NLM Agents cannot terminate jobs.
A maximum number of minutes can also be entered at the Agent and user level. To configure your Agent, use the
“Maximum Minutes Per Job” field found on the Agent tab in the Agent record. To configure a user, use the
“Maximum Job Minutes” field found on the Profile tab in the User record. Before executing the job, GECS will
determine the minimum non-zero number of minutes entered for the job, the user, and the Agent. If all three are
zero, no restriction will be set.
Events can Alert you of Over Run and Under Run Jobs
GECS Events can be configured to alert you that a running job has exceeded its maximum minutes. From Event
Definitions simply set the appropriate Event Definitions.
Setting the Estimated Minutes it takes a job to Run
You can define an estimated number of minutes your job is likely to run using the “Estimated Minutes” field found
on the Actions tab in the Job record. If your job exceeds this time you can automatically be notified.
Each time your job runs, GECS can be set up to automatically update the estimated minutes you defined with the
job's newly calculated number of estimated minutes. To setup GECS to automatically update estimated minutes for
your jobs that you have defined estimated minutes, use the “Update Estimated Minutes” field found on the
Controller tab in the Controller record. The estimate is calculated using a weighted average formula.
new estimate = ((old estimate X 3) + actual minutes) / 4
Job Lateness Issues
Active Job due to Late Start Time
You can set up your job to activate another job if your job starts late. For instance, lets say if your job is 30 minutes
late, it should activate a job called LATEJOB to run, which notifies the operations department that there may be a
problem with your job.
Create a job named LATEJOB. The status of this job should be set to “Complete” because you never want it to run
on its own. You would then create your job with an appropriate command line. From the Actions tab in the Job
record, enter the name of the job to activate (LATEJOB) in the “Activate Job” field, then enter the amount of time in
7-8
Monitoring & Managing
minutes before the job should be activated.
When this occurs, GECS automatically changes the status of the job to be activated from “complete” to “pending”.
GECS will then run the job and generate two separate Events; One for the activation Event and one GECS Event for
the job it ran.
Skip Job due to Late Start
You can set up your job to skip if it starts late. Enter the number of minutes that this job should be allowed to be late
in the “Skip this job, if it is” field found on the Actions tab in the Job record. After the job is more than 'x' minutes
late, GECS will mark it as complete or reschedule it as if it had run with a return code of 255.
Skip Job due to Late Finish
If you need your job to be skipped if it will finish after a specified time of day, enter the time in HH:MM:SS format
using the “will finish after” field located on the Actions tab in the Job record.
Before a job is started, its estimated finish time (current time plus estimated run time) is calculated. If the estimated
finish time is after the time entered here, the job will be skipped. Leave the field blank or enter 00:00:00 to indicate
no maximum finish time. The estimated finish time is compared to the first occurrence of the time entered here after
the scheduled time.
Escalate Priority due to Late Start
If your job is late, its priority can be escalated (reduced from its initial value until it equals zero). For every 'x'
minutes your job is late, the priority will be escalated by a certain amount. Enter the amount the priority should be
escalated by and the number of minutes for each escalation using the “Escalate this job’s priority by” and “for each”
fields found on the Actions tab in the Job record.
Never Late
Use the Never Late field to mark jobs as never being late.
Return Code Issues
A job’s return code can be used to determine job success or failure. You can setup your jobs to automatically take
actions based on return codes. Several actions are described below. Also, see the Task Automation chapter for more
details on setting job return codes.
Maximum Good Return Code
Use the “Maximum Good Return Code” field to enter the highest number your job can return, as its return code, to be
considered a successfully completed job. This field can be found on the Actions tab in the Job record. The number
you enter in this field can be used to activate the job entered in the “Activate Job” field.
7-9
Monitoring & Managing
Minimum Good Return Code
Use the “Minimum Good Return Code” field to enter the lowest number this job can return, as its return code, to be
considered a successfully completed job. The number you enter in this field is used in conjunction with the activate job field.
This number determines if this job should be considered a failed job.
Activate Job due to Bad Return Code
Enter the Job number of the job to be activated (status changed to pending) if this job returns a failed return code. Then, enter
the largest return code that should be considered a success.
Retry Job due to Bad Return Code
The “Retry on Return Code” field can be used to retry failed jobs. Enter the minimum job return code that should cause the job
to retry. For example: If you want the job to retry if it returns 5 or more as the return code, you would enter '5' in this field. This
field can be found on the Actions tab in the job record.
Jobs will retry immediately unless your Agent has been configured with a “Minimum Minutes Between Job Retries”, in
which case the job will not retry until that number of minutes has elapsed. Other pending jobs will be executed during this
waiting period if they exist. The “Minutes Between Job Retries” field can be found on the Agent tab in the Agent record. Enter
'0' in this field if the job should not retry.
To limit the number of times a failed job should retry, populate the ”Times To Retry” field which can also be found on the
Actions tab in the Job record.
Change Job Return Codes
By right clicking on a Completed Job in one of your jobs list, you can change a failed job’s return code. For example, if you
have a failed job that has been manually fixed but is still holding up the rest of your job stream, you can change the failed
return code to allow dependent jobs to run. This field can only be changed once.
Generate Event on job Success
This field is designed for you to be able to generate an Event of your choosing when this job runs successfully. You can use
Event Definitions to define your Events. Events can cause other jobs to run by using the Depends On Event field from the
Dependencies tab on the job record.
Generate Event on job Failure
This field is designed for you to be able to generate an Event of your choosing when this job runs and fails. You can use Event
Definitions to define your Events. Events can cause other jobs to run by using the Depends On Event field from the
Dependencies tab on the job record.
Execute Message
Agents can display a message before executing a job. If you'd like an Agent to display a message before running this job, enter
that message into the Execute Message field.
Jobs that run on Windows Agents that are setup with a command line type of NT Console or DOS will pause until someone
presses a key. All other command line type jobs will just temporarily display the execute message then continue on.
Jobs configured with a Windows NT/2000/XP/2003 command line type use a special utility program called GECSMESG to
display a window with your Execute Message. From this window you can click the OK button to run the job or click the
Cancel button to cancel the job from running. When you click the Cancel button the job will not run but will act as if it had run
returning a bad return code of 255.
7-10
Monitoring & Events
Pre & Post Messages
GECS can create an Event before a job begins and after a job has completed using the Pre and Post Messages fields.
Enter the desired message to send using these fields to enable this feature or leave blank and no message will be sent.
These messages appear in the Pre and Post Events that are generated.
7-11
Monitoring & Events
7-12
GECS Windows Client Programs
GECS Windows Client
Programs
8-1
GECS Windows Client Programs
8-2
GECS Windows Client Programs
Windows Client Programs Overview
The GECS Windows Client programs can be accessed through the GECS Administrator program. The
Administrator is composed of a series of programs that can be run by clicking on folder icons. These programs
perform three basic functions.
1. They provide a facility for editing, viewing, adding and deleting information in the Jobs, Batches, Studio Worksheets, Events, Reports, Calendars, Resources, Vacations, Users, Security Profiles, Agents, Controller Settings, DBMS Settings and Event Definitions modules.
2. They can print reports and listings of the information from these modules.
3. They allow the GECS system to be updated and monitored.
These Client programs are installed from your Global ECS Windows CD ROM or can be downloaded. To set up
additional GECS client machines, see the Configuring GECS Client Computers section in the Getting Started
chapter of this manual. For improved performance see the “Enable Data Path” field in the Workstation Setup
program.
For detailed information on any field in a Windows client program, you can access help by pressing the <F1>
function key while you cursor is positioned over the field. You can also access on line help by clicking on the help
pull down menu and selecting help. This chapter will describe the GECS Windows Client programs from the
folders below:
8-3
GECS Windows Client Programs
Jobs Lists
The Jobs lists can be displayed by clicking on an existing view or by creating your own custom view. By default
GECS ships with the following views: Batch Summary, Complete Batches, Complete Jobs, Job Sentry, On Hold
Jobs, Pending Jobs and Running Jobs.
Once you have clicked on a view you can look at job records and filter the job records displayed in the list. By
double clicking on a job from this list you can view details about the job. If you right click on a job in the list, several
options display depending on the status of the jobs. For instance, if you right click on a ‘Completed’ job you can add
a new job, delete the job, view the job details, view the job history, copy the job, run the job with a new name, rerun
or change the job’s return code. Right click on a ‘Pending’ job to add a new job, delete the job, view the job details,
display reasons why the job cannot run, view the job history, copy the job, ignore job dependencies, ignore job and
file dependencies, respect job and file dependencies, run the job with a new name, skip and reschedule the job or put
the job on hold. Right click on a job with an ‘On Hold’ status and you can add a new job, delete the job, release hold,
view the job detail, copy the job as another job or run the job as another job. Right click on a running job to add a new
job, delete a job, terminate the running job, view the job details or view the job’s history. Right click on the column
header to print the list or display a count of the items. Left click on the column header and order the list ascending or
descending.
The first button on the toolbar is used for adding new records. The next button is to refresh the list. The third button
is used to stop refreshing the list. The fourth button is to display Batch Summary mode. The fifth button enables
auto refresh mode. The sixth button display details for the job. The seventh button is for deleting job records. The
question mark button launches on line application help. The tabs are for selecting the page to view. The Filters page
can be used to select filter criteria such as job range, agent, user or department.
8-4
GECS Client Programs
Job View Properties
You can customize the display of your GECS jobs by setting the job view properties. Update the view properties to
filter the information displayed in the jobs lists. Right click on the view title to display the Job View Properties
screens.
View Tab:
Filters Tab:
8-5
GECS Client Programs
Scheduled Job Detail
The Job Detail screens allow you to easily add, modify and delete GECS Jobs. This is the most direct way of adding
jobs to the GECS data files. Jobs entered through the Job Detail screens are immediately available for execution by
your running Agents.
The first button on the toolbar is used for saving records. The next button is for viewing reasons your job will not run
and the third button is for looking at your jobs schedule. The fourth button is to display job history. The fifth button
is to display Events associated with the job. The question mark button launches on line application help. The green
VCR buttons move from first, next, previous and last records in the list. The tabs are for selecting the page to view.
Command Tab:
8-6
GECS Client Programs
Schedule Tab:
Dependencies Tab:
8-7
GECS Client Programs
Requirements Tab:
Actions Tab:
8-8
GECS Client Programs
Mail Tab:
Statistics Tab:
For additional information on jobs, see the Task Automation chapter of this manual.
8-9
GECS Client Programs
Batches
The Batches folder allows you to define a batch of processes in an off-line environment and schedule or remove
them as a whole unit. When batches, batch variables and batch jobs are entered, they do not impact the GECS
system until they are scheduled. The process of scheduling batch jobs creates job records in the GECS system.
Once scheduled, Jobs created via Batches are no different than jobs created directly using the Jobs folders.
The first button on the toolbar is used for adding new records. The second button is used for saving records. The
third button is for deleting records. The fourth button is for scheduling batch jobs and the fifth button is for
displaying scheduled jobs. The question mark button launches on line application help. The tabs are for selecting the
page to view.
Batch Jobs Tab:
8-10
GECS Client Programs
Batches
Each Batch contains two types of information. First there is information pertaining to that Batch as a whole.
Second there is information pertaining to the Batch jobs which comprise the Batch.
Information relating to the Batch as a whole falls into three categories; Batch, Scheduling, and Batch Variables.
There are separate tabs for dealing with each type of information. Every Batch must contain Batch information
(Batch owner name and Batch name). Schedule and variable information are optional. From the Batch Jobs tab,
information pertaining to individual batch jobs is accessed by double clicking the appropriate Batch job from the
Batch Jobs list.
How Do Batches Work?
A Batch should be thought of as a process, which can contain any number of individual sub-processes or steps. The
steps of a Batch are called Batch Jobs. A Batch is simply a set of related Batch Jobs which describe the individual
steps of a process (Batch). Each Batch job specifies the command line of a program to be run for each step of the
batch. Dependencies can be created between batch jobs to organize job flow within the Batch.
Once a Batch has been defined and assigned Batch job records, the Batch as a whole is scheduled. Scheduled jobs
exist in the JOBS queue. When a Batch is scheduled, its constituent Batch job records are copied into the jobs queue,
and thereby become available for processing by the GECS Agents that service the queue.
To cancel the jobs of a scheduled batch, use the Scheduled Jobs screen and select the remove option. (see the
Utilities chapter of this manual for a Batch Remove utility). Removing a Batch deletes the job records of the
scheduled Batch from the jobs queue.
How Will I Use Batches?
In most cases Batches will be your primary tool for scheduling jobs. Since Batches make it easy to organize related
jobs, you will be able to create more sophisticated job streams, and respond to variations in job schedules more
rapidly.
What Do Batches Do?
Batches organize a complex set of tasks into a single manageable entity. Information moving through a typical
computer system or network more than likely requires a series of changes made by dissimilar products from several
vendors. Batches orchestrate the creation and management of multi-step processes.
What is a Batch?
Batches are named records that contain all the information necessary to add job entries to the JOBS queue. Naming a
Batch something meaningful such as “MONTHEND”, can help make the setup, maintenance and use of Batches
more intuitive.
8-11
GECS Client Programs
What are Batch Job Records?
A Batch is comprised of one or more Batch jobs. A Batch job record contains most of the information that defines
the jobs that will be created when the batch is scheduled. The information entered for Batch job records is very
much like the information that is entered when jobs are created manually or when using the Jobs folder.
What are Batch Variables?
Batch variables allow information to be placed into job records at the time they are scheduled. When Batch variables
are present for a selected Batch, a dialog is displayed prior to the creation of jobs. The data entered into the edit fields
of this dialog are placed wherever the associated variable name exists within the Batch job text fields.
Batch variable substitution is one of the most powerful features of Batches. Before working with variables, acquaint
yourself thoroughly with GECS Batches. The function of variables is simple. GECS will look in Batch job records
for a defined variable text string and substitute for it a value which is provided at the time the Batch is scheduled. By
incorporating variables into your Batches, you can create Batches that will automatically prompt users for
information each time they are scheduled. In this way, Batches operate as process templates where parameters are
entered at the time the Batch is scheduled. The benefit is that your users can interactively configure the processes of
a Batch without actually changing any Batch configurations or job records.
There are two steps to using variables in a Batch. First, place variables in Batch jobs where substitution should
occur. Second, define those variables so that GECS will prompt the submitter for values and substitute those values
into the Batch jobs. The Batch Variables tab contains Batch variables which have been defined for a Batch.
Variable definitions are created and edited using the Batch Variable Edit Screen.
One of the most commonly used areas of Batch variable substitution is on the Batch job command line. Many
applications allow for the use of command line options. Batch substitution makes it easy to specify those options
(such as dates or times) at the point the Batch is scheduled. Batch variables can be up to 8 characters long. The
format of substitution variables used within a Batch job record is ‘@XXXXXXXX@’, where the leading and
trailing ‘@’ symbols let GECS know that the encapsulated string is a variable and ‘XXXXXXXX’ is the name of the
variable. For example:
Suppose you have a batch job that should run notepad. For the purposes of this example, you also want
notepad to open a particular file when it is run. We know that by passing a filename on the command line,
notepad will automatically open a file. The trick is that each time the batch is scheduled, you want to specify a different file to open. You can use Batches to prompt for the file name at the time the Batch is scheduled by defining a Batch variable and placing it in the notepad command line in place of the file name to
open.
Command Line: notepad.exe @EDITFILE@.txt
If EDITFILE has been defined as a Batch variable for the Batch, GECS will prompt for someone to provide
the name of the file to open and substitute that name for the Batch variable ‘@EDITFILE@’ in the Batch
job.
To manage Batch variables, click on the Batch Variables tab from the Batches folder. The Variables Edit screen
will display all variables which have been defined for the Batch. If you choose to add or edit variables, the Batch
Variable Edit screen is displayed.
What is Scheduling Batch Jobs?
Scheduling Batch jobs is a process where Batch job information is combined with Batch information to create new
job records. These jobs, when executed by GECS, obey the rules set forth in the information entered into the Batch
and Batch job forms.
8-12
GECS Client Programs
Information entered into the Batch form(s) is replicated into each job record created during the process of
scheduling the Batch. Information entered into the Batch job form(s) corresponds one-to-one with each job record
when created.
What is Removing Batch Jobs?
The process of removing batch jobs simply deletes the remaining job records created for the Batch. However, it
does not delete completed job records.
Scheduling Your Batch
The next run time can be specified on either the Scheduling options tab in main batch screen or the Batch Job Detail
screen for each Batch job. If a time is specified on the Scheduling Options main Batch screen, that time will
supersede any times entered for each Batch job. If the Scheduling Options “Beginning At” field is left blank, the
times on the Batch job screens are used. GECS interpret the time ‘00:00:00" as midnight, at the beginning of a new
day.
There are four ways of specifying the next job run time to apply to jobs created by Batches.
1. Specify the next run time in each Batch job record that is created for the Batch and leave the next run
time/”Beginning at” field on the main batch screen Scheduling Options tab blank. Each job will then be created with
the particular next run time specified for each individual Batch job record.
2. Leave the next run time field in each individual batch job record set to 00:00:00 (or any other value) and put the
desired next run time in the “Beginning at” field of the Scheduling Options tab on main Batch screen. Each job will
be created with the next run time specified in the main batch screen.
3. Leave the next run time field in each individual Batch job record set to 00:00:00 (or any other value) and put the
special variable @TIME in the next run time, “Beginning at” field of the main Batch screen. Each job will be
created with the next run time of the system time at the point the Batch is scheduled.
4. Leave the next run time field in each individual Batch job record set to 00:00:00 (or any other value) and put a
Batch Variable in the next run time, “Beginning at” field of the main Batch screen. Each job will be created with the
next run time entered on the Batch Variables tab when the batch is scheduled. You must create a Batch variable
using Variable Edit in order to have substitution occur when the Batch is scheduled.
Batch Jobs that Repeat
It’s important to keep in mind that Batches do not recur, but the jobs that are created from the Batch can be setup to
recur. Batches can be scheduled manually. If for example, you had a set of tasks you would like to have run
everyday, you could set them up one of three ways.
1. Create a Batch and indicate on the Scheduling Options tab that the jobs created by the Batch should repeat every
day. Once the Batch is scheduled, the jobs of the Batch will automatically repeat every day with no required
intervention. At any point, the Batch can be removed and the jobs will quit running until the batch is scheduled once
again.
2. Create a Batch and indicate on the Scheduling Options tab that the jobs created by the Batch should not repeat at
all. Schedule the Batch at any interval you like. The scheduled jobs would run only once and stop.
3. Schedule a job to schedule a Batch each day using the command line (GECSBSCH.EXE). You may also choose
to create another job to remove the Batch later on in the day (GECSBREM.EXE). The removing of Batch jobs will
ensure that if the Batch has not run by a certain time each day, it will be automatically removed and thus not run at all.
8-13
GECS Client Programs
Instead, it will be scheduled for execution according to the schedule of the job which does the scheduling of the
Batch. It is interesting to note that the two tasks described above (Schedule Batch Jobs and Remove Batch Jobs)
could easily be a batch unto themselves.
Scheduling Options Tab:
Batches can be scheduled to run once, many times or indefinitely. From the Scheduling Options tab, you can
schedule Batches to repeat using either dynamic or static scheduling. With a dynamic schedule, Batch jobs are
created with a date and time that the job should run next. When the jobs complete, the system automatically creates
new instances of the job for the next date and time, based on the rescheduling information entered for the Batch.
With static scheduling, a separate job record is immediately created for every instance of when the job should run.
As with both kinds of scheduling, each job created is set up to run only once and is then marked complete. The
advantage of using static scheduling is that it gives you the ability to alter a job stream for a particular day without
affecting the schedule on other days. Additionally, Batch jobs can be scheduled for a specific date range.
Note that Batches cannot be scheduled to start in the past. If you use static scheduling and schedule jobs to run with
dates or times starting in the past, no job records will be created for those times.
Using Batch Variables
Variables must be used with a beginning and a trailing ‘@’ sign. For example, if a variable named FILENAME is
defined, it can be used in a command line as:
DIR @FILENAME@
For example, with this variable named FILENAME, the following batch command lines might be substituted as:
Batch Command Line
DIR @FILENAME@
Job Command Line
DIR TEST2.TXT
8-14
GECS Client Programs
Be aware that if you include ‘consecutive’ variables you MUST include the trailing blank on the first variable.
‘Consecutive’ variables are defined as two variables entered with no other characters or spaces between the
variables. For example, if you have defined the variables SUBDIR and FILE and enter the values as \abc\ and
xyz respectively, the following Batch command line would be substituted as:
Batch Command Line
DIR @SUBDIR@@FILE@
Job Command Line
DIR \abc\xyz
Once the base job information has been added, the next step is to add the Batch variables you will need for the Batch,
if any.
Batch Variables Tab:
After entering the base Batch information including batch scheduling information and any necessary Batch
variables, the next step is to add a Batch job record for each job that should be created from the Batch. The Batch job
screens and the fields are much like the Job record screens and fields.
8-15
GECS Client Programs
Batch Jobs Command Tab:
Batch Jobs Valid Times Tab:
8-16
GECS Client Programs
Batch Jobs Dependencies Tab:
Batch Jobs Requirements Tab:
8-17
GECS Client Programs
Batch Jobs Actions Tab:
Batch Jobs Mail Tab:
8-18
GECS Client Programs
Copying
Copy Batch Job
You may copy individual Batch job records into an existing Batch by using the “Copy Batch Job” option. First, pull
up the destination batch. Next click on the Copy pull down menu and select Copy Batch Job. You will be presented
with a list of all batch jobs on file. To copy an item, either double click on it or highlight it and select copy from the
File pull down menu. Copy Batch Job copies a single list entry into the current batch.
Copy Scheduled Job
You may copy individual job records into an existing batch by using the “Copy Scheduled Job” option. This option
copies a single list entry into the current batch. Copy scheduled job is particularly useful when getting started with
Batches. It helps you avoid re-entry of existing information.
Copy Batch
When copying a Batch, all the information associated with the source Batch is duplicated, including all Batch jobs,
Batch schedule and Batch variable records. To copy an existing Batch, choose Copy Batch from the Copy pull
down menu. Enter a new batch name and then select the Batch to copy.
8-19
GECS Client Programs
Studio Worksheets
The GECS Studio is a tool to make it easier to set up and maintain complex dependent job streams in a graphical
environment. Studio allows you to create a Work Sheet that shows one or more job streams. As the name implies, a
work sheet can be thought of as a large sheet of paper where you ‘layout’ your jobs. The jobs in a stream are shown
individually on the Work Sheet and are connected with arrows showing their dependencies. The Work Sheets can
be printed for hard copy purposes. Jobs can be added or edited directly from the Work Sheet. Existing jobs can be
easily added to a Work Sheet. When an existing job is added to a Work Sheet, all the jobs it depends on and all jobs
that depend on it are automatically added to the Work Sheet.
Studio Worksheets do not refresh to display the most current job information.
The first button on the toolbar is used for adding a new Studio WorkSheet. The next button is used for saving
records. The third button is for creating a new job. The fourth button is for launching the Job Detail screen. The fifth
button is for printing. The question mark button launches on line application help.
8-20
GECS Client Programs
You can create separate work sheets for your various job streams or you can combine multiple job streams onto a
single work sheet.
The easiest way to set up a new job stream is to add the jobs directly in Studio by right clicking on the work sheet and
selecting ‘New Job’ from the displayed menu. Enter the job number for the new job. The ‘Job Detail’ screen is then
displayed so you can enter information about the new job such as the command line to execute. When complete,
click on the Save button and then the Exit button. You have added a new job to the jobs file and you have added a job
object to the work sheet.
If you already have entered your job streams into the GECS system, you can use the ‘Import’ function to import one
or more jobs onto the work sheet. Right click on the work sheet and select Import from the displayed menu. Enter
the job number you want to import to the work sheet and click Import. The existing job you entered as well as any
jobs that depend on it and jobs it depends on will appear on the work sheet. Import adds an entire stream of related
jobs to the work sheet. To add a single existing job to a work sheet, use the Add Job selection as if you were entering
a new job, but enter the number of the existing job you want on the work sheet.
Each work sheet is opened or saved by entering a name such as Nightly Processing Flow. You can name the work
sheet when you create it with the Open Work Sheet selection or when you save it with the Save As selection.
Once a job object is on the work sheet, you can single left click on it to select it, double left click to view the detail for
the job or right click on the job object and a menu of selections appears. From that menu you can perform a variety of
operations including viewing the job detail or changing the icon that appears in the box.
The functions available in Studio are started from the pull down menu, the button bar or the menus that appear from
right clicking on the work sheet or the job object.
To import a job stream that is not already represented by a work sheet:
Click on the File Menu, click Import, then press <Enter>. This will import all of your job records onto the
Studio work sheet. Notice that job dependencies are attached by an arrow from the parent to the child job.
To add additional GECS Jobs to your job stream:
Open the work sheet containing the job stream you wish to modify. Click on the ‘New Job’ button. Enter
the new job you wish to create and save it.
To delete GECS Jobs from your job stream:
Click on the job you wish to delete. Once the job record is highlighted, right click on the job and click on
the Delete selection. Answer, ‘Yes’, when asked if you are sure you want to delete.
To update GECS Job information:
Double click on the job you wish to update. Make the appropriate modifications and save.
Studio Operations
The following functions are available in the Studio from the pull down menus, button bar or by right clicking on the
work sheet or job object.
8-21
GECS Client Programs
Events
GECS Events can be displayed in customizable lists. You can use the ‘View Properties’ to update the filtering that
can be applied to your views. This allows you to choose which Events you would like to see. The Events List(s) can
display GECS system and or user defined Events. You can create new views as needed and optionally share the
views with other users. By default, GECS ships with the following views of Event lists: All Events, Closed Events,
Job Events, Open Events and Users Events.
Once you have clicked on a view you can look at Event records and filter the Event records displayed in the list. You
can double click on an Event from the list to view the Event Detail screen. If you right click on an Event in the list
you can close the Event, delete the Event, remove your name from the Event or view the details of the occurrence of
the Event. Right click on the column header to print the list or display a count of the items. Left click on the column
header and order the list ascending or descending.
The first button on the toolbar is used to refresh the list. The next button is used to stop refreshing the list. The fourth
button enables auto refresh mode. The fifth button display details for the Event. The sixth button is for deleting the
Event record. The question mark button launches on line application help. The tabs are for selecting the page to
view. The Filters page can be used to select filter criteria.
See the Events chapter of this manual for more information on Events.
8-22
GECS Client Programs
Event View Properties
You can customize the display of your GECS Events by setting the Event view properties. Update the view
properties to filter the information displayed in the Events lists. Right click on the view title to display the Event
View Properties screens.
View Tab:
Filters Tab:
8-23
GECS Client Programs
Event Detail
The Event Detail screens allow you to easily close, add comments and delete GECS Events.
8-24
GECS Client Programs
Reports
GECS ships with several standard reports. A screen will appear that prompts for the report parameters or options.
Enter the options for the report and select the Print option on the File menu to print the report.
The first button on the toolbar prints the report. The question mark button launches on line application help. The
tabs are for selecting the page to view.
Available reports pertain to the following GECS categories:
- Jobs
- Vacation Periods
-Non-Business Days
- Defined Months
- Resources
- Supplies
- Users
Building your own reports
The GECS data files are Ctree files. You can build you own GECS reports of jobs, users, etc., by using most ODBC
compatible reporting tool with the Ctree driver installed. Contact your GECS Sales Representative for details.
8-25
GECS Client Programs
Calendars
GECS Calendars can be used for setting up both the Defined Months and the Non-Business Days calendars.
The first button on the toolbar is used for adding new records. The next button is used for deleting records. The third
button can be used to set non-business days. The fourth button sets the calendar’s date range. The fifth button is for
copying/merging calendars. The sixth button is for assigning a special title to a non-business day. The question
mark button launches on line application help. The two VCR buttons (red) select the previous or next months. The
tabs are for selecting the page to view.
Non-Business Days Tab:
8-26
GECS Client Programs
Non Business Days
Job repetition based on business and non-business days uses the information entered in this application when
determining the job’s next scheduled date. By default, every day is a business day and there are no non-business
days. Use this screen to change days from business days to non-business days. Use the arrow keys, Home, End,
PgUp and PgDn keys or the mouse to change the referenced day. Once a day is selected, press Enter or double click
on the date to make it a non-business day. You can enter an 8 character description for the date if you press Enter to
set the date. The program defaults the description to Non-Busi. To change a non-business day back to a business
day, simply double click on the date or clear the title field.
Defined Months Tab:
Defined Months
Job repetition based on user defined months uses the information entered in this selection when determining the
job’s next scheduled date. By default, there are no user defined months. Use this screen to mark the days that are the
first/beginning day of a user defined month. The user defined month goes up to the next beginning date entered.
They are referred to as user defined months, but could be thought of as user defined repetition periods. Use the
arrow keys, Home, End, PgUp and PgDn keys or the mouse to change the referenced day. Once a day is selected,
press Enter or double click on the date to mark it as the beginning of a user defined month. You can enter an 8
character description for the date if you press Enter. The program defaults the description to NewMonth. To
remove the user defined month, simply press Enter or double click on the date and it will switch back to a normal
day.
8-27
GECS Client Programs
Set Date Range
The “Set Date Range” button can be used to set a date range for each of your calendars by specifying an effective and
expiration date.
Copy Calendar
You can copy one calendar to another calendar by using this screen. The source calendar can be copied such that it
adds to the entries in the destination calendar or such that it replaces the entries in that calendar.
Set Non-Business Days
You can automatically set a range of days as business or non-business from this screen. Select the calendar to be set,
enter a date range and select the days of the week that should be business, non-business or left unchanged.
8-28
GECS Client Programs
Resources
The Resources client program allows you to define agent and system resources.
The first button on the toolbar is used for adding new records. The next button is used for saving records. The third
button is used for deleting records. The question mark button launches on line application help. The tabs are for
selecting the page to view.
When resources are added with the ‘Agent’ field blank, they are system resources. When the ‘Agent’ field contains
an agent name, the resource is specific to that agent.
8-29
GECS Client Programs
Vacations
Vacations are periods of time you do not want jobs to run. To add, view or delete vacation period information, use
the Vacations client program.
The first button on the toolbar is used for adding new records. The next button brings up a list of records. The third
button is used for saving records and the fourth button is for deleting records. Use the prompt field in the button bar
for entering the vacation period number to select or add.
Vacation Period Tab:
8-30
GECS Client Programs
Schedule Tab:
Vacation Lookup Screen
When the lookup button (magnifying glass) is pressed in the toolbar or the right mouse button is clicked on the
prompt field in the button bar, a window appears that allows you to view the vacation periods based on one of the
following selections:
Vacations Sorted By Number
This selection lists all the defined vacation periods in numeric order.
Vacations Sorted By Date
This selection lists all the defined vacation periods in the order of their start date and time.
This Vacation Period’s Schedule
This selection lists up to the next 20 times this vacation period will be active. If the vacation period doesn’t repeat or
if it doesn’t repeat 20 times, fewer than 20 periods will be listed.
8-31
GECS Client Programs
Users
The first step in setting up GECS is to set up users. GECS users are defined with in the Users Screens. Security
Profile definition gives GECS users rights to use the various functions in the system and sets limits on the user’s
jobs. After you define your first user and Security Profile, GECS security is enabled.
The Workstation Setup program is used to set the type of networking features used with GECS. When using
“Microsoft”, “NetWare” or “Lan Manager” networking features, the GECS user name must be the same as the users
network name.
When using GECS on a stand-alone PC (”No” networking) or on another type of network, the user name can be
anything you want. You will be prompted to enter a valid user name and optional password before you can start any
GECS client programs.
See the GECS Command Line Utilities chapter of this manual for information on ‘USERS’ file utilities.
The first button on the toolbar is used for adding new records. The next button is used for saving records and the
third button is for deleting records. Use the prompt field in the button bar for entering the user name to select or add.
The question mark button launches on line application help. The tabs are for selecting the page to view.
Security Profile Tab:
8-32
GECS Client Programs
Mail Tab:
Network Tab:
8-33
GECS Client Programs
Accounting Tab:
8-34
GECS Client Programs
Security Profiles
Security Profile definition gives GECS users rights to use the various functions in the system and sets limits on the
user’s jobs. After you define your first user and Security Profile, GECS security is enabled.
The first button on the toolbar is used for adding new records. The next button is used for saving records and the
third button is for deleting records. Use the prompt field in the button bar for entering the Security Profile to select or
add. The question mark button launches on line application help. The tabs are for selecting the page to view.
Security Tab:
8-35
GECS Client Programs
Agents
Agent records describe the operating system and hardware characteristics of the agent, as well as the functions you
want the agent to perform. Once agent records are created, agents can either be run from a desktop icon, in Windows,
as a service or in Unix, as a daemon.
See the Utilities chapter of this manual for information on AGENT file utilities.
The first button on the toolbar is used for adding new records. The next button is used for saving records. The third
button is for deleting records and the fourth button opens the agent lookup screen. Use the Agent prompt field in the
button bar for entering the agent name to select or add. The question mark button launches on line application help.
The tabs are for selecting the page to view.
Agent Tab:
8-36
GECS Client Programs
Characteristics Tab:
8-37
GECS Client Programs
Controller Settings
The Controller Screens allows you to modify your GECS controller record. Your controller record describes the
functions you want your controller to perform. Your controller can either be run from a desktop icon, or as a
Windows service.
The Workstation Setup program is used to create your GECS controller record, controller desktop icon and, when
desired, to set up your controller to be run as a service.
The first button on the toolbar is used for saving the record. The next button allows you to ping the controller
program. The third button can be used to automatically pulse the controller. The question mark button launches on
line application help. The tabs are for selecting the page to view.
From the Actions pull down menu, you can easily hide, show, minimize, pause, resume, stop, ping or pulse your
Controller by selecting one of these options.
Controller Tab:
8-38
GECS Client Programs
Network Tab:
Control Tab:
8-39
GECS Client Programs
Defaults Tab:
Mail Tab:
8-40
GECS Client Programs
DBMS Settings
The DBMS Screen allows you to modify your DBMS record. The DBMS record describes the functions you want it
to perform. Your DBMS can either be run from a desktop icon, or as a Windows service.
The Workstation Setup program is used to create your GECS DBMS record, DBMS desktop icon and, when
desired, to set up your DBMS to be run as a service.
The first button on the toolbar is used for saving the record. The next button allows you to ping the DBMS program.
The third button can be used to backup the GECS data files. The question mark button launches on line application
help.
From the Actions pull down menu, you can easily hide, show, minimize, or ping your DBMS by selecting one of
these options.
8-41
GECS Client Programs
Event Definitions
vents are things that can cause a job to run or things which may require special notice. Events can be generated by
the GECS system or they can be user definable.
Each Event is numbered and contains parameters to allow for special notifications. These notifications include:
email, SNMP, network message, Windows event logging, job activation, audible wav file, and color highlighting in
the GECS Administrator Events lists.
Use the Event Definitions folder to update Event parameters. GECS system Events are numbered from zero to 500
and cannot be deleted. User definable Events can be numbered starting from 1000.
The contents that display in the Users Events View controls whether the User Event Indicator is highlighted in red.
Event Definition Details can be modified using the GECS administrator client program to configure the special
notifications mentioned above.
Depending on how you use the GECS system, many Events you will not care about and others you will want to know
about if they occur.
Scroll through this list of Event Definitions and configure the Events you wish to be informed of.
8-42
GECS Client Programs
Event Definition Details
The Event Definition Detail screens allow you to modify your GECS Event Definition records.
Event Tab:
Mail Tab:
8-43
GECS Client Programs
Network Tab:
8-44
GECS Agents
GECS Agents
9-1
GECS Agents
9-2
GECS Agents
Agent Overview
A computer running the GECS Agent (GECSAGNT) software will actually run the jobs users schedule. The GECS
Controller dispatches jobs to available Agents. If an Agent is not running the Controller will not dispatch any jobs to
it.
Agent records are defined in the GECS system. These records name the Agents, describe the computers the Agents
will run on and various other details about the Agent.
The Agent programs can be run as a Unix daemon or from a terminal window on Unix. On Windows , Agents can be
run as a service under the system account, as a service under a specified user account or from a desktop icon.
The GECS Workstation Setup program is used to configure the way Windows Agents are to run. You should use the
Workstation Setup program to create Agent icons, or when desired, on Windows, to set up your Agents to run as
services.
When not run as a daemon or as a service, special commands can be entered at the Agent window. These commands
are described later in this chapter.
Installing Windows Agents from CD
Windows Agent programs can be installed from CD ROM. To install additional Agents go to each Agent machine
and install the Agent programs using the following instructions:
Windows Agent from CD ROM
A. Login as Administrator or as an administrator equivalent user.
B. Insert the GECS Windows CD ROM. The installation program may automatically start after several
seconds. If the installation program does not automatically start, click the Start button, select Run and
Enter: D:\SETUP.EXE
(Where D: is your CD ROM drive)
C. Click the Install Agent Only option then click the OK button.
D. Click the Finish button to display the Global Agent Setup screen.
E. Again, use the default settings and click the Configure button, then click OK.
Installing Agents from Images
GECS Agent programs can be copied from the Global ECS Windows CD ROM from the AGENT subdirectory or
you can FTP the Agent programs from the Global ECS web site (www.globalecs.com). To install Agents from
images (EXE/TAR files), go to each Agent machine and install the Agent programs using the following
instructions:
9-3
GECS Agents
Windows Agent Exe File
A. Login as Administrator or as an administrator equivalent user.
B. Open a Command Prompt
C. Enter:
md c:\gecsagnt
D. Copy or ftp the EXE file to c:\gecsagnt (as binary)
E. Exit
F. Click the Start button, select Run, c:\gecsagnt\gecs-3.11-intel-win32.exe
G. Unzip into c:\gecsagnt
H. Unzip, click OK then Close.
I. Click the Start button, select Run, c:\gecsagnt\subtypes
AIX Agent Tar File
A. Login as the root user.
B. Enter: cd /
C. mkdir /gecs-tar
D. cd /gecs-tar
E. Copy or ftp the tar file to /gecs-tar (as binary)
F. tar -xvf gecs-3.11-rs6000-aix.tar
G. cd GECS
H. installp -ac -d . GECS
HP-UX Agent Tar File
A. Login as the root user.
B. Enter: cd /
C. mkdir /gecs-tar
D. cd /gecs-tar
E. Copy or ftp the tar file to /gecs-tar (as binary)
F. tar -xvf gecs-3.11-hp9000-hpux.tar
G. swinstall -s /gecs-tar/GECS GECS
Linux Agent Tar File
A. Login as the root user.
B. Enter: cd /
C. mkdir /gecs-tar
D. cd /gecs-tar
E. Copy or ftp the tar file to /gecs-tar (as binary)
F. tar -xvf gecs-3.11-intel-linux.tar
9-4
GECS Agents
G. cd GECS
H. rpm -i GECS-3.1-1.i386.rpm (redhat systems)
or
alien -i -k ./GECS-3.1-1.i386.rpm (for debian Linux-Corel)
NLM Agent Tar File
A. Go to a PC running DOS, Windows or Windows NT/2000/XP/2003.
B. Login as SUPERVISOR or ADMIN.
C. Open a command prompt.
D. Enter
md c:\gecsnlm
E. Copy or ftp the EXE file to c:\gecsnlm (as binary)
F. Exit
G. Click the Start button, select Run, c:\gecsnlm\gecs-3.11-intel-netware.exe
H. Unzip into c:\gecsnlm
I. Unzip, click OK then Close.
J. Click the Start button, select Run, c:\gecsnlm\install.exe
SCO UnixWare Agent Tar File
A. Login as the root user.
B. Enter: cd /
C. mkdir /gecs-tar
D. cd /gecs-tar
E. Copy or ftp the tar file to /gecs-tar (as binary)
F. tar -xvf gecs-3.11-intel-unixware.tar
G. pkgadd -d /gecs-tar GECS
Solaris Agent Tar File
A. Login as the root user.
B. Enter: cd /
C. mkdir /gecs-tar
D. cd /gecs-tar
E. Copy or ftp the tar file to /gecs-tar (as binary)
F. tar xvf gecs-3.11-sparc-solaris.tar
G. pkgadd -d /gecs-tar GECS
The above example is for ‘sparc’ based Solaris. Change all references from ‘sparc’ to ‘intel’ for ‘intel’ based
Solaris.
9-5
GECS Agents
Tru64 Unix Agent Tar File
A. Login as the root user.
B. Enter: cd /
C. mkdir /gecs-tar
D. cd /gecs-tar
E. Copy or ftp the tar file to /gecs-tar (as binary)
F. tar xvf gecs-3.11-alpha-tru64.tar
G. setld -l GECS GECS310
IRIX Agent Tar File
A. Login as the root user.
B. Enter: cd /
C. mkdir /gecs-tar
D. cd /gecs-tar
E. Copy or ftp the tar file to /gecs-tar (as binary)
F. tar -xvf gecs-3.11-mips-irix.tar
G. inst -a -f GECS -u all
H. installp -ac -d . GECS
Create Agent Records
Before starting your Agents you need to create a unique Agent record for each Agent. Use the GECS Client
programs to create Agent records.
Starting your Agents
Start your Agents on the Agent machines using an appropriate command. Command line usage options include:
gecsagnt [-n name]...
-c ini
INI file to use
-h
run hidden
-m
run minimized
-n name
Agent’s GECS name
-p port
Use ‘port’ rather than port 2000
9-6
GECS Agents
-q port
Use ‘port’ for HTTP rather than port 2010 (0=disable)
-s name
HTTP login name
-t pass
HTTP login password
-u path
Path for misc HTTP files
-v
Verbose messages
For example:
Agent Operating System
Command Line
Unix or Linux
gecsagnt [-d] [-n name] [-p port]
NT/2000/XP/2003
use the ‘Agent NTAGENT’ icon in the GECS Agent program group
or C:\GECS\GECSAGNT.EXE[-n name][-p port]
NLM
LOAD SYS:\GECS\GECSAGNT.NLM [-n name][-p port]
Note that for the NLM Agent, the NETDB.NLM must be loaded in order to run GECSPING.NLM,
GECSSTOP.NLM, GECSHIDE.NLM, GECSSHOW.NLM, PULSENOW.NLM or AGENTRUN.NLM. This
NLM is loaded by NW4.11, but has to be loaded by hand for NW5.
The ‘-d’ option tells the Agent to run as a Unix Daemon. Initially, do not run the Unix Agents as a Daemon so you
can see the jobs running on the Unix console. You can start the Agent later as a Daemon if you wish.
The ‘-n name’ option gives the Agent a GECS name. Some examples of Agent names are NTAGENT or
HPAGENT. The names on all Agents must be unique and defined using the GECS.
Note that the name parameter is optional. If a name is specified using this option, this Agent will ONLY respond to
messages specifically sent to that name. If the name option is omitted, the Agent will respond to any request,
regardless of the name. It is recommended that you use the name option.
The ‘-p port’ option tells the Agent which TCP/IP port number to use. This parameter is optional. Other start up
parameters are described later in this chapter. By default the Agents use port 2000. The range of valid port numbers
is 1 to 65536. To stop an Agent when running on the desktop or console, enter ‘exit’.
Running a Test Job on New Agents
Set up a test job using the Windows Administrator program - Jobs folder.
1. Click on the File pull down menu and select Add New Job. Enter: JOB1TEST then click the Add button.
2. Enter the following job parameters:
Command Line: gecsret 0
( gecsret is a utility program that returns the value passed as a command line parameter. It is installed in the
Agent program subdirectory.)
Command Line Type: Match the OS you are running
9-7
GECS Agents
3. Click on the Requirements Tab and select an Execute By Agent. Choose the name of the new Agent you
created. This will force this new job to only run on this particular Agent.
4. Save the job.
After several seconds (when the Controller pulses), the test job should run on the Agent machine.
For example, you should be able to see this job in the completed jobs list. If you highlight this job from the list and
double click on the entry, completed job information will be displayed on the job’s statistics tab.
Troubleshooting
Should you experience problems, go to the Windows machine where the Controller is installed and test
communication with the running Agents using the GECSPING utility.
The GECSPING utility is installed with the Controller programs. If you used default directories during installation, GECSPING is in the C:\GECS subdirectory. Enter the following command line:
C:\GECS\GECSPING.EXE name ip_name [port]
The ‘name’ and ‘ip_name’ command line options are required. The ‘name’ is the GECS name you gave
the Agent when you started it, such as NTAGENT or HPAGENT. ‘Port’ is optional. ‘Port’ is the port
number on the Agent machine that will be used for communication from the Controller, and is a number in
the range of 1 to 65536. The Agent port defaults to 2000. For example:
C:\GECS\GECSPING HPAGENT zeus.company.com 3000
or
C:\GECS\GECSPING NTAGENT 200.200.200.100
A message will be displayed to indicate whether the specified Agent can be contacted. Note that the
‘name’ and ‘port’ options must match the name and port specified when the Agent was started.
Make sure you can successfully ping the Agent before you continue with the next step. If the AGNTPING
fails, verify your IP address or name, try a different port number, and verify that you are using the Agent
name you used when you started the Agent.
You can go to the computer where the Agent is running and enter the word ‘Address’, in the Agent window. This
will display the name and address the Agent is running as.
9-8
GECS Agents
Monitoring Your Agents
GECS Events can inform you if you have an Agent that is not running
You can check the status of each of your Agents using the Windows Administrator Agents folder or using the web
Client programs.
From the GECS Administrator program, click on the Agents folder, click on the Agent you wish to check, then click
on the “Lookup” toolbar button and select “List of Agents”. A window will display the Agent names, description
and status of each.
By right clicking on the Agent record from the Administrators list you can easily hide, show or minimize Windows
Agents as well as stop or ping an Agent.
The web clients can display a list of problems with the GECS System. These problems may include Agents marked
as quit. Agent records can also be accessed from the “Agents” option off your Global ECS, main menu, Home page.
You can view the status of an Agent using a browser by entering the appropriate URL as shown below:
http://ipaddress:http port/name
For example:
http://200.200.200.154:2010/FRAN
You will then be prompted to enter a user name. By default, you should enter the name of the Agent (FRAN).
However, if the Agent was started with the command line parameters -s name (HTTP login name) and -t pass
(HTTP login password) the appropriate user name and password must be used.
9-9
GECS Agents
Agent Parameters
Agent records are defined in the GECS system. These records name the Agents, describe the computers the Agents
will run on and various other details about the Agent. Agent records describe the operating system, IP Address,
comments and hardware characteristics of the Agent. Agent records can be created using the web based Client
programs or the Windows based Administrator Client program
The GECS web based Client programs are described later in this manual. The Agent parameter field names are the
same in the web based clients as in the Windows Client programs. Agent parameters are described below.
The GECS Administrator Windows based Client program, allows you to create, modify and delete Agent records
and is displayed below.
Agent Name
Your GECS Agents can be assigned any alpha numeric name up to 8 characters in length. Agent names are forced
upper case. Every Agent must have a unique name that must be defined before it can be started.
You should only create as many Agents as you are licensed to run. If you do create more Agent records then you are
licensed for, ensure you set the “Process Jobs” field to None, on the Agents you do not intend to use. Otherwise,
GECS will determine on its own which Agents to service.
IP Address
The “IP Address” field in the Agent record is used to enter the IP address of the machine that will be running the
Agent software as this defined Agent.
9-10
GECS Agents
Port
The “Port” field in the Agent record is used to enter the port number of the machine that will be running the Agent
software as this defined Agent. If this field is left blank GECS will use port 2000.
Last Accessed
The “Last Accessed” date and time fields are used to view the last activity of an Agent. These fields are automatically updated by GECS. These fields cannot be modified.
Description
The “Description” field is used to enter any miscellaneous description about your Agent. This optional description
will appears along with the Agent name in various places within the GECS programs.
Process Jobs
The “Process Jobs” field is used to indicate whether this Agent should process:
All jobs
- No restrictions
Group jobs
- Only jobs that belong to a specific group
None (Inactive)
- No job records.
When communications fail between the DBMS or Controller and an Agent GECS sets the Agent’s Process Jobs
field to “None (Inactive)”. To set the Agent back to “Active” you must update Process Jobs field to either “All
jobs” or “Group jobs”.
Simultaneous Jobs
The “Simultaneous Jobs” field is used to specify the number of jobs you would like your Agent to be able to run at
one time. If you enter a '0' in this field, the Agent will run an unlimited number of jobs simultaneously which will
likely exceed the available defined system resources and generate errors.
Maximum Jobs Of A Class
The “Maximum Jobs Of A Class” field can be used to limit the number of jobs of a given class that can be run at once.
Each job can be assigned to a class using the “Job Class” field found in the Job record.
If you have set the maximum simultaneous jobs to 5, you might want to set the maximum jobs of a class to 4. This
would keep a single class of jobs from hogging and entire Agent. If you have jobs you never want to have running at
the same time, you could set this number to 1 and assign the jobs to the same class. Entering 0 will eliminate any
class restrictions.
“Resources” can also be used to limit certain jobs from running at the same time. For details see the Required
Resources section in the Task Automation chapter.
9-11
GECS Agents
Minutes Between Job Retries
Jobs can be defined such that when they return a failing return code they can automatically retry. In some situations,
this can cause an Agent to continuously try a failing job when it has other jobs pending. By defining a minimum
number of minutes between job retries, you can keep the job from constantly trying the failing job, without giving
up on it completely. Use the Agent record’s “Minutes Between Job Retries” field to set this time.
Maximum Minutes Per Job
Using the “Maximum Minutes Per Job” field allows you to define a maximum number of minutes that a job can run
on your Agent.
GECS monitors job processes while they run and shut down sessions that run longer than is allowed.
GECS for NetWare NLMs monitors its job processes while they run. Command lines that started with the word
‘load’ are automatically ‘unloaded’ by the when they run longer than their maximum run time.
A maximum number of minutes can also be entered at the user and job level. Before executing the job, GECS will
determine the minimum non-zero number of minutes entered for the job, the user and the Agent and will use that
number. If all three are zero, no restriction will be set.
Ignore User Names
By default, GECS will only accept WRK files and dispatch jobs for users that are defined in the GECS Users file. By
entering a check mark in the “Ignore User Name” field, GECS will no longer reject WRK files or jobs because they
are from undefined users.
When this field is enabled, GECS uses the user definition for the lowest alphabetical name on file in determining
how to process jobs.
Login As Submitting User
Most Agents can be configured to login to the network as the submitting user before executing jobs. Enable the
“Login as Submitting User” field in the Agent record if an Agent should login as the submitting user before
executing jobs.
GECS Agents that can be configured to login as submitting user include: Windows, Linux, AIX, Solaris, HPUX
and Tru64 Unix. GECS Agents that cannot be configured to login as submitting user include: NLM and UnixWare.
When Windows Agents login as submitting user they use the submitting user's rights but not the user's desktop.
When Linux, AIX, Solaris, HPUX or Tru64 Unix Agents login as submitting user, they use the user's rights and the
user's environment. (The 'su' command is used and the user's .profile gets executed).
You must also include the user’s “Network User Name” from the Users record. (This field is case sensitive). For
Windows only the “Network Password” is also required.
When logging in as submitting user on Windows, the Agent account used to start the Agent must be a local user
account, not a domain account. The Windows Agents also require the proper security privileges in order to log on as
the submitting user. See the “Creating User Accounts” section of this chapter for details.
Linux, AIX, Solaris, HPUX or Tru64Unix Agents must be running logged in as root, running as a daemon or on the
desktop.
9-12
GECS Agents
Comments
The “Comments” field is an optional field that can be used to enter a miscellaneous comment about your Agent.
Agent - Characteristics Tab
Agent characteristics are usually defined for Agents in a multi-Agent environment. Characteristics are used to limit
the jobs or type of jobs that can run on certain Agents. The Agent Characteristics page contains the fields described
below.
Group Names
The “Group Names” field is an optional field which can be used in a multi-Agent environment. This is the name of
the group of Agents to which this Agent belongs. Group names may be used to direct selected jobs or selected users’
jobs to be executed on specific Agents.
Up to 10 group names can be assigned to each Agent. To add an Agent group, type the new group name in one of the
Agent group fields.
Operating System
The “Operating System” field is used to define the type of operating system of the computer that will run this defined
Agent. The information entered here is used to decide if this Agent has adequate capabilities to run particular jobs.
Your options are: Other, Windows NT/2000/XP/2003, UnixWare, Netware, Windows 95/98/ME, Linux, AIX,
HPUX, Solaris, Tru64 and IRIX.
Operating System Version
The “Operating System Version” field is used to define the operating systems version number which is installed on
the computer that will run this defined Agent. The information entered here is used to decide if this Agent has
adequate capabilities to run particular jobs.
Job Types
The “Job Types” field is required and is used to indicate what command line type(s) of jobs this Agent should be able
to run. Your options include:
Windows NT/2000/XP/2003 - Applies to Windows Agents.
Windows 95/98/ME
- Applies to Windows Agents.
Windows
- Applies to Windows Agents.
DOS
- Applies to Windows Agents.
OS/2
- Applies to Windows Agents.
9-13
GECS Agents
NLM
- Applies to NetWare Agents.
NT Console
- Applies to Windows Agents.
UnixWare
- Applies to UnixWare Agents
Linux
- Applies to Linux Agents.
AIX
- Applies to AIX Agents.
HPUX
- Applies to HPUX Agents.
Solaris
- Applies to Sun Solaris Agents.
Tru64 Unix
- Applies to Tru64 (Digital Unix) Agents.
IRIX
- Applies to IRIX Agents.
Configuring Agents
Unix Agent programs can be run as a Unix daemon or from a terminal window on Unix. Unix Agents use Unix
installation utilities to copy GECS Agent programs to the proper directory. The parameters used when starting Unix
Agents determines whether they run as a daemon or from a terminal window.
Windows Agents can be run as a service under the system account, as a service under a specified user account or
from a desktop icon. A GECS installation program (SUBTYPES) is shipped for Windows Agents to copy the
GECS Agent programs to the proper directory. Unlike Unix Agents, Windows Agents must use a special program
to configure the way Windows Agents are to run. The GECS Workstation Setup program configures the Agent
computer to create Agent icons for starting the Agent from the desktop, or to set up Agents to run as services.
9-14
GECS Agents
Windows Agent Configuration
A40SETUP.EXE is the Windows program used to configure your Windows Agent(s). When started, a screen
similar to the following will appear:
Use this program to set up your Windows Agents. When run from a Desktop Icon, the Agents must be manually
started. When run as a service, the Agent program is automatically started when the computer is started.
Starting and Stopping Agents
When a Windows Agent is run as a service, it will automatically start and run when Windows starts, whether anyone
is logged in or not. It will have the rights of the user you indicate it should log in as. You will not be able to see the
jobs being run. They will run invisibly.
When a Windows Agent is run on the desktop (not as a service), the Workstation Setup program will create an icon
to start the Agent. When you run the Agent on the desktop, you will see the jobs being run.
Run the GECSSTOP program or enter ‘exit’, ‘stop’ or ‘quit’ to stop the Agent.
Agents software is installed from diskette or CD ROM. Each Agent operating system supported by GECS contains
an Agent program, an Agent Workstation setup program and a few other programs described below. Generally, the
Agent software programs work the same, regardless of operating system.
It is run as follows:
Unix or Linux
gecsagnt [-d] [-n name] [-p port]
Windows desktop Double click your “Agent NTAGENT” icon
9-15
GECS Agents
or C:\GECS\GECSAGNT.EXE [-n name] [-p port]
NLM
LOAD SYS:\GECS\GECSAGNT.NLM [-n name] [-p port]
All the command line arguments are optional. The ‘-d’ option tells the Agent to run as a Unix or Linux Daemon.
The ‘-n name’ option gives the Agent a GECS name. A record must be entered for each Agent using this ‘name’.
The names on all Agents must be unique. The ‘-p port’ option tells the Agent which TCP/IP port number to use. By
default the Agents use port 2000.
When you run the GECS Agent for HP-UX, UnixWare, Linux, Solaris, AIX or Tru64 as a daemon, they run in the
background. They and the jobs they run can’t be seen. They will continue to run after you logout. You may want to
make entries in the /etc/inittab file so the Agents will automatically start when the operating system starts. The
daemon will run with the rights and environment of the user that started it.
There are special startup options listed below. These options can either be run from the command line, or can be
entered in the shortcut properties for a Windows Agent when run from a desktop icon.
Run Agent as Desktop vs. Service
Hidden / Minimized
Windows Agents can be run so that they show on the screen, they can be run hidden from view or minimized. From
the GECS Administrator program, Agents folder, Actions pull down menu, you can Hide, Show, Minimize, Stop or
Ping an Agent. Hide or Minimize allows you to hide or minimize the displayed Agent from view, on the Agent
machine, once it is started. Once hidden or minimized, you can bring the Agent back into the foreground by
selecting “Show”. The Agent can be started in hidden mode by including the -H command line option or started
minimized by including the -M command line option:
GECSAGNT.EXE Agentname -H
GECSAGNT.EXE Agentname -M
Where Agentname is the name of your Windows Agent. By including a shortcut icon for your Agent in the startup
group with the -H or -M option, the Agent will start hidden or minimized every time your Windows Agent machine
is started.
The programs launched by GECS Agent when the Agent is hidden may or may not be hidden themselves depending
on whether the job was defined to run normal, minimized or hidden. They may appear in the foreground or hidden
whether the Agent is running normally or hidden, depending on the setting for the job.
Running your Agent as a Windows Service
Windows NT introduced the concept of “services”. A service is a software program that is automatically started
when Windows starts, but before anyone logs in. Services start before the user logs in and continue to run even after
the user logs out. Database servers and file servers are types of programs that would normally be run as services.
Windows Agents can be installed as a service. GECS will execute submitted jobs as long as Windows is running,
even if no one is logged in to the console. There are several setup issues that must be considered as well. Regardless,
running GECS as a service under Windows can be used in a wide variety of ways and can greatly enhance the
functionality of Windows.
If you are not familiar with using Services, you should not attempt to run your GECS Agent as a service. Also, first
time GECS users should always start by running their Agents from a desktop icon. More experienced GECS users
can run their Agent(s) as a service, after testing.
9-16
GECS Agents
Differences When Run as a Service
When a Windows Agent is run as a service, there are several differences in the type of jobs that can be run and the
way jobs are run. This is due to the nature of a service and its security. The following list contains the differences in
functionality:
Keyboard stuffing is ONLY allowed with DOS programs.
GECS and its jobs are hidden from view when no one is logged in.
Once someone logs in, the jobs GECS is running are visible on the desktop, if the GECS service is running
on the system account. This will likely make the Program Manager environment difficult, if not impossible to use. If the jobs are being run on a user account, they will not be visible to the logged in user. For best
results, most GECS maintenance can be performed from another Workstation.
Network drives are not mapped until a user logs in and the mappings are lost when the user logs out.
Logging on or off during job execution may interfere with job execution.
Desktops do not get established and neither do things such as drivers/printers/drive mappings/search
path/environment variables and a collection of other things.)
By using the default settings, GECS runs in the security context of the local system account and uses the default
Station/Desktop. With Windows, the system accounts privileges have been modified to limit access to local and
network resources thereby limiting the privileges of GECS and its jobs. To regain control over the resources GECS
has access to, GECS must be setup to run within the account of a specific user. Use the procedures outlined below to
create an GECS Agent user account and setup GECS to use the new account.
Creating User Accounts
Assigning a specific user account to a GECS Agent allows control over the security access to local and network
resources. To setup a GECS Agent user account, Log on to Windows as the system administrator or a user who has
rights to create new users. Using the Windows User Manager, create a new user using the information specified
below.
Username:
NTAGENT (use the Agent name)
Full Name:
GECS
Description:
Logon Account
Password:
xxxxxxx
[x] Password Never Expires
Use User Manager’s User Rights Policy dialog to grant the required rights to the Agent’s user account. The rights
required for the Agent to execute the submitted jobs varies with each installation of GECS. These rights MUST be
determined by you. In addition to rights required by the executed jobs, the Agent’s logon account MUST have the
following advanced User Rights. Note that ‘Show Advanced User Rights’ must be checked to display the necessary
rights.
Act as part of the operating system
Increase quotas
Log on as a service
Replace a process level token
By making the Agent User Account a member of the Administrators group, GECS will have full control of the local
system. This may not be the desired behavior of your particular system. To change the rights of the Agent Account,
first create a new user group and then make the Agent Account a member of this group, at which point you may
change the User rights for this specific group. (See User Manager Help for more information on creating New
Groups, New Users and User Rights).
9-17
GECS Agents
Creating Logon User accounts
In addition to the running in a dedicated log on account, each job that the Agent executes may run within the security
context of the user who submitted the job. This feature is enabled by checking ‘Login as Submitting User’ in the
GECS Agent record and by entering the ‘Network User Name and Password’ in the GECS User record. When
entering the ‘Network User Name’ an optional Domain name may be included before the entered user name. i.e.
‘\\DOMAIN\username’.
To edit the user accounts that GECS Jobs will log on as, logon to Windows as the system administrator or a user who
has rights to edit user accounts. Using the Windows User Manager, select the user to grant the required log on rights.
Use User Manager’s User Rights Policy dialog to grant the required rights to the selected users account. The rights
required for the Agent to execute the submitted jobs varies with each installation of GECS. These rights MUST be
determined by you. In addition to rights required by the executed jobs, the user account MUST have the following
advanced User Rights. Note that ‘Show Advanced User Rights’ must be checked to display the necessary rights.
Log on as a service
Log on as a batch job
Grant these rights to each user account that will run GECS Jobs.
GECS Service Program
GECS can be run as a service on Windows. The ASERVICE.EXE program is used to start the service. This
program is run automatically by the Windows service manager and should never be run directly. This program is
only included with GECS Agent for Windows.
GECS Service Installation
The Workstation Setup program for Windows can configure GECS s to run either on the desktop or as services. The
services can run using the system account or under a specified user account. Additionally, when jobs are run, the
jobs can run logged in as the submitting user or as the user the Agent is running as.
To setup an Agent to run as a Windows service, open the GECS Workstation Setup program. Go to the Agents page,
set the “Run ” field to either “as a Service using the specified user account” or “as a Service using the system
account”. When using a user account, press the lookup button on the User Account field to select from a list of user
accounts. Enter the password in the Password field. After completing the properties screen press the OK or Next
button then click the Configure button.
The Workstation Setup program will automatically configure the specified Agent to run as a service. It will also add
the appropriate registry information.
GECS Service Removal
The Windows Workstation Setup program can be used to remove a service. To remove a service, update the “Run”
field to “from a desktop icon”.
9-18
GECS Agents
Agent Command Line Utilities
When Agents are not run as a daemon or as a service, special commands can be entered at the Agent window. These
commands are listed below:
GECSHIDE
- Used to hide a Windows Agent window
GECSLAUN
- Internal Unix utility
GECSPAUS
- Used to Pause/Unpause remotely
GECSPING
- Used to test the status of Agents
GECSRET
- Used for testing return codes
GECSSHOW
- Used to display a hidden Windows Agent windows
GECSSTOP
- Used to stop an Agent
PULSENOW
- Used to immediately pulse your Controller
These and other utilities are described in detail in the GECS Utility Programs chapter of this manual.
Agent Desktop Terminal Commands
When Agents are not run as a daemon or as a service, special commands can be entered at the Agent window. These
commands are described below:
Usage:
EXIT, STOP, QUIT
- Shutdown the Agent
HIDE
- Hide the Agent
MINI
- Minimize the Agent
VERSION
- Display version
CLS, CLEAR
- Clear screen
TIME
- Display time
VERBOSE, QUIET
- Toggle verbose messages
ADDRESS
- Display address
LIST
- List processes
9-19
GECS Agents
Uninstalling GECS Agents
Be sure all GECS programs are stopped before uninstalling.
Windows Client, DBMS, Controller, or Agent
1. From Control Panel, click Add/Remove Programs.
2. Select the Global Event Control Server then choose Uninstall.
3. Indicate whether or not to delete program and data files.
4. Click the Uninstall button.
AIX Agent
1. Login as root.
2. Enter
cd /
3. Enter
/usr/lib/instl/sm_inst installp_cmd -u -f GECS
or for the menu driven program enter
smit
and follow the instructions that appear on the screen
HP-UX Agent
1. Login as root.
2. Enter
cd /
3. Enter
swremove GECS
Linux Agent
1. Login as root
cd /
2. Enter
3. Enter
rpm –e GECS
(or) dpkg –r GECS
(Redhat)
(Debian)
NetWare Agent
1. Login as ADMIN or equivalent from a Workstation running DOS, Windows or Windows NT/2000/XP/2003.
2. Change to the root subdirectory (i.e. CD \)
3. Delete the files from the GECS subdirectory (i.e. DEL \GECS\*.*)
4. Remove the GECS subdirectory (i.e. RD \GECS)
9-20
GECS Agents
SCO UnixWare Agent
1. Login as root.
2. Enter
cd /
3. Enter
pkgrm GECS
Solaris Agent
1. Login as root.
2. Enter
cd /
3. Enter
pkgrm GECS
Tru64 Unix Agent
1. Login as root.
2. Enter
cd /
3. Enter
setld -d GECS300
IRIX Agent
1. Login as root.
2. Enter
cd /
3. Enter
inst -a -R GECS
or for the menu driven program enter
smit
and follow the instructions that appear on the screen
9-21
GECS Agents
9-22
GECS Controller
GECS Controller
10-1
GECS Controller
10-2
GECS Controller
Controller Overview
The Windows computer running your GECS Controller program (GECSPROC.EXE) controls and dispatches jobs
to be run by available Agents.
When running, your Controller looks at the JOBS file and determines which Pending job to dispatch to Agents. It
checks the availability of each defined Agent. It may also perform a number of other tasks during its “free time”.
Controllers can be run from a desktop icon, or a Windows service using a user account or using the system account.
When your Controller is configured to run on the desktop, the Workstation Setup program creates an icon in the
GECS desktop folder. The Controller can then be started by clicking on the icon. While it is running, enter
‘exit’,‘stop’ or ‘quit’ to shut down the Controller program. When the Controller is running on the desktop, it has the
rights of the user logged in. It will only run as long as someone is logged in.
When the Controller is configured to run as a service, it will automatically start and run whenever Windows is
running, whether anyone is logged in or not. It has the rights of the user you indicate it should log in as or the
system account. You can start and stop the service by clicking on the Services selection on Control Panel.
Installing the Controller Program
The GECS Controller program can be installed from the Global ECS Windows CD ROM or you can FTP the
Controller programs from the Global ECS web site. Instructions to install from CD ROM or from images (EXE
files) off the web site are listed below. Go to your Controller machine and follow one of the sets of instructions
below.
Windows Controller from CD ROM
A. Login as Administrator or as an administrator equivalent user.
B. Insert the GECS Windows CD ROM. The installation program may automatically start after several
seconds. If the installation program does not automatically start, click the Start button, select Run and
Enter: D:\SUBTYPES
(Where D: is your CD ROM drive)
C. Click the Complete Installation option then click the OK button.
D. Click the Finish button to display the Global ECS Setup screen.
E. Again, use the default settings and click the Configure button, then click OK.
Windows Controller Exe File
A. Login as Administrator or as an administrator equivalent user.
B. Open a Command Prompt
C. Enter:
md c:\gecsctrl
D. Copy or ftp the EXE file to c:\gecsctrl (as binary)
E. Exit
F. Click the Start button, select Run, c:\gecsctrl\gecs-3.10-system.exe
G. Unzip into c:\gecsctrl
H. Unzip, click OK then Close.
10-3
GECS Controller
I. Click the Start button, select Run, c:\gecsctrl\setup.exe
The GECS Workstation Setup program can be used to create your Controller record, your Controller desktop icon
and, when desired, to setup your Controller to be run as a service.
GECS Express installation will automatically create and start your Controller as a service under the system account.
Monitoring Your Controller
You can check the status of your Controller program using the GECS Administrator Windows Client program or
using the Browser based Client programs.
From the Administrator program, click on the Controller Settings option and it displays the status of your Controller
and the last time it pulsed.
By right clicking on the Controller Settings option from the GECS Administrator’s list you can easily hide, show,
minimize, pause, resume, stop, ping or pulse your Controller.
You can view the status of your Controller using a browser by entering the appropriate URL as shown below:
http://ipaddress:http port/name
For example:
http://200.200.200.25:2011/CONTROL
You will then be prompted to enter a user name. You should enter the name of your Controller (CONTROL).
However, if the Controller was started with the command line parameters -s name (HTTP login name) and -t
pass (HTTP login password) the appropriate user name and password must be used.
10-4
GECS Controller
Controller Parameters
Your Controller record can be modified using the GECS Client programs. Your Controller record describes the
functions you want your Controller to perform. The GECS Administrator Windows Client program is displayed
below.
Controller Name
Your Controller name is CONTROL. This record is automatically created when you install GECS. This name
cannot be changed or deleted.
Controller Status
The “Controller Status” field displays the status of your Controller. GECS will automatically update this field.
Controller status is defined as:
Quit
- Your Controller has been stopped
Running
- Your Controller is running
Reset
- Your Controller has been reset
Paused
- Your Controller has been paused by its “Pause Filespec” file
10-5
GECS Controller
Last Pulsed
The “Last Pulsed” date and time fields are automatically updated by your Controller. This field contains the last
"activity" on your Controller. This may be the last time your Controller pulsed, the last time a job was dispatched or
other types of activity.
IP Address
The Controller “IP Address” field is used to enter the IP Address of the computer that will run this defined
Controller program. The address of the current machine is added by default.
Port
The Controller“Port” field is used to enter the port number on the machine that will run this defined Controller
program. The port number defaults to 2001.
Description
The Controller “Description” field is used to enter any miscellaneous description about your Controller. This
optional description will appears along with the Controller name in various places within the GECS Client
programs.
Pulse Rate
The Controller “Pulse Rate” field contains a number which tells your Controller how often, in seconds, it should poll
the system to see if there are any jobs to dispatch. It is NOT recommended that the pulse rate be set under 15
seconds.
There are two features, described below, (pulse now program and pulse file) to help you control pulsing and to
minimize the load put on the operating system and hardware by GECS while maintaining responsiveness.
Determining The Proper Pulse Rate
If you set up your Controller with a short pulse rate (30 seconds or less), your Controller will pulse quite frequently
and will be responsive. On the other hand, it may put more load on the hardware and operating system due to this
frequent checking than is necessary when there are no jobs to dispatch.
Additionally, they may not get enough spare time between pulses to perform their internal housekeeping such as
purging of completed jobs. If the pulse rate is set to 60 seconds or more, your Controller will put very little load on
the hardware and operating system when there are no jobs to dispatch. On the other hand, it might take a minute or so
before jobs are dispatched to Agents.
In general, a 60 second pulse rate should work fine most GECS processing schemes. When GECS is used to dispatch
large numbers of one time only jobs submitted by users in an ad hoc fashion, a pulse rate of 30 seconds might be
more desirable to deliver to them the responsiveness they are looking for, understanding that the load put on the
10-6
GECS Controller
hardware and operating system will be somewhat higher.
Pulse Now Program
The program PULSENOW.EXE can be run on your Controller machine at any time to cause it to stop waiting and
pulse. You can create an icon to run this program with a command line of:
C:\GECS\PULSENOW.EXE CONTROL IPADDRESS PORT
where ‘CONTROL’ is the name of your Controller. ‘IPADDRESS’ and ‘PORT’ is the IP address and port number
assigned to the Windows machine that is running your Controller program.
This program must be running in the computer where your Controller program is run. This program causes your
Controller to immediately pulse. If your Controller pulse rate has been set to 60 or 120 seconds or more to keep the
Controller’s load to a minimum and you believe there is work to be done, you can use this program to cause your
Controller to pulse now rather than waiting for the normal pulse time. The Controller will pulse at the next regular
pulse time interval after the “Pulse Now”.
Pulse File
Additionally, your Controller will look for a ‘pulse file’ while waiting and once it finds it, it will delete it, stop
waiting and pulse. The file is defined in GECS.INI in the Controller’s section:
[CONTROLLER]
PulseFile=filespec
When this entry is defined for your Controller, it will look for the specified ‘filespec’ while it waits.
Delete Jobs On Completion
You may indicate whether non recurring jobs should be deleted when complete or left on file, marked as completed.
When you check mark the “Delete Jobs on Completion” field, all jobs this Controller marked complete, will be
deleted except those jobs configured to “Keep when complete”.
See also the delete only successful jobs on completion GECS.INI file entry. By setting this entry, [Controller]
DeleteOnlySuccessfulJobs=1, failed jobs will be left on file.
Update Estimated Minutes
Check mark the “Update Estimated Minutes” field if you would like GECS to automatically update job’s estimated
run time each time they are run. The estimate is calculated using a weighted average formula.
new estimate = ((old estimate X 3) + actual minutes) / 4
10-7
GECS Controller
Ignore Users for WRK files
By default, GECS will only run jobs for users that are defined in the GECS User record. By check marking this field,
GECS will no longer reject jobs because they are from undefined users.
When this setting is set to 'Yes', GECS uses the user definition for the lowest alphabetical name on file in
determining how to process jobs.
Days Of Completed Jobs To Keep
GECS can automatically 'trim' your completed job records. If you want GECS to automatically delete completed
job records, enter the number of days of completed jobs that should be maintained in the “Days of Completed Jobs
To Keep” field. If you don't want it to automatically trim your completed jobs file, enter '0' in this field.
Add New Jobs From WRK Files
The “Add New Jobs” field must be check marked if you want your GECS to look for WRK files and add them as jobs
to be executed.
WRK Files Path
Use the “WRK File Path” field to specify the subdirectory where GECS should look for WRK files. This field
works much like the PATH command. You can include more than one subdirectory name, separated by a semicolon
(;) if you want. For example:
F:\GECS\;F:\WRKFILES;F:\GECS\DATA\WRKFILES
By default, this field contains a dot (.). The dot causes GECS to look for .WRK in the directory where your GECS
programs are installed.
Charge Multiplier
The “Charge Multiplier” field is used to indicate an amount to charge users for executing their jobs. The GECS User
record “Charge Per Job” and/or “Charge Per Second” fields must be populated and are multiplied times the number
entered in this field.
Charge Users For Jobs
The “Charge Users for Jobs” field is used to indicate whether or not GECS should calculate charges for the jobs that
get executed by Agents. You must set the GECS User record’s “Charge Per Job” and/or “Per Second Charge”
field(s) in order to use this feature.
10-8
GECS Controller
Comments
The “Comments” field is an optional field that can be used to enter a miscellaneous comment about your Controller.
Controller - Network Tab
The Network tab found in the Controller Settings screens contain several fields which are described below.
Time Sync Type
Your Controller can be configured to synchronize its time using one of the time synchronization methods below:
- None
- Microsoft
- NetWare
- Time Protocol (RFC-868)
- NTP/SNTP (RFC-1305/1361/1769/2030)
Time Sync File Server
The “Time Sync File Server” field can be used to synchronize the computer’s time, that is running your Controller
with another computer on the network.
If you wish to time sync to a NetWare file server you must have NetWare drivers installed. Likewise, if you wish to
time sync to a Windows Server machine, you must have Microsoft drivers installed.
During every pulse, your Controller with a Time Sync Server name entered will update the time on the machine with
the time of the computer specified. For example:
TESTSRV1
\\FILESRVR
123.123.123.123:37
123.123.123.123:123
Controller - Control Tab
The Control tab found in the Controller Settings screens contain a variety of fields as described below.
Halt Filespec
The “Halt Filespec” field is used to define a fully qualified path and file name, that when found, will cause your
Controller to immediately stop/terminate (all running jobs) and shut down/exit your Controller. Your Controller
10-9
GECS Controller
looks for this file during each pulse cycle.
Before restarting your Controller, you must delete the file that caused your Controller to exit. If you don’t, your
Controller will immediately halt again.
Exit Filespec
The “Exit Filespec”field is used to define a fully qualified path and file name, that when found, will cause your
Controller to shut down/exit (once all running jobs have finished). While waiting for running jobs to stop, it will not
start any new jobs. Your Controller looks for this file during each pulse cycle.
Before restarting your Controller, you must delete the file that caused your Controller to exit. If you don’t, your
Controller will immediately exit again.
Pause Filespec
The “Pause Filespec”field is used to define a fully qualified path and file name, that when found, will cause your
Controller to stop launching any new jobs until the filespec disappears. While the filespec exists, your Controller
“Status” is set to “Paused” and it stays in a sleeping type mode. Your Controller looks for this file during each pulse
cycle.
Before restarting your Controller, you must delete the file that caused your Controller to pause. If you don’t, your
Controller will immediately pause again. See also the “Use Controller Pause Times” field to allow your Controller
to automatically create and delete your pause filespec.
Use Controller Pause Times
The “Use Controller Pause Times” field is used to set up your Controller to automatically pause and unpause itself,
as described above, based on the times entered in the “Pause At” and “Unpause At” fields.
To enable this feature, you must have a “Pause Filespec” defined.
Pause At / Unpause At
The “Pause At” and “Unpause At” fields are used to allow your Controller to automatically create and delete the
filespec you have defined for your “Pause Filespec”. This file will be created and deleted according to the times
entered in these fields for when your Controller should automatically pause/resume processing. Your Controller
will ignore this field if it is set to 00:00:00 (midnight). For example:
Pause At:
23:00:00
Unpause At:
00:30:00
would pause your Controller daily at 11pm until 12:30am.
To enable this feature, you must have a “Pause Filespec” defined and the field, “Use Controller Pause Times” must
be check marked.
10-10
GECS Controller
Reset Command
The “Reset Command” field is used to define a command line to be executed if your Controller is having a problem.
(i.e. The Controller’s “Last Pulsed” time has not been updated within its “Reset Minutes”.)
Your reset command could send a message, email or even a page, using whatever command line utility you’d like.
For example, in a Novell environment, you might define the Reset Command for CONTROL as:
SEND "Controller CONTROL Requires Attention" to SUPERVISOR
In a Microsoft environment you might define the Reset Command for CONTROL as:
NET SEND Supervisor Controller CONTROL Requires Attention
or run a batch file that calls your paging software, which sends you a page to notify you that your Controller is in
trouble:
C:\GECS\BEEPME.BAT
The reset command defined for your Controller will be launched if your Controller is believed to be hung.
Your Controller is considered to be hung when ALL the following occur:
1. Your Controller has a Reset Command defined.
2. Your Controller has a blank Viewed By field.
3. Your Controller has a non-zero value for the Last Access Date & Time fields.
4. Your Controller has a non-zero value for Maximum No Access Minutes field.
5. The Last Access Date & Time PLUS the Maximum No Access Minutes is a time in the past.
6. Your Controller’s Status is NOT Quit or Reset.
7. Your Controller’s pause, exit or halt files cannot be found.
Besides simply executing the reset command, GECS also changes the “Status” of your Controller to “Reset”, so the
command will only be executed once.
Note that the program you want GECS to run to reset your Controller may be too large to fit into memory. If you
receive "Insufficient Memory" errors trying to execute your reset command, you can begin the command with an
asterisk (*). This tells the setup or client program to unload itself before executing the command. You will have all
but 30K of your conventional memory available for executing the command.
Controller - Defaults Tab
The fields listed in Controller Settings Defaults tab are used to tell your Controller what it should use as defaults for
the jobs it adds. If a particular job parameter is omitted in a WRK file, GECS will use the information entered here
for the job. These default values are also used by the GECS Client programs when creating new job records.
Controller - Mail Tab
The Mail tab in the Controller record is used to check email messages for wrk files to convert into jobs.
Accept WRK Files Via Mail
The “Accept WRK File Via Mail” field must be enabled if you want GECS to accept WRK files via email.
10-11
GECS Controller
GECS is sent a piece of email just as if it was a user. The text of the message contains the lines of the WRK file or the
WRK file can be sent to GECS as an attachment to the message. If attachments are sent, the text of the message is
ignored.
Mail System
Use the “Mail System” field to indicate the type of mail system you are going to use for GECS to accept WRK files
via mail. If email is not going to be used by GECS to pick up WRK files, select None. Your options are:
- None
- Novell MHS
- Microsoft Mail
- cc:Mail
- Notes Mail
- Internet Mail
Mail User Name
GECS can be assigned it’s own email address for checking for WRK files to convert into real jobs.
Use the “Mail User Name” field to enter the email user name assigned to GECS for receiving WRK files. The
format is username (with optional[:password]) following the selected email system's name guidelines. For
example:
GECSWRK
- for MHS Mail
GECSWRK:password
- for MS Mail
GECSWRK
- for MS Exchange Mail
GECSWRK
- for cc:Mail
leave this field blank
- for Notes Mail
gecswrk@vinsoft.com
- for Internet Mail
Mail Password
Use the “Mail Password” field to enter your GECS email password for receiving WRK files. Follow the selected
email system guidelines.
You would leave this field blank if you specify a password in the “Mail User Name” field using the optional
password parameter.
password
- for MHS Mail
password
- for MS Mail
password
- for MS Exchange Mail
password
- for cc:Mail
password
- for Notes Mail
10-12
GECS Controller
password
- for Internet Mail
For security purposes the password you enter will not be displayed. This field will automatically be filled in with
asterisks.
Mail Subdirectory
Use the “Mail Subdirectory” field to enter the drive and subdirectory of the selected email system. This would
typically be something like:
F:\MHS\MAIL
- for MHS
F:\WGPO
- for MS Mail
leave this field blank
- for MS Exchange Mail
M:\CCDATA
- for ccMail
leave this field blank
- for Notes Mail
mail.isp.net
- for Internet Mail
Mail Pulse
The “Mail Pulse” field is used to enter the amount of time, in seconds, you would like your GECS to look for WRK
file via mail. 0 = use your Controller’s “Pulse Rate”.
Starting and Stopping your
Controller
Desktop Controller Start Up Command Line Options:
The GECS Workstation Setup program creates an icon on the desktop for the Controller. Start it by double clicking
on the Controller shortcut icon. This program is started by running GECSPROC.EXE. There are special startup
options listed below. These options can either be run from the command line, or can be entered in the shortcut
properties for the Controller when run from a desktop icon.
Usage: gecsproc name [-p portnum]...
name
Controller’s GECS name “CONTROL”
-c ini
The INI file to use
-h
Run hidden
-m
Start minimized
-p port
Use ‘port’ rather than port 2001
-q port
Use ‘port’ for HTTP rather than port 2011 (0=disabled)
-s name
HTTP login name
10-13
GECS Controller
-t pass
HTTP login password
-u path
Path for misc. HTTP files
-v
Verbose messages
For example:
GECSPROC.EXE NAME [-P port]
C:\GECS\GECSPROC.EXE control -P 2001
where ‘CONTROL’ is the name defined for your Controller and -P for optional port. The default port is 2001.
Your Controller must be running in order to dispatch jobs to your Agents. When the Controller is running on the
desktop, it has the rights of the user logged in. It will only run as long as someone is logged in
To shutdown your Controller, type ‘exit’. It may take your Controller several seconds to complete the shutdown
process.
Information on running your GECS Controller as a service is described later in this chapter.
Your GECS Controller can be run so that it is shown on the screen, or it can be run hidden from view. Once hidden,
you can bring it back into the foreground by running the ‘Show Controller’ command. Your Controller can be
started in hidden mode by including the -H command line option:
GECSPROC.EXE CONTROL -H
By including an icon in the startup group with the -H option, your Controller will start hidden every time Windows
is started.
Your Controller can also be started minimized by using the -M command line option:
GECSPROC.EXE CONTROL -M
Once minimized, you can open it back up by running the ‘Show Controller’ command.
Configuring Your Controller
Running the Controller as a Service
Windows NT introduced the concept of “services”. A service is a software program that is automatically started
when Windows starts, but before anyone logs in. Services start before the user logs in and continue to run even after
the user logs out. Database servers and file servers are types of programs that would normally be run as services.
The Controller can be installed to run as a service. GECS will execute submitted jobs as long as Windows is
running, even if no one is logged in to the console. There are several setup issues that must be considered as well.
Regardless, running GECS as a service under Windows can be used in a wide variety of ways and can greatly
enhance the functionality of Windows.
By using the default settings, GECS runs in the security context of the local system account and uses the default
Station/Desktop. Beginning with Windows NT version 3.5, the system accounts privileges have been modified to
limit access to local and network resources thereby limiting the privileges of GECS and its jobs. To regain control
over the resources GECS has access to, GECS must be setup to run within the account of a specific user. Use the
procedures outlined below to create a GECS user account and setup GECS to use the new account.
10-14
GECS Controller
Creating User Accounts
Assigning a specific user account to a GECS Controller allows control over the security access to local and network
resources. To setup a GECS Controller user account, Log on to Windows as the system administrator or a user who
has rights to create new users. Using the Windows User Manager, create a new user using the information specified
below.
Username:
CONTROL (use your Controller name)
Full Name:
GECS Job Controller
Description:
Job Controller Logon Account
Password:
xxxxxxx
[x] Password Never Expires
Use User Manager’s User Rights Policy dialog to grant the required rights to the Controller user account. The rights
required for the Controller to dispatch the submitted jobs varies with each installation of GECS. These rights
MUST be determined by you. In addition to these rights, the Controller’s logon account MUST have the following
advanced User Rights. Note that ‘Show Advanced User Rights’ must be checked to display the necessary rights.
Act as part of the operating system
Increase quotas
Log on as a service
Replace a process level token
By making the Controller User Account a member of the Administrators group, GECS will have full control of the
local system. This may not be the desired behavior of your particular system. To change the rights of the Controller
Account, first create a new user group and then make the Controller Account a member of this group, at which point
you may change the User rights for this specific group. (See User Manager Help for more information on creating
New Groups, New Users and User Rights).
If the Controller using this account reads its data files from a networked file server, the account must have Full
Access to the share that is used to reference the file server where the GECS data is located.
GECS Service Program
The CSERVICE.EXE program is used to start the service. This program is run automatically by the Windows
service manager and should never be run directly.
GECS Service Installation
The Workstation Setup program C40SETUP.EXE can configure your Controller to run either on the desktop or as
services. The services can run using the system account or under a specified user account.
To setup your Controller to run as a Windows service, see the Custom Installation chapter of this manual.
The Workstation Setup program will automatically configure the specified Controller to run as a service. It will also
add the appropriate registry information.
GECS Service Removal
The GECS Workstation Setup program can be used to remove a service. To remove a service, simply select Run
from a desktop icon option in the Controller Information section of the Workstation Setup program.
10-15
GECS Controller
Pause GECS Controller from Windows Service Manager
When a “Pause Filespec” is defined for your GECS Controller running as a service, the GECS Controller can be
paused using the Windows service manager.
Controller Window Commands
Usage:
EXIT, STOP, QUIT
- Shutdown the Controller
HIDE
- Hide the Controller
MINI
- Minimize the Controller
PULSE
- Pulse the Controller Now
TEST
- Pulse the Controller Now and Test all Agents
VERSION
- Display version
CLS, CLEAR
- Clear screen
TIME
- Display time
LIST
- List active jobs
VERBOSE, QUIET
- Toggle verbose messages
ADDRESS
- Display addresses
Uninstalling GECS
Be sure all GECS programs are stopped before uninstalling.
Windows Client, Controller, or Agent
1. From Control Panel, click Add/Remove Programs.
2. Select the Global Event Control Server then choose Uninstall.
3. Indicate whether or not to delete program and data files.
4. Click the Uninstall button.
10-16
GECS DBMS
GECS DBMS
11-1
GECS DBMS
11-2
GECS DBMS
GECS DBMS Overview
The GECS DBMS program (GECSDBMS.EXE) is one of the most important components of the GECS system.
The DBMS allows access to the GECS data files. The DBMS must be running in order to use any of the components
of the GECS System. This program is designed to run continuously.
Installing the DBMS Program
The GECS DBMS program can be installed from the Global ECS Windows CD ROM or you can FTP the DBMS
program from the Global ECS web site. Instructions to install from CD ROM or from images (EXE files) off the
web site are listed below. Go to your DBMS machine and follow one of the sets of instructions below.
DBMS from CD ROM
A. Login as Administrator or as an administrator equivalent user.
B. Insert the GECS Windows CD ROM. The installation program may automatically start after several
seconds. If the installation program does not automatically start, click the Start button, select Run and
Enter: D:\SUBTYPES
(Where D: is your CD ROM drive)
C. Click the Complete Installation option then click the OK button.
D. Click the Finish button to display the Global ECS Setup screen.
E. Again, use the default settings and click the Configure button, then click OK.
DBMS Exe File
A. Login as Administrator or as an administrator equivalent user.
B. Open a Command Prompt
C. Enter:
md c:\gecsctrl
D. Copy or ftp the EXE file to c:\gecsctrl (as binary)
E. Exit
F. Click the Start button, select Run, c:\gecsctrl\gecs-3.10-system.exe
G. Unzip into c:\gecsctrl
H. Unzip, click OK then Close.
I. Click the Start button, select Run, c:\gecsctrl\setup.exe
The GECS Workstation Setup program will create your DBMS record, your DBMS desktop icon and, when
desired, to setup your DBMS to be run as a service.
GECS Express installation will automatically create and start your DBMS as a service under the system account.
11-3
GECS DBMS
Monitoring Your DBMS
You can check the status of your DBMS using the GECS Administrator client program or using the web Client
programs.
The status of your DBMS can be viewed by clicking on the DBMS Settings option from the GECS Administrator
program.
By right clicking on the DBMS Settings option from the GECS Administrator’s list you can easily hide, show,
minimize and ping your DBMS.
You can view the status of your DBMS using a browser by entering the appropriate URL as shown below:
http://ipaddress:httpport/name
For example:
http://200.200.200.37:2012/DBMS
You will then be prompted to enter a user name. You should enter the name of your DBMS (DBMS). However, if
the DBMS was started with the command line parameters -s name (HTTP login name) and -t pass (HTTP
login password) the appropriate user name and password must be used.
DBMS Parameters
Your DBMS record is automatically created and can be updated using the GECS Client programs. From the GECS
Administrator Client program use the DBMS settings folder to update your GECS DBMS record. Your DBMS
record describes the functions you want your DBMS to perform.
The DBMS Settings screen is displayed below.
11-4
GECS DBMS
DBMS Name
Your GECS DBMS is automatically named DBMS. This name cannot be changed.
Status
The DBMS “Status” field displays the status of your DBMS. Your DBMS will automatically update this field. You
cannot edit this field. DBMS status is defined as:
Quit
- Your DBMS has been stopped
Running
- Your DBMS is running
IP Address
The DBMS “IP Address” field is used to enter the IP Address of the computer that will run your DBMS program.
The address of the current machine is added by default.
Port
The DBMS“Port” field is used to enter the port number on the machine that will run your DBMS program. The port
number defaults to 2002.
Description
The DBMS “Description” field is used to enter any miscellaneous description about your DBMS. This optional
description will appears along with the DBMS name in various places within the GECS Client programs.
Comments
The “Comments” field is an optional field that can be used to enter a miscellaneous comment about your DBMS.
Days Of Events To Keep
Your GECS DBMS program can automatically 'trim' the list of Events. If you want your DBMS to automatically
delete old Event records, enter the number of days of Events that should be maintained in the “Days of Events To
Keep” field. If you don't want it to automatically trim the Events, enter '0' in this field.
11-5
GECS DBMS
DBMS Mail
Your DBMS can be configured to send email when a particular Event occurs. You must specify the type of email
your DBMS is to send and you must also specify within each Event Definition which Events you wish to send email
on.
Mail System
Use the “Mail System” field to indicate the type of mail system you are going to use to send email messages on
Events. Each Event you wish to receive email must be configured in Event Definitions. If email is not going to be
used with GECS, select No Your options are:
- None
- Novell
- Microsoft Mail
- cc:Mail
- Notes Mail
- Internet Mail
Mail User
The DBMS can be assigned its own mail address. It can then send mail messages when certain GECS Events occur.
After configuring your DBMS record to send mail, you simply update the Event Definitions for the Events you
would like to be notified of. For example, email can be sent about Events pertaining to your jobs and/or your GECS
System.
Use this field to enter the from mail user name assigned to this DBMS. The format is username (with
optional[:password]) following the selected mail system's name guidelines.
For example:
DBMS
for MHS Mail
ProfileName
for Microsoft Mail
DBMS
for cc:Mail
leave this field blank
for Notes Mail
12345dbms
for Internet Mail (sending from name)
Mail Password
Use the “Mail Password” field to enter your GECS DBMS's email password. Follow the selected email system
guidelines.
You would leave this field blank if you specify a password in the “Mail User Name” field using the optional
password parameter.
11-6
GECS DBMS
password
- for Mail
password
- for Microsoft Mail
password
- for cc:Mail
password
- for Notes Mail
password
- for Internet Mail
For security purposes the password you enter will not be displayed. This field will automatically be filled in with
asterisks.
Mail Subdirectory
Use the “Mail Subdirectory” field to enter the drive and subdirectory of the selected email system. This would
typically be something like:
F:\\MAIL
- for MHS
F:\
- for MS Mail
leave this field blank
- for MS Exchange Mail
M:\
- for ccMail
leave this field blank
- for Notes Mail
mail..net
- for Internet Mail
Time Sync Type
Your DBMS can be configured to synchronize its time using one of the time synchronization methods below:
- None
- Microsoft
- NetWare
- Time Protocol (RFC-868)
- NTP/SNTP (RFC-1305/1361/1769/2030)
Time Sync File Server
The “Time Sync File Server” field can be used to synchronize the computer’s time, that is running your DBMS with
another computer on the network.
If you wish to time sync to a NetWare file server you must have NetWare drivers installed. Likewise, if you wish to
time sync to a Windows Server machine, you must have Microsoft drivers installed.
When your DBMS has a Time Sync Server name entered it will update the time on the machine with the time of the
computer specified. For example:
TESTSRV1
\\
11-7
GECS DBMS
123.123.123.123:37
123.123.123.123:123
Configuring the DBMS
The DBMS must run on a Windows NT/2000/XP/2003 computer. The DBMS can run from a desktop icon, as a
service under the system account or as a service under a specified user account. Use the GECS Workstation Setup
program to configure the DBMS program.
DBMS Data Backup
You can backup your GECS system data by clicking on the Backup toolbar button in the DBMS Settings screen.
This will backup all files which exist in your GECS data directory. By default this directory is C:\GECS\DATA.
You will be prompted to enter the drive and subdirectory of the location where you would like your GECS data
directory to be backed up into. This directory is relative to the computer on which the DBMS is running.
The Backup procedure initiates an asynchronous backup of the GECS data files. All database transaction are
suspended until the backup is complete. The archived data files may then be safely moved to tape or another storage
device. Data file integrity is maintained in the event that a system restore is required.
Scheduled Backups
You can schedule a GECS job to automatically backup up your GECS data files on which ever type of schedule you
choose. Use the GECSBKUP command line utility for your jobs command line as show in the example below.
Usage: GECSBKUP subdir
(where subdir is the directory where you wish to have your data saved to)
Job Command Line: C:\GECS\GECSBKUP F:\BACKUP\GECSDATA
The DBMS will backup the data therefore, the directory entered is relative to the DBMS.
You can also use GECS substitution variables to enable your backup job to copy the data into a separate folder for
each day of the week. It is a good idea to have separate copies of data to use to restore from file corruption or user
errors. You would schedule your job to repeat daily and use substitution variables as follows:
Job Command Line: C:\GECS\GECSBKUP F:\BACKUP\GECSDATA\@SCHDATE(%a)
@SCHDATE will substitute the job’s schedule date and the (%a) would use the day of the week format such as Sun,
Mon, Tue, etc. (Note that substitution variables must be all upper case). You would end up with GECS data copied
to the F:\BACKUP\GECSDATA\Sun, F:\BACKUP\GECSDATA\Mon and F:\BACKUP\GECSDATA\Wed
folders respectively.
11-8
GECS DBMS
After setting up and running jobs to backup your GECS data files. You should test your scheme by shutting down
your system and restoring your data. You should test copying individual .DAT and .IDX files and test copying all
files into your GECS Data directory.
Setting up a GECS Fail Over System
The following are recommendations on minimizing the effects of Global ECS system failure. (primary
Controller/DBMS machine hangs, loses logical or physical network connection, loses power etc.). Also
suggestions to prepare for failure and recovery procedures. Depending on the environment there may be alternative
solutions. You should periodically test your fail over and recovery plans.
1. To decrease your chances of failure, install the Global ECS Controller, DBMS, Web Manager and GECS data
locally on one Windows machine. We will call this the Primary GECS machine. Do not run any Agents or install
other software on this machine. This will eliminate the chances of network problems and eliminate the chances of
other software affecting machine performance.
2. Secondary GECS machine: Install and configure Global ECS on a second Windows machine with access to a
secondary GECS data folder. This Secondary system should have all GECS components configured to be run ‘From
Desktop Icons’. The secondary DBMS and Controller programs should NOT be started until needed.
3. Primary GECS machine: Periodically launch a job that copies GECS data to a secondary GECS folder, accessible
to the Secondary DBMS/Controller machine.
GECS System Recovery Procedures
If your Primary GECS Machine goes down, there are a couple of quick steps you can take to get GECS up and
running on another machine. To start up your fail over system described above, follow the steps below.
1. Once the Primary Machine is no longer running, go to the Backup machine and start the DBMS from a desktop
icon. Open the Administrator program and look at your jobs. Depending on when the Data files were copied, you
may have some jobs that have very recently run that are not reflected in the set of data you are viewing.
2. Once you have determined which jobs have already run, you can ‘Skip and Reschedule’ them so they do not run
twice. If your data is up to date you may not have to do anything.
11-9
GECS DBMS
3. When Pending jobs have been checked, open the Workstation setup program and configure your GECS
components to run as your Primary GECS System was configured, either ‘From Desktop Icons’ or ‘As Services’.
Once configured, services will automatically start. Components configured to run on the desktop should be started
by double clicking the respective icons.
If you need to restore your Global ECS system and you do not have a fail over system already installed, you can
install GECS programs from the Global ECS web site at www.globalecs.com. You must have a backup copy of
your data files to restore and you must verify the version of Global ECS programs. Install the GECS programs and
configure all components to initially run on the desktop. After installing a new GECS system, shut down all GECS
components and copy in your restored data files. Start the DBMS and verify your job records are ok to run. Once
your job streams are verified, run the Workstation Setup program and configure your components to run as you like.
Starting and Stopping the DBMS
The DBMS can run from a desktop icon, as a service under the system account or as a service under a specified user
account. When run from a desktop icon you can start it by double clicking on the icon. When run as a service, the
DBMS program will automatically start when the operating system starts.
There are special startup options listed below. These options can either be run from the command line, or can be
entered in the shortcut properties for the DBMS when run from a desktop icon.
DBMS Desktop Startup Command Line Options
Usage: gecsdbms [-n name]...
-c ini
The INI file to use
-h
Run hidden
-m
Run minimized
-n name
DBMS’s GECS name
-p port
Use ‘port’ rather than port 2002
-q port
Use ‘port’ for HTTP rather than pot 2012 (0=disable)
-s name
HTTP login name
-t pass
HTTP login password
-u path
Path for misc. HTTP files
-v
Verbose messages
To stop the DBMS program when running from a desktop icon, type ‘exit’, ‘quit’, or ‘stop’ in the DBMS command
shell window. To shut down the DBMS running as a service, go to Control Panel, Services and stop the DBMS
service.
11-10
GECS DBMS
DBMS Window Commands
When the GECS DBMS program is not running as a service, you can type the following commands into the DBMS
window.
Usage:
EXIT, STOP, QUIT
- Shutdown the DBMS
HIDE
- Hide the DBMS
MINI
- Minimize the DBMS
VERSION
- Display version
CLS, CLEAR
- Clear screen
TIME
- Display time
VERBOSE, QUIET
- Toggle verbose messages
ADDRESS
- Display address
CLIENTS
- Display clients
HANDLES
- Display handles
LICENSE
- Display Agent License Information
Uninstalling GECS
Be sure all GECS programs are stopped before uninstalling.
Windows Client, Controller, DBMS or Agent
1. From Control Panel, click Add/Remove Programs.
2. Select the Global Event Control Server then choose Uninstall.
3. Indicate whether or not to delete program and data files.
4. Click the Uninstall button.
11-11
GECS DBMS
11-12
GECS Web Manager and Browser Clients
GECS Web Manager and
Browser Clients
12-1
GECS Web Manager and Browser Clients
12-2
GECS Web Manager and Browser Clients
GECS Web Manager Overview
The GECS Web Manager program (GECSWEBS.EXE) allows access via a browser to the GECS data files.
Configuring your Web Manager
The Web Manager must run on a Windows NT/2000/XP/2003 computer. It can run from a desktop icon, as a service
under the system account or as a service under a specified user account. Use the GECS Workstation Setup program
to configure the Web Manager program.
Starting and Stopping the Web
Manager
The Web Manager can run from a desktop icon, as a service under the system account or as a service under a
specified user account. When run from a desktop icon you can start it by double clicking on the icon. When run as a
service, the Web Manager program will automatically start when the operating system starts.
There are special startup options listed below. These options can either be run from the command line, or can be
entered in the shortcut properties for the Web Manager when run from a desktop icon.
Web Manager Desktop Startup Command Line Options
Usage: gecswebs [-n name]...
-c ini
The INI file name to use
-h
Run hidden
-m
Run minimized
-n name
Web Manager’s GECS name
-p port
Use ‘port’ rather than port 2003
-q port
Use ‘port’ for HTTP rather than pot 2013 (0=disable)
-u path
Use ‘path’ for HTTP files rather than the working directory
-v
Verbose messages
To stop the Web Manager program when running from a desktop icon, type ‘exit’, ‘quit’, or ‘stop’ in the Web
Manager command shell window. To shut down the Web Manager running as a service, go to Control Panel,
Services and stop the Web Manager service.
12-3
GECS Web Manager and Browser Clients
Web Manager Window Commands
When the GECS Web Manager program is not being run as a service, you can type the following commands into the
Web Manager window.
Usage:
EXIT, STOP, QUIT
- Shutdown the Web Manager
HIDE
- Hide the Web Manager
MINI
- Minimize the Web Manager
VERSION
- Display version
CLS, CLEAR
- Clear screen
TIME
- Display time
VERBOSE, QUIET
- Toggle verbose messages
ADDRESS
- Display address
Using GECS Browser Client Programs
The Web Manager program allows users to access the GECS data files remotely from most any machine using a
browser. After pointing your browser at the URL you are prompted to login to the GECS System. After GECS
validates your user name and password, you can monitor or update the GECS system from the web pages displayed
on your browser. No software or special configuration is required on users computers.
12-4
GECS Web Manager and Browser Clients
Opening GECS Browser Client Programs
To check GECS components from a browser, open your browser program and enter the appropriate URL as shown
below:
http://ipaddress : port / name
Web Manager
To open your GECS browser Client programs, open your browser program and enter the Web Manager IP Address
and HTTP Port Number. For example:
http://200.200.200.25:2013
From a computer where GECS is installed, you can double click the Global ECS browser icon to access the browser
Client programs.
You will be prompted to enter a username and password. You can enter any valid GECS user name.
Agents
To check your Agent from a browser, open your browser program and enter the Agent IP Address, HTTP Port
Number and Agent Name. For example:
http://200.200.200.205:2010/NED
You will be prompted to enter a username and password. For the user name, enter the name of the Agent, in this
example you would enter NED. However, if the Agent was started with the command line parameters -s name
(HTTP login name) and -t pass (HTTP login password) the appropriate user name and password must be used.
Controller
To check your Controller from a browser, open your browser program and enter the Controller IP Address, HTTP
Port Number and Controller Name. For example:
http://200.200.200.189:2011/CONTROL
You will be prompted to enter a username and password. For the user name, enter the name of the Controller, you
would enter CONTROL. However, if the Controller was started with the command line parameters -s name
(HTTP login name) and -t pass (HTTP login password) the appropriate user name and password must be used.
DBMS
To check your DBMS from a browser, open your browser program and enter the DBMS IP Address, HTTP Port
Number and DBMS Name. For example:
http://200.200.200.37:2012/DBMS
12-5
GECS Web Manager and Browser Clients
You will be prompted to enter a username and password. For the user name, enter the name of the DBMS, you
would enter DBMS. However, if the DBMS was started with the command line parameters -s name (HTTP login
name) and -t pass (HTTP login password) the appropriate user name and password must be used.
12-6
GECS Utility Programs
GECS Utility Programs
13-1
GECS Utility Programs
13-2
GECS Utility Programs
GECS Command Line Utilities
GECS ships special command line utility programs that must be run on a command line. These programs install into
your GECS directory. Some of these programs require exclusive use of the GECS data files and therefore, can only
be run when your GECS programs are shut down. Utility programs include the following:
BATCHDON
- Batch dependencies program
GECSAUSR
- Add users utility
GECSBKUP
- Data backup utility
GECSBREM
- Remove scheduled batch jobs program
GECSBSCH
- Schedule batch jobs program
GECSCALE
- Add calendars utility
GECSCAN
- Can do program
GECSCANT
- Can’t do program
GECSCERT
- Certificate Security program
GECSCHNG
- Trigger File Change Utility
GECSCLEA
- Cleanup utility
GECSCNUM
- Change job number utility
GECSCONV
- Convert utility
GECSCUSE
- Change user utility
GECSDEL
- Job delete utility
GECSDUMP
- Job export utility
GECSEDEL
- Event Delete utility
GECSEVNT
- Add Events utility
GECSHIDE
- Used to hide a Windows Agent/Controller program window
GECSLAUN
- Internal Unix utility (Agent)
GECSLDEL
- Completed job delete utility
GECSLDUM
- Completed job export utility
GECSOVER
- Job override utility
GECSPASS
- Password change program
GECSPAUS
- Used to Pause/Unpause remotely
GECSPING
- Used to test the status of Agents
GECSPURG
- Job purge utility
GECSQUEU
- Queue program
GECSQUIC
- Quick job adding program
GECSRBLD
- Rebuild utility
GECSRET
- (DOSRET, OS2RET, WINRET & WINRET32) Return code testing
executables
GECSSHOW
- Used to display a hidden Windows Agent/Controller
13-3
GECS Utility Programs
GECSSIZE
- Trigger File Size utiltiy
GECSSTOP
- Used to stop an Agent/Controller
GECSSTP
- Stop job utility
GECSTRIG
- Job trigger utility
GECSVAL
- Validate utility
PULSENOW
- Used to immediately pulse your Controller
BATCHDON - Batch Dependency Utility
This program checks to see that one or more Batches (BATCH2 thru BATCHn) have successfully completed since
another batch (BATCH1) last ran.add users utility,
BATCHDON.EXE [/WAIT] jobnum batch1 batch2 ... batchn
Zero is returned if the batches completed and non zero if they didn’t. This job is designed to be the first job in a batch,
with the other jobs in the batch depending on it. It can then test to see if the predecessor batch(s) have completed. The
program looks at all the jobs in the batch (batch1) to see when the last of them finished. The job that launches this
program must be excluded from this calculation, since it is running now. Consequently, its job number (jobnum) must
be included on the command line, so it can be excluded. The /WAIT parameter will cause the program to stop and
wait for a key for use in testing and debugging. For example:
BATCH1
BATCH2
BATCH3
BATCH1.1
BATCH2.1
BATCH3.1
BATCH1.2
BATCH2.2
BATCH3.2
BATCH1.3
BATCH2.3
BATCH3.3
BATCH1.4
BATCH2.4
BATCH3.4
BATCH1.5
BATCH2.5
BATCH3.5
BATCH1.6
BATCH2.6
BATCH3.6
BATCH1.7
BATCH2.7
BATCH3.7
BATCH1.8
BATCH2.8
BATCH3.8
BATCH1.9
BATCH2.9
BATCH3.9
BATCH4
BATCH4.1 cmdline BATCHDON BATCH4.1 BATCH4 BATCH1 BATCH2 BATCH3
retry if return code is greater than or equal to 1
number of times to retry = 0 (infinite)
BATCH4.2 depends on BATCH4.1 returning 0
BATCH4.3 depends on BATCH4.1 returning 0
BATCH4.4 depends on BATCH4.1 returning 0
BATCH4.5 depends on BATCH4.1 returning 0
BATCH4.6 depends on BATCH4.1 returning 0
BATCH4.7 depends on BATCH4.1 returning 0
13-4
GECS Utility Programs
BATCH4.8 depends on BATCH4.1 returning 0
BATCH4.9 depends on BATCH4.1 returning 0
There are four batchs of jobs, BATCH1, BATCH2, BATCH3 and BATCH4. Each batch contains a number of jobs.
You don’t want any of the jobs in BATCH4 to start until all the jobs in BATCH1, BATCH2 and BATCH3 are
complete. You would make all the jobs in BATCH4 (except BATCH4.1) depend on BATCH4.1. The BATCH4.1
job would run the BATCHDON program as shown and would be setup to retry on failure as shown.
When used as shown, none of the jobs in BATCH4 would run untill all the jobs in BATCH1, BATCH2 and
BATCH3 have run. The program also respects the ‘maximum good return code’ field. If one of the predecessor jobs
completed, but with a return code greater than the maximum good return code, the job isn’t considered complete.
All the jobs in the predecessor batches (BATCH1, BATCH2 and BATCH3) must repeat as often, or more often,
than the jobs in BATCH4.
If not, BATCH4 jobs will repeat with the same frequency as the least often repeating job in BATCH1, BATCH2 or
BATCH3.
Note that the batchdon program must be installed on the agent machine along with the client programs installed on
the agent machine. This is because the GECS.INI file is required to be on the agent machine.
GECSAUSR - Add Users Utility
The add users utility, GECSAUSR, allows you to automate the process of adding a large number of users to the
GECS users file. This program reads a comma separated file that contains a list of user names and optionally their
password. The users in the file are added to the GECS users file. A template username is specified and the users that
are added are created ‘like’ the template user. The program is run by entering:
GECSAUSR [/NOSTOP] templateuser filename
The comma separated file is in the format:
“username”
“username”
“username”
or
“username”, “password”
“username”, “password”
“username”, “password”
For example, if you had manually added a GECS user named JOE and had created the following comma separated
file named USERS.CSV:
“SALLY”, “123"
”SAM", “234"
”WALLY", “345"
you could have this utility automatically add these users with similar security as existing user JOE, by entering:
GECSAUSR JOE F:\USERS.CSV
The /NOSTOP option causes the program to exit immediately upon completion.
13-5
GECS Utility Programs
GECSBKUP - Data Backup Utility
The data backup utility, GECSBKUP, can be run to make backup copies of your GECS data directory. You will
need to enter the drive and subdirectory of the location you would like your GECS data directory to be backed up
into. For instance:
GECSBKUP F:\BACKUP
A GECS job can be scheduled to launch this backup utility. This way you can automatically have your GECS data
directory backed up as often as you like.
GECSBREM - Remove Scheduled Batch jobs program
Removing scheduled jobs will actually delete, from the JOBS table, the jobs of a previously scheduled GECS Batch.
A batch may be removed by using either the standalone GECSBREM.EXE program, which will allow this program
to be run unattended as a GECS job, or by using the Client Batches “Remove Instance” or “Remove All” buttons
from the “Scheduled Jobs” screen. Completed Jobs will be left on file.
To remove a single instance of a batch, from the client Administrator program, Batches screen, click on the
“Scheduled Jobs” toolbar button. From the Remove Scheduled Jobs program and from the scheduled jobs screen in
the Batches program you can click on the “Remove Instance” button to remove a single highlighted job.
To remove all jobs previously scheduled from a batch, from Batches, click on the “Scheduled Jobs” toolbar button.
From the Remove Scheduled Jobs program and from the scheduled jobs screen in Batches, you can click on the
“Remove All” button to remove all jobs for the highlighted batch.
The Remove Scheduled Jobs program (GECSBREM.EXE) may be passed command line parameters to control the
operation of the removal process. The first parameter passed may be the name of the Batch to remove. It will then
remove the most recent scheduled batch of the batch name specified. Should the removal fail, a message box is
displayed indicating the error that occurred and an exit value of 1 is returned to the calling program. Error messages
may be silenced using the -Q (Quiet) command line switch.
GECSBREM.EXE batchname -Q
GECSBSCH - Schedule Batch jobs program
The Schedule Batch Jobs program can be started with the name of the desired Batch passed on the command line.
The program will immediately schedule the designated batch. It will stop and prompt for Batch Variables, if any are
defined for the Batch. The -Q command line option can be added after the batch name to indicate that the program
should run in “Quiet” mode, not stopping for program errors. This will allow the scheduling of a Batch to be
automated (run unattended) as a GECS job.
GECSBSCH.EXE batchname -Q
Note that this program will still prompt for Batch variable input if they have been defined for the Batch when run
with the -Q option.
When scheduling a batch via Batches Administrator client program, the currently selected Batch is scheduled.
Scheduling a batch using the Schedule Batch Jobs program first presents a list of all the available batches, allowing
you to choose which batch to schedule. Double clicking on a batch or highlighting and clicking the “Next” button
initiates submission.
The ability to run GECSBSCH.EXE has enormous potential for automating the scheduling of individual batches.
These executable programs can be run as a standard GECS job. By running GECSBSCH.EXE as a job, it is possible
to daisy chain batches. Consider creating a batch which has as its last step, an item which will run GECSBSCH.EXE
passing the name of the next batch to run. In this way, you can create dependent batches.
13-6
GECS Utility Programs
The batch scheduling process performs the following:
1. Creates new job records and adds them to the jobs queue. Unique job numbers are assigned and are associated
exclusively to the batch. This makes it possible to remove scheduled jobs for this batch schedule only.
2. Generates Events for each Batch Scheduled.
GECSCALE - Add Calendars Utility
The add calendars utility, GECSCALE, allows you to automate the process of adding a large number of defined
months or non-business days. This program reads a comma separated file that contains a list of dates and optionally
their description. The dates in the file are added to either the GECS defined months or non-business days file based
on the type entered on the command line. Additionally, the name of the calendar that the entries should be added to
is entered on the command line. The program is run by entering:
GECSCALE [/NOSTOP] type calendar filename
where ‘type’ is either NONBUSI or DEFMONTH and ‘calendar’ is the name of the calendar the entries should be
added to. If the specified ‘calendar’ does not already exist, it is created. Any existing entries in the specified
calendar remain and the new entries are added to them. The comma separated file is in the format:
“mm/dd/yyyy”
“mm/dd/yyyy”
“mm/dd/yyyy”
or
“mm/dd/yyyy”, “description”
“mm/dd/yyyy”, “description”
“mm/dd/yyyy”, “description”
For example, if you had created the following comma separated file named MONTHS.CSV:
“01/01/1996", ”Month1"
“02/02/1996", ”Month2"
“03/03/1996", ”Month3"
you could have this utility automatically add these defined months to the MYMONTHS calendar by entering:
GECSCALE DEFMONTH MYMONTHS F:\MONTHS.CSV
The /NOSTOP option causes the program to exit immediately upon completion.
GECSCAN - Can Do Program
The can do program, GECSCAN, produces a list of the jobs that a particular Agent can execute. It is run by entering:
GECSCAN [/NOSTOP] Agent [/O:output file]
where Agent is the name of the Agent you want to test. For example:
GECSCAN AGENTNT
would produce a list of all the jobs that AGENTNT can execute. The /NOSTOP option causes the program to
immediately exit on completion. The /O:output option causes the program to send its output to the specified file,
rather than to the screen.
13-7
GECS Utility Programs
GECSCANT - Can’t Do Program
The can’t do program, GECSCANT, is just the opposite of GECSCAN. It produces a list of the jobs that a particular
Agent cannot execute and it explains why. It is run by entering:
GECSCANT [/NOSTOP] Agent [/O:output file]
where Agent is the name of the Agent you want to test. For example:
GECSCANT AGENTNT
would produce a list of all the jobs the AGENTNT cannot execute. The /NOSTOP option causes the program to
immediately exit on completion. The /O:output option causes the program to send its output to the specified file,
rather than to the screen.
GECSCERT - Certificate Management Program
To set up certificate management for your Global ECS system, you must run the GECSCERT program on every
computer that will be running GECS components. You must establish a unique password for your system. This
password must be entered when this program is run. Any computer without the proper certificate will be locked out
of the system. Information about this computer is encrypted with the password to prevent this certificate from being
used on other computers. The password is the key to generating the certificate code. We recommend the password
exceed 16 characters but no more than 255 characters. Normal rules of command line arguments apply. (i.e. If you
are using spaces in your password it should be enclosed in quotes). For example:
GECSCERT /NEW abc1234567890wxyz abc1234567890wxyz
Where ‘abc1234567890wxyz’ is your password. It is entered twice for verification.
To disable certificate management you can run the GECSCERT program with the delete option. For example:
GECSCERT /DEL abc1234567890wxyz
For Windows, you must be logged in as Administrator and you must have the appropriate password to disable this
scheme.
For Unix, you should be logged in as root. A file will be created on the machine in the /GECS subdirectory.
GECSCHNG - Trigger File Change Utility
The GECSCHNG utility allows dependencies on files “changing”. This program accepts a file name as an
argument. When GECSCHNG.EXE first starts, it records (in memory) the time/date stamp of the file that was
passed on the command line. It then periodically checks the time stamp of the file. When the time stamp does not
match the one in memory, that means the file has been edited/changed. At that point GECSCHNG.EXE returns a
zero to the OS and terminates. If the file passed on the command line cannot be found, GECSCHNG.EXE returns a
non-zero value and terminates. The syntax for use is:
GECSCHNG filespec
where filespec is the fully qualified path of the file to be watched. For example:
C:\GECS\GECSCHNG C:\TESTFIL.TXT
would be the “Command Line” of the Trigger Job. This job needs to be started BEFORE the file changes and will
run until the file changes. The real Job will be the second job that has a “Job Dependency” on the first (Trigger) job.
13-8
GECS Utility Programs
GECSCLEA - Cleanup Utility
The cleanup utility, GECSCLEA, is provided to help automatically reset your system after an abnormal system
failure. The format for executing the clean program is:
GECSCLEA.EXE [/NOSTOP] [wrksubdir][/DEL beg end]
[/PURGE beg end][/ROLL beg end][/RESET][/RECONLY][/NOWRK]
Optional parameters as follows:
/NOSTOP
- causes program to immediately exit upon completion
wrksubdir
- subdirectory to delete wrk files from
/DEL beg end
- delete pending non-recurring jobs from beg through end
/PURGE beg end
- delete completed jobs from beg to end
/ROLL beg end
- roll forward pending recurring jobs from beg through end
/RESET
- mark all jobs currently set as “on hold” to “pending”
/RECONLY
- only “recurring” jobs should be rolled forward. Don’t mark on time jobs
complete
/NOWRK
- don’t delete any wrk files
In case of power failure or other system failure, GECS can handle resetting jobs that were running at the time of the
system failure by using the GECSCLEA utility. Jobs that were running when the system failed are left “Started”.
The cleanup utility is designed to be run before your Controller restarts after such an outage. It can mark jobs as
pending so they will run again as soon as your Controller is restarted, just as if the job had never been started prior to
the system failure. This prevents jobs that are not set for retry from being skipped due to system failure. This
program resets the “Job Status” flag for any jobs with a started status and sets it back to “Pending”. This will cause
your Controller to dispatch the job again, once it is started.
This program cannot be run when any other GECS programs (Controller or clients) are being run. It will error if it
can’t open the data files exclusively. The program returns 0 if it is successful, 1 if it failed because the files were in
use and 2 if it encountered some other sort of error.
This program is designed to be put in the AUTOEXEC.BAT or STARTUP.CMD file of the machine being run as
the by entering something like:
F:
CD \GECS
GECSCLEA
IF ERRORLEVEL 2 GOTO ERROR
GECSPROC CONTROL
GOTO DONE
:ERROR
PAUSE
:DONE
You might want to test for an error level of 1 as well. If the program returns an error of 1, another might be running
the GECSCLEA utility. You might want to wait several minutes before trying to start the Controller. The
Controller won’t start if another node is running the cleanup utility. The WAITKEY.EXE program can be used for
the wait by entering something like:
13-9
GECS Utility Programs
F:
CD \GECS
GECSCLEA
IF ERRORLEVEL 2 GOTO ERROR
IF ERRORLEVEL 1 GOTO WAIT
:START
GECSPROC CONTROL
GOTO DONE
:WAIT
WAITKEY 120 Waiting For Cleanup To Finish.
GOTO START
:ERROR
PAUSE
:DONE
This program can also optionally delete job records or roll jobs forward into the future by using command line
options.
You might want to delete some or all of your one time only jobs before the system restarts. The program will delete
all non-recurring jobs in a particular job number range by entering:
GECSCLEA /DEL begnum endnum
For example:
GECSCLEA /DEL 100 999
would delete all non-recurring jobs in the job number range of 100 through 999. You can enter 0 to indicate first
and/or last. For example
GECSCLEA /DEL 0 0
would delete all non-recurring jobs.
You might want to roll forward some or all of your recurring jobs before they start. The program can roll forward
recurring jobs until they are scheduled at sometime in the future by entering:
GECSCLEA /ROLL begnum endnum
For example:
GECSCLEA /NOSTOP /ROLL 1000 1999
would advance the next scheduled date and time on all recurring jobs in the job number range of 1000 through 1999.
You can enter a 0 to indicate first and/or last. For example:
GECSCLEA /ROLL 1000 0
would roll forward all recurring jobs numbered greater than or equal to 1000.
The ‘wrksubdir’ option can be added as the first command line option to tell the cleanup program to delete any WRK
files from the specified subdirectory. For example:
GECSCLEA F:\GECS
would cause the cleanup program to delete any WRK files that might exist in F:\GECS or SYS:\GECS.
The GECSCLEA utility can optionally reset jobs that are marked as ‘started’ to ‘pending’ by using the /RESET
command line option. For example:
GECSCLEA /RESET
The GECSCLEA utility can optionally purge completed jobs in a particular job number range by using the /PURGE
command line option.
GECSCLEA /PURGE begnum endnum
For example:
13-10
GECS Utility Programs
GECSCLEA /PURGE 1000 2000
would delete all completed jobs that had job numbers in the range of 1000 through 2000
These options can be combined on a single command line by entering:
GECSCLEA F:\ /DEL 20 0 /ROLL 0 19 /RESET
Jobs are rolled forward as if they started when scheduled and took no time to run. This means that the jobs that repeat
based on the Last Start Time or Last Finished Time will effectively be rescheduled based on the Last Scheduled
Time as they are rolled forward. Most jobs will roll forward rather quickly. Jobs that are scheduled very frequently
(every couple seconds) can take some time to roll forward if the Controller has been down for quite a while (several
weeks or months).
This program can automate and simplify your recovery after a system outage, but you need to remember that it
is a powerful program and should be used carefully.
GECSCNUM - Change Job Number Utility
The change job number utility, GECSCNUM, can be used to allow you to change the job number of an existing job.
The program is run by entering:
GECSCNUM [/NOSTOP] oldnum newnum
The /NOSTOP option causes the program to immediately exit on completion. The oldnum should be populated
with the old job number to change from and the newnum should be populated with the new job number to change to.
For example:
GECSCNUM 155 BKUPJOB
This would change job number 155 into a job named BKUPJOB. Likewise:
GECSCNUM BATCH5.JOBA-105 TESTBATCH.A-1
would change job number BATCH5.JOBA-105 into a job named TESTBATCH.A-1.
GECSCONV - Convert Utility
The Convert utility, GECSCONV, converts ECS version 5.1 or GECS version 1.5 data to GECS version 3.1 data.
The SERVERS, RESOURCE and LOGS files are not converted. It is run by entering:
GECSCONV
This program should only be run once. It installs with the Controller programs but in the convert subdirectory.
GECSDEL - Job Delete Utility
The job delete utility, GECSDEL, is a command line utility that can be used to delete a job or a range of jobs either
from a prompt or from inside a batch file. This program is run by entering:
GECSDEL [/NOSTOP] [/ONLYCOMP] jobnum [endjob]
where jobnum is the number of the job to be deleted. For example:
GECSDEL BATCH1.JOBA-1 BATCH1.JOBZ-1
13-11
GECS Utility Programs
would delete job BATCH1.JOBA-1 thru BATCH1.JOBZ-1 from the JOBS file. The /NOSTOP option causes
the program to exit immediately upon completion. The /ONLYCOMP option causes the program to only delete
completed jobs. Without this option the specified job is deleted regardless of status. Jobnum is the job number
to delete. [endjob] is optional ending job number to delete through. This program checks rights of the user attempting to delete the job. The user must be assigned to a Security Profile that is allowed to edit ALL jobs, not
just their own.
GECSCUSE - Change User Utility
The change user utility, GECSCUSE, allows you to change the ‘Submitted By’ user name assigned to all or
individual user’s job(s). The program is run by entering:
GECSCUSE [/NOSTOP][/JOB=n.n-n] olduser newuser
The /NOSTOP option causes the program to immediately exit on completion. The /JOB= option allows you to
specify individual job numbers. The olduser should be populated with the old GECS user name to change from and
the newuser should be populated with the new GECS user name to change to. For example:
GECSCUSE FRED MARILYN
This would update the “Submitted By” field of every job with a submitted by name of Fred to Marilyn. Or to
change only the “Submitted By” name on job BATCH1.JOB1-1, see the following:
GECSCUSE /JOB=BATCH1.JOB1-1 FRED MARILYN
GECSDUMP - Job Export Utility
The Job export/dump utility, GECSDUMP, creates either a fixed length or comma separated value data file from the
information in the JOBS file. This utility is great for transferring test jobs to production. You can dump fully tested
jobs from your test environment into a .WRK file then let your production Controller pick up the .WRK file and
convert it into GECS production jobs. To run the program, enter :
GECSDUMP [/NOSTOP] filename type [job[job]]
where filename is the name of the output file to be created and type is the either CSV (Comma Separated Value),
CSV2 (Comma Separated Value which includs valid times), FIXED (Fixed Length), WRK (does not dump job
names) or WRKX (dumps job names and saves them in the file ) to indicate the type of file to be created. A single
job number or range of job numbers can be specified. When a range of job numbers is specified, a space should be
entered between the beginning number and the ending number. For example:
GECSDUMP C:\TEST.DAT WRKX BATCH1.JOB1-1 BATCH1.JOB50-1
The /NOSTOP option causes the program to exit immediately upon completion. The file that is created contains the
fields in the JOBS file. The CSV, CSV2 and FIXED format files contain most of the fields in the job record. The
WRK and WRKX files contain all the fields in the job record. Should the specified ‘filename’ exist, it is deleted
before the new one is created without warning.
All the information in the jobs file is exported except the login as a specified user password. The password is
not exported. See the “Job Dump Data Files” section in the File Glossary chapter of this manual for a detailed
layout of the file formats. See the “Task Automation” chapter of this manual for job parameter WRK file
equivalent values.
When GECSDUMP is used to create a WRK file from a single job that has job dependencies, you may need to
manually update the WRK file using special dependency WRK file parameters. For instance, you may need to
create a WRK file for each job in the dependent job stream, combine the WRK files into one WRK file, then
edit the WRK file using Xn: or 2n: parameters to specify the job dependencies.
13-12
GECS Utility Programs
GECSEDEL - Event Delete Utility
The Event delete utility, GECSEDEL, allows you to delete GECS Event records. The program is run by entering:
GECSEDEL [/NOSTOP][ONLYCLOSED] begdate [enddate]
The /NOSTOP option causes the program to immediately exit on completion. The /ONLYCLOSED option allows
you to delete only closed Events. The begdate should be populated with the date to start deleting and the optional
enddate when to stop deleting. For example:
GECSEDEL /ONLYCLOSED 07/01/2003 09/01/2003
This would delete GECS Event that have a Closed status that occurred between July, 1st 2003 and August, 1st
2003.
GECSEVNT - Add Events Utility
The GECSEVNT utility allows you to define and add your own Events to the GECS system. Usage as follows:
GECSEVNT num= type= serv= name= ret= j1= u1= u2= u3= u4= u5= j2=
Jobs can depend on the occurrence of these Events you create.
num=
%NUMBER% of Event (number must be greater than 1000) (required)
type=
%TYPE% of Event (0=DBMS,1=Controller,2=Agent,3=WebManager,4=Admin,5=Other) (required)
“Generated By” field
serv=
%SERVER% of Event - “Component” field (1-8 characters) (optional)
name= %NAME% of Event (1-255 characters) (optional)
ret=
%RETCODE% of Event (number) (optional)
j1=
%JOBNUM% of Event (bat.job-inst) (optional)
u1=
%USER1% of Event (1-48 characters) (optional)
u2=
%USER2% of Event (1-48 characters) (optional)
u3=
%USER3% of Event (1-48 characters) (optional)
u4=
%USER4% of Event (1-48 characters) (optional)
u5=
%USER5% of Event (1-48 characters) (optional)
j2=
%JOBNUM2% of Event (bat.job-inst) (optional)
For instance you may need to create an Event that will trigger one of your jobs to run. For example:
GECSEVNT num=1005 type=5 serv=CMDLINE j1=BATCH1.JOB5-6
GECSHIDE
The GECSHIDE utility will hide a running Agent or your Controller. It is run as:
Unix or Linux
GECSHIDE name ip_name [port]
Windows
C:\GECS\GECSHIDE.EXE name ip_name [port]
NLM
LOAD SYS:\GECS\GECSHIDE.NLM name ip_name port]
13-13
GECS Utility Programs
The ‘name’ and ‘ip_name’ command line options are required. The ‘port’ option is optional. For example:
GECSHIDE Agent1 joe.fred.com
or
LOAD SYS:\GECS\GECSHIDE.NLM nlmAgent 234.234.234.234 12345
A message will be displayed to indicate whether the command was run. Note that the ‘name’ and ‘port’ options
must match the name and port specified when the Agent was started.
This program is included with the Agents, Controller and Windows clients.
GECSLAUN
The GECSLAUN utility is used internally by the Unix Agents when they run jobs as the submitting user. This
program should not be run by hand. There is no Windows version.
GECSLDEL - Completed Job Delete Utility
The completed job delete utility, GECSLDEL, is a command line utility that can be used to delete completed jobs
either from a prompt or from inside a batch file. This program is run by entering:
GECSLDEL [/NOSTOP] jobnum[jobnum]
where jobnum is the number of the job or the range of jobs to be deleted. When a range is specified, you should enter
a space between the beginning number and the ending number. For example:
GECSLDEL 12345 12499
GECSLDEL BATCH1.JOBA-5 BATCH1.JOBZ-5
would delete completed job records for jobs 12345 through 12499. The /NOSTOP option causes the program to exit
immediately upon completion.
GECSLDUM - Completed Job Statistics Export Utility
The completed job statistics export/dump utility, GECSLDUM creates either a fixed length or comma separated
value data file from the information statistics from a completed job.
To run the program, enter :
GECSLDUM [/NOSTOP] filename filetype
where filename is the name of the output file to be created and filetype is the either CSV (Comma Separated Value)
or FIXED (Fixed Length) to indicate the type of file to be created. For example:
GECSLDUM TEST.DAT FIXED
The /NOSTOP option causes the program to exit immediately upon completion. The file that is created contains
completed job statistics information.
Should the specified ‘filename’ exist, it is deleted before the new one is created without warning.
13-14
GECS Utility Programs
GECSOVER - Job Override Utility
The job dependency override utility, GECSOVER, allows you to flag a job such that it should run even though its
predecessor jobs haven’t run (override the job dependency). It is run by entering:
GECSOVER [/NOSTOP] jobnum
where ‘jobnum’ is the number of the job to be overridden. For example:
GECSOVER BATCH1.1234-1
would flag job BATCH1.1234-1 such that it would run without its predecessor jobs running first. The
/NOSTOP option causes the program to exit immediately upon completion.
GECSPASS - Password Change Program
The password change program, GECSPASS, lets you change the encrypted network passwords in the GECS data
files without having to run the GECS client programs. This program is useful if you require frequent user password
changes and you don’t want users to be allowed to edit users from the GECS Clients. This program is run by
entering:
GECSPASS [/NOSTOP] username password
where username is the user record to be changed in the GECS user file and password is the new password to be
assigned to the user. For example:
GECSPASS JOE LAWNMOWER
would change the network login password of the GECS user named JOE to LAWNMOWER. The /NOSTOP
option would cause the program to exit immediately on completion.
If the user running this program (based on their network login name) is allowed to edit users in the client programs,
they can use this program to change anyone’s password. If they are not allowed to edit users in the client programs,
they can only change their own password.
GECSPAUS
The GECSPAUS utility allows you to pause and unpause your Controller from any computer that has this program
installed. It is run as:
Unix or Linux
GECSPAUS on|off name ip_name [port]
Windows
C:\GECS\GECSPAUS.EXE on|off name ip_name [port]
NLM
LOAD SYS:\GECS\GECSPAUS.NLM on|off name ip_name port]
‘On’ =pause Controller, ‘off’ =unpause Controller, ‘name’ and ‘ip_name’ are the Controller’s GECS name and
Controller’s ip address. These command line options are required . The ‘port’ option is optional. The port defaults
to 2001. For example:
GECSPAUS control on joe.fred.com
or
LOAD SYS:\GECS\GECSPAUS.NLM on control 234.234.234.234 2001
13-15
GECS Utility Programs
A message will be displayed to indicate whether the command was run. Note that the ‘name’ and ‘port’ options
must match the name and port specified when the Controller was started.
This program is included with the Agents, Controller and Windows clients.
GECSPING - Ping GECS Component
To test communications between your Controller, Clients or your running Agents you can use the GECSPING
utility. This utility is very similar to PING. From the computer running your Controller, Agent or GECS Windows
Client programs you can launch the GECSPING utility to check for a response from a specified GECS component.
This utility is very helpful for trouble shooting.
If you used default directories during installation, GECSPING is in the C:\GECS subdirectory. Enter the following
command line:
C:\GECS\GECSPING.EXE name ip_name [port]
The ‘name’ and ‘ip_name’ command line options are required. The ‘name’ is the GECS name of the component being tested, such as NTAGENT or CONTROL. ‘Port’ is optional. ‘Port’ is the port number on the GECS
component computer. It is a number in the range of 1 to 65536. For example:
C:\GECS\GECSPING Agent1 zeus.company.com
or
C:\GECS\GECSPING control 200.200.200.100 2001
A message will be displayed to indicate whether the specified component can be contacted. Note that the
‘name’ and ‘port’ options must match the name and port specified when the component was started.
Make sure you can successfully ping the component before you continue with the next step. If the GECSPING
fails, try a different port number, verify your IP address or name, and verify that you are using the component
name you used when you started the component.
You can go to the computer where the component is running and enter ‘Address’. This will display the name
and address the component is running as.
GECSPURG - Job Purge Utility
The job purge utility, GECSPURG, deletes old job records. It is run by entering:
GECSPURG [/NOSTOP][/COMPONLY] mm/dd/yyyy
Where all jobs created prior to the ‘mm/dd/yyyy’ date are deleted. For example:
GECSPURG 12/19/1998
would delete all jobs created prior to December 19th 1998. The /NOSTOP option causes the program to exit
immediately upon completion. The /COMPONLY option will only delete jobs with a completed status.
GECSQUEU - Queue Program
The job queue program, GECSQUEU, lists the contents of the job queue. It can list all jobs, all jobs assigned to an
Agent group, all jobs assigned to an Agent and all jobs submitted by a user. The program is run by entering:
13-16
GECS Utility Programs
GECSQUEU [/NOSTOP][/G:group][/S:Agent][/N:user][/A][/O:output]
The optional /G, /S and /N options let you limit the list to jobs that match the specified criteria. For example:
GECSQUEU /G:GROUP1
would produce a list of the jobs assigned to an Agent GROUP1. The /NOSTOP option causes the program to
immediately exit on completion. The /A option causes the program to include all jobs in the list, even if their
time has not come due. The /O:output option causes the program to send its output to the specified file, rather
than to the screen. Jobs that have trigger file dependencies that are not met, do not display in this list.
GECSQUIC - Quick Job Adding Program
The quick job adding program, GECSQUIC, is used for quickly adding pending WRK files from a command line.
To start this program enter:
GECSQUIC subdir C:command
where subdir is the subdirectory where the pending work file should be created and command is the command that
should be executed. For example:
GECSQUIC F:\GECS C:COPY F:\X F:\Y
would create a WRK file in the F:\GECS or SYS:\GECS subdirectory. These programs can also be used to
“reactivate” a completed job. To do this enter:
GECSQUIC subdir J:jobnum
where subdir is the subdirectory where the pending work file should be created and jobnum is the job number of the
existing job that should be reactivated. For example:
GECSQUIC F:\GECS J:101
would create a work file in the F:\GECS or SYS:\GECS subdirectory that would tell GECS to reactivate job 101.
These programs normally stop at the end and display a message indicating they were successful. To avoid this stop
at the end, include the /NOSTOP command line option such as in:
GECSQUIC /NOSTOP \GECS C:\test.exe
GECSRBLD - Rebuild Utility
As with any file system, under certain unusual circumstances (i.e. power or hardware failure) it is possible that the
GECS data files could become corrupted and GECS will give an error (i.e. I/O error) when it attempts to access
them. To help deal with these rare situations, the GECSRBLD, rebuild utility is provided.
WARNING: No GECS programs should be running when this programs is run.
The Rebuild utility allows you to rebuild a damaged files. It is run by entering:
GECSRBLD filename
GECSRBLD all
where ‘filename’ is the name of the GECS data file to be rebuilt or ‘all’ will rebuild all of the data files.
After the rebuild utility is complete, temporary files will be deleted. In most situations, all the data will be recovered
from the corrupted file, but in some circumstances, some of the data will be lost. After rebuilding a file, use the
Client programs to validate the rebuilt data.
13-17
GECS Utility Programs
GECSRET - Job Return Code Program
The job return code program, GECSRET, can be used to test your job streams with various job return codes. Your
“command line” should be as follows:
c:\gecs\gecsret retval
where retval is the return code you’d like the program to return. This program simply returns the specified value as
its return code. For example, create a GECS job named “TEST” and specify the following job parameters:
Command Line: c:\gecs\gecsret 8
Command Line Type: choose the appropriate operating system
Where c:\gecs is your Agent directory and 8 is the value you would like the program to return.
When you have finished, save your job and exit. After your job has run, ensure your job returned 8 by viewing your
completed job statistics.
The GECSRET program is installed with the Agents and Controller.
GECSSHOW - Display Agent or Controller
The GECSSHOW utility will unhide a hidden or display a minimized Agent or your Controller. It is run as:
Unix or Linux
GECSSHOW name ip_name [port]
Windows
C:\GECS\GECSSHOW.EXE name ip_name [port]
NLM
LOAD SYS:\GECS\GECSSHOW.NLM name ip_name port]
The ‘name’ and ‘ip_name’ command line options are required. The ‘port’ option is optional. For example:
GECSSHOW Agent1 joe.fred.com
or
LOAD SYS:\GECS\GECSSHOW.NLM nlmAgent 234.234.234.234 12345
A message will be displayed to indicate whether the command was run. Note that the ‘name’ and ‘port’ options
must match the name and port specified when the Agent or your Controller was started.
This program is included with the Agents, Controller and Windows clients.
GECSSIZE - Trigger File Size Change Utility
The Trigger File Size Change utility, GECSSIZE, can be run to monitor a file until the file size changes. The
“GECSSIZE” utility allows dependencies on file size “changing”. This program accepts a file name as an
argument. When GECSSIZE.EXE first starts, it records (in memory) the size of the file that was passed on the
command line. It then periodically checks the size of the file. When the size does not match the one in memory, that
means the file has been changed. At that point GECSSIZE.EXE returns a zero to the OS and terminates. If the file
passed on the command line cannot be found, GECSSIZE.EXE returns a non-zero value and terminates. The syntax
for use is:
GECSSIZE filename
Where ‘filename’ is the file to wait for a size change. For example:
GECSSIZE C:\TEST1\TESTFILE.TXT
13-18
GECS Utility Programs
GECSSTOP - Stop Agent or Controller
GECSSTOP will cause the specified GECS Agent or your Controller to stop and unload itself. To stop a running
Agent, run the following commands:
Unix or Linux
GECSSTOP name ip_name [port]
Windows
C:\GECS\GECSSTOP.EXE name ip_name [port]
NLM
LOAD SYS:\GECS\GECSSTOP.NLM name ip_name [port]
The ‘name’ and ‘ip_name’ command line options are required. The ‘port’ option is optional. For example:
GECSSTOP Agent1 abraham.mycompany.com 4000
or
C:\GECS\GECSSTOP.EXE ntAgent 123.124.125.126
A message will be displayed to indicate whether the specified Agent was stopped. Note that the ‘name’ and ‘port’
options must match the name and port specified when the Agent was started.
This program is include with the Agents, Controller and Windows clients.
GECSSTP - Stop Job Utility
The stop job utility (GECSSTP) allows you to tell GECS to terminate a running job from a command line utility. It is
run by entering:
GECSSTP [/NOSTOP] jobnum
where ‘jobnum’ is the number of the currently running job to be stopped. For example:
GECSSTP 1234
would tell the Agent that is currently running job 1234 to terminate it. The /NOSTOP option causes the program to
exit immediately upon completion.
GECSTRIG - Job Trigger Utility
The job trigger utility , GECSTRIG, flags a job as pending and sets the next scheduled date and time to the current
time to trigger a completed job to run. It is run by entering:
GECSTRIG [/NOSTOP] jobnum
where ‘jobnum’ is the number of the job to be triggered. For example:
GECSTRIG 1234
would flag job 1234 such that it would run immediately. The /NOSTOP option causes the program to exit
immediately upon completion.
13-19
GECS Utility Programs
GECSVAL - Validate Utility
The Validate program, GECSVAL, analyzes the data files without attempting to correct problems. All other GECS
programs must be stopped before running this program. It validates all the GECS data files. It is run by entering:
GECSVAL filename
GECSVAL all
Where ‘filename’ is the name of the GECS data file to be validated or ‘all’ will validate all of the data files.
It will stop if it encounters any problems in the files. If the Validate program encounters problems, you should run
the GECSRBLD utility.
PULSENOW
The PULSENOW utility allows you to automatically pulse your Controller from any machine that has this program
installed. It is run as:
Unix or Linux
PULSENOW name ip_name [port]
Windows
C:\GECS\PULSENOW.EXE name ip_name [port]
NLM
LOAD SYS:\GECS\PULSENOW.NLM name ip_name port]
The ‘name’ and ‘ip_name’ command line options are required. The ‘port’ option is optional. The port defaults to
2001. For example:
PULSENOW control joe.fred.com
or
LOAD SYS:\GECS\PULSENOW.NLM control 234.234.234.234 2001
A message will be displayed to indicate whether the command was run. Note that the ‘name’ and ‘port’ options
must match the name and port specified when the Controller was started.
This program is included with the Agents, Controller and Windows Client programs.
13-20
GECS Custom Installation
GECS Custom Installation
14-1
GECS Custom Installation
14-2
GECS Custom Installation
GECS Configurations
The Basic Architecture
GECS version 3 standard architecture when installed using the Express Installation is as follows:
The Express installation option installs all of the GECS components onto one computer. The Controller, DBMS
and Web Manager programs run as services. The Agent, window’s clients and browser are started from icons
on the desktop.
To change this standard configuration, you can select custom installation from the Workstation Setup program.
See the Configuration Worksheet chapter of this manual to help organize the computers that make up your
Global ECS System.
You might want the Agent to run as a service or you might want the Controller and DBMS to run from icons on
the desktop. To make changes like this to a system that was configured using Express installation:
1. Shutdown your Administrator client program or any other users might be running.
2. Start the GECS Workstation Setup (C40SETUP.EXE).
3. Make the desired changes. Each page describes a portion of the system. For example, to make the
Web Manager program run from an icon on the desktop, rather than as a service, go to the Web
Manager page by pressing the ‘next’ button. Change the ‘Run’ selection to ‘from a Desktop Icon’ and
continue to press ‘next’ and ‘configure’ buttons until the program completes. Be careful not to
accidentally change any other fields.
4. Once the configuration is complete, the Web Manager will no longer run as a service and you will find
an icon in the Global ECS folder to start it manually by double clicking the Web Manager program
shortcut icon.
Improper use of Workstation Setup can prevent your system from working.
The following configurations are described next:
1. Adding Agent computers
2. Adding Windows Client programs on other computers
3. Managing the GECS system from a browser
4. Installing the system across multiple computers
14-3
GECS Custom Installation
Adding Agent Computers
To add additional GECS Agents to your system, you need to first add new Agent information to the GECS system
using either the Windows Administrator Client program or from the browser client using the ‘Agents’ option. Then
you need to go to the Agent computer and install and start the Agent software.
Note that the IP address you enter for the Agent record is critical so GECS can communicate with the Agents. See
the section in the Getting Started chapter on installing Agents for more information.
Once you have added additional Agents to your system it will look something like this:
There are any number of reasons to add Agents to your system including:
1. Support for additional operating systems
2. Increase system throughput
3. Increase system reliability
14-4
GECS Custom Installation
Adding Windows Client Programs on Users Computers
Windows Client programs can be installed on users computers. Your GECS system will then look something like:
Once the Windows Client programs are installed on users computers, they can be used to configure and manage the
GECS system.
See the section in the Getting Started chapter for more information on installing just the Windows clients on users
computers.
14-5
GECS Custom Installation
Managing the GECS System from a Browser
When the GECS System is configured so it can be managed from computers using a browser, it is configured
like this:
No software installation or special configuration is required at the computers where the browser is run. To access
the Web manager simply enter the URL:
http://ipaddress:port
For example, if the ‘Primary Computer’ is at IP address 123.123.123.123, the GECS Web Manager was started on
port 2013 (the default), you would enter the URL:
http://123.123.123.123:2013
When the Browser first connects to the Web manager, you will need to enter the name and password of a valid
GECS user. Note that the GECS Web manager uses simple HTML and should be compatible with most browsers
with no special configuration.
Note that you can also check whether the Agents, Controller or DBMS are running by querying them with your
browser. They begin to listen for HTTP packets when they start and will respond to browser queries. Use the same
URL format to query these components:
http://ipaddress:port/gecsname
For example, if the IP address is 123.123.123.123, the Agent was started with HTTP port of 2010 (the default) and
the Agent was started with name of ‘pete’ (specified in the Workstation Setup program during configuration), you
would enter the URL:
http://123.123.123.123:2010/pete
You will be prompted for a username and password. By default the username to enter is simply the Agent name
‘pete’ without a password. You can specify a different username and password by using the –s and –t command line
options when the Agent is started. See the Agents chapter of this manual for details on starting your Agents.
14-6
GECS Custom Installation
Querying the Controller or DBMS works the same other than different ports and names are specified.
Default HTTP Ports:
Agent
2010
Controller
2011
DBMS
2012
Web Manager
2013
14-7
GECS Custom Installation
Installing the GECS System Across Multiple Computers
The examples shown so far show the bulk of the GECS system installed in a single computer. For a variety of
reasons, you might want to spread the system across more than one computer. When each part of the system is
installed in a separate computer it looks like this:
To install a distributed system like this, you would:
1. Draw a diagram like the one above of the system you wish to install. Put the IP addresses, ports and
GECS names for each of the computers on the diagram. Go to the computer that will run the DBMS
and install it. When installing the DBMS, you will need to know your license information.
In
the Workstation Setup program, enter the information about the computers where the other parts of
the system will be running.
2. Shutdown any Client programs such as the Administrator that you or any other users might be
running.
3. Go to the computer that will run the Windows Clients and install them. In the Workstation Setup
program, enter the information about the computers where the other parts of the system will be
running.
4. Go to the computer that will run the Agents and install them. In workstation setup, enter the
information about the computers where the other parts of the system will be running.
After installing the Agents, go to the computer where the Windows Clients are installed and enter the
new Agents records.
5. Go to the computers that will run the Controller and install it. In workstation setup, enter the
information about the computers where the other parts of the system will be running.
6. Go to the computer that will run the Web Manager and install it. In workstation setup, enter the
information about the computers where the other parts of the system will be running.
14-8
GECS Custom Installation
Custom Installation Program
The Workstation Setup program can be run in Express or Custom modes. The two methods do the same thing, the
Express mode assumes a simple single machine configuration while the Custom mode allows you to change many
aspects of the system configuration.
In Custom mode, the Workstation setup program presents a series of screens. You press the next and previous
buttons to switch between screens. Each screen allows you to configure a particular component of your GECS
System. The screens are:
DBMS
Is the DBMS on this machine and if not where is it?
Controller
Is the Controller on this machine and if not where is it?
Web Manager
Is the Web Manager on this machine and if not where is it, if anywhere?
Agent
Is there an Agent on this machine?
Client Programs
Should icons be created for Windows clients on this machine?
Desktop
What folder should be used for desktop icons?
License
What is your company name and license number?
Configure
Go ahead and configure this machine as entered.
The information entered in the GECS Workstation Setup program is used to create the GECS.INI file in your
Windows (C:\WINNT) directory. The entries are saved in the registry so the next time Workstation Setup is run on
this computer, it will default to your previous entries.
A note about IP addresses.
The Workstation Setup program has a number of places where you will need to enter the IP address of the computer
where the particular component is running, These IP addresses can be entered either as numbers or as DNS names.
Numbers (i.e. 123.123.123.123) have the advantage of not needing to be translated before use. DNS names have the
advantage of being able to be assigned dynamically and the actual underlying number can change as long as the
name remains the same. You and your network administrator will need to determine whether to configure with
numbers or names.
A note about IP ports.
The four main server components of the system (Agent, Controller, DBMS and Web Manager) each use 2 IP ports.
One port is used for communication between GECS components. The use of a port for communications between
GECS components is required. The other port is used for HTTP communications between GECS components and
browsers. The use of a port for HTTP communications is optional and can be disabled by entering a port number of
zero (0). The Workstation Setup program will default to the following port numbers:
Component
GECS Port HTTP Port
Agent
2000
2010
Controller
2001
2011
DBMS
2002
2012
Web Manager
2003
2013
14-9
GECS Custom Installation
DBMS
Use this page to indicate whether you want the DBMS to run in this computer or whether you are going to have
it run in another computer. There MUST be a DBMS somewhere in your system.
If you want the DBMS to run on this computer, you must enter its IP address and ports. You must also indicate
whether it should run on the desktop, as a service on the system account or as a service on a user account. You
must also indicate where on the local hard drive the data should physically be stored.
If you are going to run the DBMS on another computer, you must enter the IP address and port where it will
run.
14-10
GECS Custom Installation
Controller
Use this page to indicate whether you want the Controller to run in this computer or whether you are going to
have it run in another computer. There MUST be a Controller somewhere in your system.
If you want the Controller to run on this computer, you must enter its IP address and ports. You must also
indicate whether it should run on the desktop, as a service on the system account or as a service on a user
account.
If you are going to run the Controller on another computer, you must enter the IP address and port where it will run.
14-11
GECS Custom Installation
Web Manager
Use this page to indicate whether you will run a Web Manager and whether you want the Web Manager to run
in this computer or on another computer.
If you want the Web Manager to run on this computer, you must enter its IP address and ports. You must also
indicate whether it should run on the desktop, as a service on the system account or as a service on a user
account.
If you are going to run the Web Manager on another computer, you must enter the IP address and port where it will
run.
14-12
GECS Custom Installation
Agent
Use this page to indicate whether you will run an Agent in this computer.
If you want to run an Agent on this computer, you must enter its name, IP address and ports. You must also indicate
whether it should run on the desktop, as a service on the system account or as a service on a user account.
14-13
GECS Custom Installation
Client Programs
Use this page to indicate whether you want icons created for the Windows Client programs on this computer. If
you want icons created for the Windows Client programs, indicate the type of network security to be used. The
three types can be summarized as:
No Network
This method prompts the users for their GECS name and password.
Microsoft
This method uses your Windows NT login name for GECS security.
Novell
This method uses your NetWare login name for GECS security.
14-14
GECS Custom Installation
Desktop
Use this page to indicate which folder the icons should be created in. This page will not be displayed if there are no
icons to create on this computer.
14-15
GECS Custom Installation
License
Use this page to enter your GECS license information. This page is only displayed if you are configuring this
computer to have a DBMS on it.
14-16
GECS Custom Installation
Configure
This page is simply a last warning that you are about to configure your system to match your entries. Once you press
‘Configure’ your configuration will be changed.
14-17
GECS Custom Installation
14-18
Technical Reference
Technical Reference
15-1
Technical Reference
15-2
Technical Reference
GECS.INI File
GECS uses a locally stored ASCII text configuration file named GECS.INI. It serves several important purposes:
1) It determines where all the GECS programs look to find the data files.
2) It contains run-time information for your GECS components such as screen size,
position and settings for your Client programs.
3) It determines how date substitution variables are formatted.
When you run the GECS WorkStation Setup program, this file is automatically generated and stored locally in your
WINNT directory. It can be edited with any standard text editor such as Edit or Notepad.
The file is laid out much like a Windows INI file. The file is setup in several sections, [AGENT],
[APPLICATIONS], [CONTROLLER], [CONTROLS], [DBMS], [ENVIRONMENT], [FILES], [FORMAT],
[FORMS], [OPTIONS], [STUDIO] and [WEBMANAGER]. All the GECS programs will look for this file in the
default subdirectory when they start. The programs can be passed the name of an alternative configuration file on
the command line by using the /C:filename command line option. For example:
C:\GECS\GECSADMIN.EXE -C:c:\winnt\MYGECS.INI
It is important to note that by improperly altering the [FILES] section, you can cause GECS to generate errors and
fail to operate. You may want to make a note of any special changes you manually make to your GECS.INI file.
Some entries are created automatically by the GECS WorkStation Setup program or by other programs as they are
opened.
[AGENT] Section
In certain circumstances it may be necessary to adjust certain parameters including keystuffing parameters. This
can be accomplished by creating a GECS.INI file in the WINNT directory of the machine where the Agent is
running. The file may look similar to this:
[AGENT]
CaptionRetries=12
KeyDelay=100
KeySwitch=1
SHELL=COMMAND.COM /e:1024
SHELL32=CMD.EXE
SyncFrequency=600
SyncServer=
SyncTimeout=60
SyncType=0
TV_SECTimeout=1
CaptionRetries, by default, tries 12 times to find the window with the specified caption text on the title bar.
KeyDelay sets the time, in milliseconds, to pause between each key sent to an application. The default value is set
to 100ms. If keystrokes are sporadically lost, increasing this value to a higher value, like 400ms, may remedy this
situation.
Setting the KeySwitch entry from 1 to 0 should keep the Agent from changing focus to the application window
with every keystroke.
Shell is used if you have a DOS command line type job and you need additional environmental space. You can use
the Agent section to change the environment allocated to these jobs. By default, jobs are launched using /e:1024.
Shell32 is used if you have Windows NT/2000/XP/2003 or NT Console command line type jobs that need
additional environmental space. You can use the Agent section to change the environment allocated to these jobs.
By default, jobs are launched using /e:1024.
15-3
Technical Reference
The SyncFrequency entry defines how often in seconds the Agent should time synchronize. This entry defaults
to 600 seconds.
The SyncServer entry is used to specify the server computer that the Agent should synchronize its time to. This
entry is blank by default.
The SyncTimeout entry tells how long, in seconds, it should try to synchronize its time. This entry defaults to 60
seconds.
The SyncType sets the type of time synchronization that should be used. 0=none, 1=Microsoft, 2=NetWare,
3=Time protocol (RFC-868) and 4=NTP/SNTP (RFC-1305/1361/1769/2030). This entry defaults to zero.
The TV_SECTimeout entry defines the amount of time, in seconds, the thread block should wait when selecting a
packet. This entry defaults to 1 second.
[APPLICATIONS] Section
The [Applications] section contains configuration information for GECS Windows Client programs. This section
is updated by GECS when Configuration Options or window positioning is changed. This section should not be
changed manually.
[CONTROLLER] Section
The [CONTROLLER] section can contain a variety of options. For example:
[CONTROLLER]
AgentTimeout=15
BackupPulse=15
DeleteOnlySuccessfulJobs=1
KillFrequency=30
MessageAsKill=0
PredecessorStyle=0
PrimaryController=
PulseFile=
ResetOnReconnect=0
SendAttempts=5
SMTPLogin=
SMTPFrom=
SyncFrequency=600
SyncTimeout=60
TV_SECTimeout=1
WrkFilesPerPulse=
The AgentTimeout entry defines how long, in seconds, the Controller should wait for a response from an Agent.
This entry defaults to 15 seconds.
The BackupPulse entry is reserved for a future version.
By default, the controller setting "Delete jobs on completion" deletes all completed jobs when they complete. By
using DeleteOnlySuccessfulJobs, the controller will only delete the 'successful' jobs (those with a return
code that's less than or equal to the 'max good return code' entered for the job) when they complete. The 'failed' jobs
will be left on file.
The KillFrequency entry is reserved for a future version.
The MessageAsKill entry allows the job parameter “Execute Message” to be executed when a job is killed by
GECS. (0=no, 1=yes). This entry defaults to zero.
The PredecessorStyle entry allows jobs be rescheduled using predecessor style dependencies. (0=no,
1=yes). This entry defaults to zero.
The PrimaryController entry is reserved for a future version.
15-4
Technical Reference
The PrimaryController entry defines the name and address of the primary Controller computer in the format
of (GECSName@IPAddr:Port). This entry is blank by default.
The PulseFile entry defines the name of the pulse file to use for your Controller. The pulse file can force your
Controller to immediately poll the GECS system. This entry is blank by default.
The ResetOnReconnect entry allows the Controller to tell its Agents to reset (kill all running jobs) when it
reconnects to them after communications have failed (0=no, 1=yes). This entry defaults to zero.
The SendAttempts entry defines how many times the Controller should try to send packets to Agents. This entry
defaults to 2 times.
The SyncFrequency entry defines how often, in seconds, the Controller should synchronize its time. This entry
defaults to 600 seconds.
The SyncTimeout entry defines how long, in seconds, the Controller should try to synchronize its time. This
entry defaults to 60 seconds.
The TV_SECTimeout entry defines the amount of time in seconds the thread block should wait when selecting a
packet. This entry defaults to 1 second.
The WrkFilesPerPulse entry defines how many WRK files GECS should convert into jobs during each pulse.
This number can range from 0 to 65,000. If GECS finds there are more WRK files to convert it will immediately
pulse again to read in more files.
[CONTROLS] Section
The [Controls] section contains configuration information for GECS Windows Client programs. This section is
updated by GECS when Configuration Options or window positioning is changed. This section should not be
changed manually.
[DBMS] Section
The [DBMS] section can contain a variety of options. For example:
[DBMS]
AgentTimeOut=15
ClientDelayPulse=600
DataPath=C:\GECS\DATA
DBMSTimeout=10
DelJobEvents=1
DoLocalDataAccess=1
HeartBeat=60
MaxClientDelay=600
PrimaryDBMS=
RecvTimeout=3
SecondaryDBMS=
SendAttempts=5
SyncFrequency=600
SyncServer=
SyncTimeout=60
SyncType=0
TV_SECTimeout=1
The AgentTimeOut entry sets the amount of time, in seconds, the DBMS should try to talk to the Agent before
giving up.
The ClientDelayPulse entry sets how often the DBMS should check for missing clients.
The DataPath entry lists the directory where the GECS data files are located. By default a dot (.) indicates that the
data files exist in the GECS data directory (C:\GECS\DATA). There are several important things to keep in mind
15-5
Technical Reference
about how GECS components access data files when determining how to setup their location.
1) Your GECS DBMS cannot use drive letters when run as a service. It must use UNC (Universal Naming
Convention) or ‘domain’ and ‘share’ names by making an entry such as:
\\DOMAIN1\C$\GECS\DATA
2) The other GECS programs can all use drive letters by making an entry such as:
C:\GECS\DATA
3) The GECS NLMs cannot use drive letters. They must access the data files using the NetWare naming
convention of ‘servername/volume:’ by making an entry such as:
FS1/SYS:\GECS\DATA
The DBMSTimeout tells GECS programs how long, in seconds, they should try and talk to the GECS DBMS. This
entry defaults to 10 seconds.
The DelJobEvents entry determines whether Events assocated with jobs should be deleted when job records are
deleted. This entry defaults to 1 which means ‘yes’ automatically delete GECS Events assocated with job records
when job records are deleted. 0 would not delete Events.
The DoLocalDataAccess entry can be set =1 to allow the Client programs to access the data files directly
instead of going through the GECS DBMS program to access the data. Direct data access will usually be faster
making the Client programs seem more responsive. You must specify a DataPath when this option is enabled.
The HeartBeat entry sets how often the GECS programs should send a heartbeat ping to the DBMS. This entry
defaults to every 60 seconds.
The MaxClientDelay entry defines after how many seconds should the DBMS decide that the Client programs
have disappeared. It will then close open files and free resources. This MUST be greater than the HeartBeat. This
entry defaults to 600 seconds.
The PrimaryDBMS entry is reserved for a future version.
The RecvTimeout entry sets how long the DBMS should wait to receive a response from Agents.
The SecondaryDBMS entry is reserved for a future version.
The SendAttempts entry defines how many times programs should attempt to send packets to the DBMS. This
entry defaults to 5 times.
The SyncFrequency entry defines how often in seconds the DBMS should time synchronize. This entry
defaults to 600 seconds.
The SyncServer entry is used to specify the server computer that the DBMS should synchronize its time to. This
entry is blank by default.
The SyncTimeout entry tells the DBMS how long, in seconds, it should try to synchronize its time. This entry
defaults to 60 seconds.
The SyncType sets the type of time synchronization that should be used by the DBMS. 0=none, 1=Microsoft,
2=NetWare, 3=Time protocol (RFC-868) and 4=NTP/SNTP (RFC-1305/1361/1769/2030). This entry defaults to
zero.
The TV_SECTimeout entry defines the amount of time, in seconds, the thread block should wait when selecting a
packet. This entry defaults to 5 seconds.
[ENVIRONMENT] Section
The [ENVIRONMENT] section can be used to define environmental variables that Windows Agents can set prior
to job execution. For example:
15-6
Technical Reference
[ENVIRONMENT]
JOBNUM=@JOBNUM
AGENT=@AGENT
PARENT=GECS
Only a limited number of the special GECS substitution variables can be used. These must be set for each Windows
Agent separately in each Agent’s local GECS.INI configuration file.
[FORMAT] Section
The [FORMAT] section can contain an option which determines how date substitution variables are formatted. For
example:
[FORMAT]
DATE=0
DATES=0
DateFormatShort=string
DateFormatLong=string
TimeFormat=string
Note that either DATE=n or DATES=n can be used.
GECS can format date substitution variables in five different formats:
n
Format
Example
0
1
2
3
4
mm/dd/yyYY
dd-mm-yyYY
ddMMMyyYY
mm-dd-yyYY
dd/mm/yyYY
12/31/99 or 12/31/1999
31-12-99 or 31-12-1999
31DEC99 or 31DEC1999
12-31-99 or 12-31-1999
31/12/99 or 31/12/1999
Some date substitution variables will produce 2 digit years (i.e. @DATE) and some will produce 4 digit years (i.e.
@DATEL). Note that if this section is omitted, GECS defaults to format 0 (mm/dd/yyYY).
You can also use the ‘string’ to override the default formatting or the formatting specified by ‘Date=n’. The ‘string’
is a formatting string that can contain one or more of the following special fields:
%b
abbreviated month uppercase (JAN)
%c
abbreviated month capitalized (Jan)
%B
month (January)
%m
month (2 character)
%d
day (2 character)
%1
month (1 or 2 character)
%2
day (1 or 2 character)
%n
day with suffix (1st, 2nd)
%y
year (2 character)
%Y
year (4 character)
%A
day of week (Monday)
%a
day of week (Mon)
%H
hour in 24 hour format
%I
hour in 12 hour format
15-7
Technical Reference
%M
minute
%S
second
%T
hundredths of seconds
%p
AM or PM
For example:
[FORMAT]
DateFormatShort=%m.%d.%y
DateFormatLong=%B %n, %Y
TimeFormat=%H:%M
would cause the following output:
@DATE
@DATEL
@TIME
12.31.02
December 31st, 2002
23:59
Note that ‘TimeFormat’ overrides the default formatting of @TIME and @SCHTIME, but not @MTIME.
@MTIME uses “%H:%M:%S” regardless of what ‘TimeFormat’ is set to.
Lastly, you can use formatting strings with the substitution variable to override any other formatting specified by
including the formatting string in parenthesis immediately after the substitution variable and before any date math.
For example:
@DATE(%m)
12
@DATEL(%1.%2.%y)
12.31.02
@TIME(%I o’clock)
11 o’clock
@DATE(%d)+1d
1
No spaces are allowed between the substitution variable and the parenthesis. Empty parenthesis will use the default
formatting.
[FORMS] Section
The [Forms] section contains configuration information for GECS Windows Client programs. This section is
updated by GECS when Configuration Options or window positioning is changed. This section should not be
changed manually.
[OPTIONS] Section
The [Options] section is used to store default values for the GECS Windows clients. Each GECS user has a unique
set of defaults. This section is automatically updated by GECS and should not be altered manually.
[Options]
User_AppID_ControlID=Value
15-8
Technical Reference
[STUDIO] Section
The [Studio] section contains configuration information for the GECS Studio client program. This section is
updated when the Configure options are set. This section should not be changed manually.
[STUDIO]
DetailYPos=5
DetailXPos=61
AutoLoadSheet=TEST WORKSHEET
WorkSheets=TEST WORKSHEET
AutoLoad=1
ShowPages=0
[WEBMANAGER] Section
The [WEBMANAGER] section can contain an option to set the amount of seconds the “Problems” html page
automatically updates with information. For example:
[WEBMANAGER]
RefreshRate=15
This rate defaults to 15 seconds.
Updating a GECS.INI file
To successfully make changes to a configuration file, perform these steps:
1. Shutdown your GECS DBMS.
2. Stop all users from running GECS Client programs and utilities.
3. If you intend to change the location of any data files, copy the data files to the new location and rename the
original copies of the files to an extension of .OLD so they won’t accidentally be used.
4. Double click on the notepad icon labeled GECS.INI from your GECS Controller folder (or use any text editor) to
edit each locally stored GECS.INI file on every machine where applicable.
5. Restart your Controller and test the GECS programs before allowing your users to start using them.
Time Synchronization
In a distributed multiple PC environment such as is found with GECS, time synchronization can keep your system
operating in an efficient fashion. Some network operating systems provide a mechanism to synchronize machines
on the LAN. If your environment offers such a feature, it should be used whenever possible.
GECSTIME.EXE
The GECSTIME command line utility can be run to display the current date and time. Usage:
gecstime tp|sntp ipnameaddr [port]
15-9
Technical Reference
Use Time Protocol (tp) or
Tp|sntp
Simple Network Time Protocol (sntp).
Ipnameaddr
The time server's IP name or address.
(i.e. time.nist.gov)
Port
The time server's port (optional).
Defaults to 37 for tp and 123 for sntp.
For example:
gecstime sntp 192.43.244.18
Network Time:
GMT = Wed Jun 11 16:11:30 2003
Local = Wed Jun 11 11:11:30 2003
Computer Time: GMT = Wed Jun 11 16:11:39 2003
Local = Wed Jun 11 11:11:39 2003
The GECS DBMS, Controller, Web Manager and Agent components of GECS can all be configured to synchronize
time using one of the following time synchronization methods: NetWare, Microsoft, Time Protocol (RFC-868) or
NTP/SNTP (RFC-1305/1361/1769/2030).
NetWare Time Synchronization
When the Novell configuration of GECS is used, certain components of GECS can synchronize with NetWare file
servers. For Windows, this requires the use of client software from Novell. The NetWare client software provided
by Microsoft will not allow GECS to synchronize its time with NetWare file servers. In the DBMS and Controller
records, you can choose the NetWare time synchronization method and enter the name of the NetWare file server
that should be used to synchronize with. The Web Manager program and Agent software must be configured to
synchronize by updating the GECS.INI file settings.
SyncType=2
SyncServer=servername
There are also GECS.INI settings for the time synchronization frequency and timeout values for all these
components by updating the following sections: [CONTROLLER], [DBMS], [WebManager] and [AGENT] with
the following entries:
SyncFrequency=600
SyncTimeout=60
Your DBMS or Controller must be logged in to the file server that it is going to synchronize with. NLM s can
synchronize their time with any file server that has the NetWare user ‘VINZANT_USER’ defined in its bindery.
This user is created automatically by the NLM installation program on the file server where the GECS data files are
located.
Microsoft Time Synchronization
Your DBMS or Controller can synchronize time with a Windows server or workstation when the Microsoft network
drivers are used. Enter the name of the Windows server to synchronize with in the DBMS or Controller record. The
user under whose account the Windows DBMS or Controller is running must have rights to change the system time.
The Web Manager program and Agent software must be configured to synchronize by updating the GECS.INI file
settings.
SyncType=1
SyncServer=\\servername
15-10
Technical Reference
There are also GECS.INI settings for the time synchronization frequency and timeout values for these components
by updating the following sections: [CONTROLLER], [DBMS], [WebManager] and [AGENT] with the following
entries:
SyncFrequency=600
SyncTimeout=60
Time Protocol (RFC-868)
Your DBMS or Controller can synchronize time using Time Protocol (RFC-868) by updating the DBMS or
Controller record with the method “Time Protocol (RFC-868)” and the IP Address or name of the host to
synchronize time with. For example:
Time Protocol (RFC-868)
TIME.NIST.GOV 37
The user under whose account the Windows DBMS or Controller is running must have rights to change the system
time. The Web Manager program and Agent software must be configured to synchronize by updating the
GECS.INI file settings.
SyncType=3
SyncServer=hostname or IPADDRESS [port]
There are also GECS.INI settings for the time synchronization frequency and timeout values for all of these
components by updating the following sections: [CONTROLLER], [DBMS], [WebManager] and [AGENT] with
the following entries:
SyncFrequency=600
SyncTimeout=60
NTP/SNTP (RFC-1305/1361/1769/2030)
Your DBMS and Controller components can synchronize time using NTP/SNTP (RFC-1305/1361/1769/2030) by
updating the records with the method “NTP/SNTP (RFC-1305/1361/1769/2030)” and the IP Address or name of
the host to synchronize time with. For example:
NTP/SNTP RFC-1305/1361/1769/2030)
TIME.NIST.GOV 37
The user account the DBMS or the Controller is running under must have rights to change the system time. The Web
Manager program and Agent software must be configured to synchronize by updating the GECS.INI file settings.
SyncType=4
SyncServer=hostname or IPADDRESS [port]
There are also GECS.INI settings for the time synchronization frequency and timeout values for these components
by updating the following sections: [CONTROLLER], [DBMS], [WebManager] and [AGENT] with the following
entries:
SyncFrequency=600
SyncTimeout=60
The local time of each computer will be adjusted to match the file server or time server time according to the entry
set for the SyncFrequency in the GECS.INI file. By default the SyncFrequency is set to every 600 seconds.
The SyncTimeout tells how long the GECS component should try and time synchronize. By default it will on ly try
for 60 seconds then quit trying until the next SyncFrequency.
If you have been using the Novell SYSTIME utility as part of your job flow to correct time shift, you should be able
to eliminate these jobs and use the time synchronization built into GECS. Additionally, if you have jobs that change
the system time, built in time synchronization should help correct this problem. On the other hand, if your job
stream relies on the system time being artificially changed, you should not use the time synchronization feature built
15-11
Technical Reference
into GECS as it will negate your artificial time change.
For more information on Time Protocol (RFC-868) or NTP/SNTP(RFC-1305/1361/1769/2030) you can reference
the Internet sites for these time server methods.
Time Change Issues
GECS uses the computer’s local system time to determine when jobs should be run, how long they ran, and how
long ago they ran. There are two types of time changes that can be expected. The time might slide forward or back
an hour due to daylight savings time or the time might slide forward or back small amounts due to time
synchronization. The GECS architecture is based on several assumptions.
1. A job’s scheduled time is entered in the local time of the computer.
2. Time moves forward, it doesn’t go backwards.
Due to the importance of time to GECS, special time change handling has been built into the system to handle
situations where time goes ‘backwards’. When GECS discovers that time has gone backwards (i.e. it was 02:00:00
and it’s now 01:58:00) it stops processing and waits for the time to get back to the original time (02:00:00).
Changes Due To Synchronization
When time synchronization is used to handle the ‘drift’ that is normal for PC clocks either by using the
synchronization built into the LAN or the synchronization built into GECS, these changes are typically small
(usually less than one second or two) and the effects of the system waiting for the time to catch up should be
unnoticeable.
Changes Due To Spring Daylight Saving Time
When Daylight Savings Time goes into effect in the spring and time springs forward, the clock goes from 01:59:59
to 03:00:00. The effect of this time change is small and generally benign. There are several special items worth
noting.
1. Jobs running before the time change and finishing after the time change will appear to have run an hour
longer than they actually ran.
2. There will appear to be a backlog of jobs immediately after the time change, as an hours worth of jobs
will immediately come due.
3. The night when the time change occurs contains one less hour of processing time.
Changes Due To Fall Daylight Savings Time
When Daylight Savings Time ends in the fall and time falls back, the clock goes from 01:59:59 to 01:00:00. The
effect of this time change is moderate, though generally benign. There are several special items worth noting.
1. Jobs running before the time change and finishing after the time change will appear to have run in less
time than they actually ran.
2. Jobs that finish during the hour after the time change will appear to all finish at about 02:00:00.
3. GECS will sit idle for the hour after the time change, waiting for the time to get back to 02:00:00.
4. The night when the time change occurs contains one extra hour of processing time, though the GECS
will sit idle for that hour.
To prevent GECS from sitting idle for this hour requires user intervention. After the time has changed, shut down
GECS and once it has been shut down, restart it.
15-12
Technical Reference
Minimizing the Effects Of Daylight Savings Time Changes
The only certain way to eliminate all effects of Daylight Savings Time Changes is to shutdown GECS prior to the
time change and then to restart it after the time change. Only in the most time sensitive situations should this be
required. The built in time change handling capabilities of GECS should be able to handle most situations, with the
anomalies described above.
Configuring GECS for Sound
A wide variety of sound cards are available today. Each requires its own set of Windows drivers. Drivers for the
most popular sound card drivers are included with Windows. Windows drivers for other sound cards are provided
with the sound cards. The sound card driver configuration required for each card may vary. Follow the instructions
provided with your sound card. GECS will be able to play WAV files on your sound card once it’s properly
configured. To test your sound card installation for GECS:
1. Select Control Panel
2. Select Sounds. If “Sound” is not shown as an icon, your configuration is incorrect.
3. Single click on a WAV file from the list on the left. If you cannot select a WAV file, your configuration is
incorrect.
4. Press the “Test” button. If sound is produced, your sound card is properly configured.
Using GECS Event WAV Files
GECS can play specified WAV files when certain GECS Events occur. Use the Events Definitions option in the
Windows Administrator program to specify a fully qualified WAV file name to annunciate your Events. You can
use ones you record yourself or ones you purchase. Simply specify the desired WAV file in the Event Definition
WAV file name field. For example:
C:\WINDOWS\TADA.WAV
To test whether your WAV file is compatible with GECS, try the WAV file using Media Player, Sound Recorder or
the Control Panel Sound section.
GECS Licensing Restrictions
GECS tracks the Agents being run and compare this information to the information from the license number
installed for your system. The license information can be seen in several places. The Windows Administrator client
program contains the Help menu selection ‘Help About’ where your license information can be viewed. The
Workstation Setup programs for Windows is used to update the license information. This program displays the
name of the company the software is licensed to in the main window. Evaluation licenses will expire on a particular
date and most purchased licenses will be limited to particular number of running Agents and the type of Agent. An
Agent will not be serviced by GECS if:
1. The license is expired.
2. There are already too many Agents running.
3. The license is not for this type of Agent (i.e. Windows, NLM, & Linux versus Unix).
15-13
Technical Reference
4. The license file cannot be located.
With a five Agent license you can run five Agents at a time. If you attempt to start a sixth Agent, GECS will
randomly decide which Agent has breeched the license and which Agent to stop servicing.
The license information is contained in a file named ECSDRIVE.EXE. If you should get an error that the license
information cannot be located, check the GECS.INI entry for this file to see that it properly points to the drive and
subdirectory where this file is located. By default, this file is in the subdirectory where your GECS data files are
located. Do not distribute this file to anyone. Your company’s name and license number are contained in this file
and will be displayed when the Windows client software is run. It is also important to keep track of the license
number label from your printed license agreement. GECS will not run without a valid license number. Should you
need to reinstall your software, you will need this number.
NetWare Issues
Microsoft vs. Novell Drivers
The NetWare specific features of GECS require the use of drivers from Novell for Windows. The NetWare drivers
from Microsoft can be used, but will not provide the NetWare specific functions available when the drivers from
Novell are used, such as NetWare messaging. If you are using NetWare drivers from Microsoft, you should
configure the system in Workstation Setup as using No Network or a Microsoft network.
Bindery Emulation
In a NetWare 4 or 5 environment, bindery emulation is required for the NetWare specific flavors of GECS.
Microsoft/LAN Server Network Issues
User Names
The Microsoft/LAN Server network flavor of the client program does NOT check to see that the network user names
entered as GECS user names are valid when they are added. GECS user names that are not valid network user names
will not be usable. GECS user names must be the same as network user names. The network user names used when
submitting jobs must match GECS user names or the job will not run.
Event Network Messaging
When GECS Events are setup, in Event Definitions, to notify via Network Message, GECS uses the Messenger
Service to send the message. The Messenger Service must be running in the DBMS machine that is going to send
messages and in all workstation nodes that are to receive messages. Additionally, each node that is to receive a
message must be running the Netpopup Service. If the Netpopup Service is not run, the messages are written to a log
file, but aren’t displayed on the workstation. If the Messenger Service is not run, users cannot be notified that jobs
have been completed via network messaging.
15-14
Technical Reference
No Networking Issues
User Names
GECS is unable to determine a user name based on the user’s network name with this flavor. The GECS Windows
Client programs will determine the user name by prompting the user for a user name and password each time the
programs are started. The user name and password can also be passed on the command line for the programs by
including the /U: and /P: options on the command line. For example:
C:\GECS\PROGNAME.EXE /U:username /P:password
Where PROGNAME.EXE is the name of the GECS Windows client program. The user name entered at the prompt
(or on the command line) must be a user name that has been defined in the GECS user file. The password must be the
password entered in the Network Password field for the user. The password is not visible on the screen (it appears as
stars (*)) and is stored in an encrypted fashion. To eliminate the password, fill the Network Password field with
spaces. If a user has no password, no password needs to be passed on the command line or entered in at the prompt.
Event Network Messaging
No Event network messaging is available when using the “No” Networking option from the GECS Workstation
Setup program.
15-15
Technical Reference
15-16
GECS Security
GECS Security
16-1
GECS Security
16-2
GECS Security
Access to the GECS Client programs
The Global Event Control Server® has its own security system that determines what users can and can’t do with the
GECS Client programs. These rights are defined in Security Profiles. Each GECS User must be associated with a
Security Profile.
When using the Microsoft/LAN Server or No network configuration, the Client programs will only allow valid
GECS users access. Consequently, it is imperative that the first user added have rights to access ALL of the GECS
Client program components.
One GECS user is automatically created when the GECS software is first installed. This user is made part of the
ADMIN Security Profile and thus given access to all components of the GECS system as displayed above.
By default an ADMIN and OPERATOR Security Profile are defined. Once a Security Profile has been created and
defined, Users can be assigned to the specified Security Profile thus giving them access to the specified GECS
Client program components as defined for the Security Profile.
You can create as many GECS Security Profiles as necessary. The ADMIN default Security Profile can be modified
but cannot be deleted. The OPERATOR default Security Profile can be modified and/or deleted.
16-3
GECS Security
Security Enhancements
The security in GECS 3.10 has been substantially enhanced. The enhancements have been developed in
conjunction with staff from the Center for Education and Research in Information Assurance and Security
(CERIAS) at Purdue University. The goal of the enhancements was to accomplish these goals:
No one should be able to view the communications as it is been transmitted between components. To
accomplish this, we have enhanced the encryption scheme used to encrypt communications packets. We are using a
64 bit block cipher encryption scheme with 128 bit keys.
No one should be able to record packets and replay them at another time. The encryption keys used by the
system are constantly changing. Packets encrypted at one time cannot be decrypted at another time. This prevents
packets from being replayed.
Components must be able to verify that communications are valid. To accomplish this, we allow users to create
certificates that are unique for their computer and installation. The certificates are used as part of the encryption
scheme. Certificates are optional. If you decide to employ this option, it must be manually set up. See the following
instructions for certificate management set up.
Setting Up Packet Encryption
To enable packet encryption, you must run the Certificate program (GECSCERT) described below.
Client programs that are configured to directly access the GECS data files cannot take advantage of this data
encryption. This is because the direct data access method is performed by the operating system and network drivers
not the GECS DBMS.
To configure GECS to run without direct data access, open the Workstation Setup program and ensure the ‘Enable
Data Path’ field on the Client Programs page is not enabled.
Setting Up GECS Certificate
Management
To set up certificate management for your Global ECS system, you must run the GECSCERT program on every
computer that will be running GECS components. You must establish a unique password for your system. This
password must be entered when this program is run. Any computer without the proper certificate will be locked out
of the system. Information about this computer is encrypted with the password to prevent this certificate from being
used on other computers.
The password is the key to generating the certificate code. We recommend the password exceed 16 characters but
no more than 255 characters. Normal rules of command line arguments apply. (i.e. If you are using spaces in your
password it should be enclosed in quotes). For example:
GECSCERT /NEW abc1234567890wxyz abc1234567890wxyz
Where 'abc1234567890wxyz' is your password. It is entered twice for verification.
16-4
GECS Security
To disable certificate management you can run the GECSCERT program with the delete option. For example:
GECSCERT /DEL abc1234567890wxyz
For Windows, you must be logged in as Administrator and you must have the appropriate password to disable this
scheme.
For Unix, you should be logged in as root. A file will be created on the machine in the /GECS subdirectory.
16-5
GECS Security
16-6
File Glossary
File Glossary
17-1
File Glossary
17-2
File Glossary
File Glossary
GECS Data Files
The GECS data files must be located in the subdirectory specified in the GECS.INI file. This file contains a listing
for each file. The GECS.INI file must be in the ‘WinNT’ directory (i.e. C:\WINNT). Users must have read/write access to the subdirectory where the GECS data files are located.
This file contains late breaking news on this version which is not included in this manual.
READ.ME
This file contains custom configuration information used by many of the GECS programs. This file is created automatically when GECS is installed. It can be created by hand for special Windows Agent configuration.
GECS.INI
These files are the actual data files that hold the client program’s information. The Client programs and the Controller program must have access to these files.
ALERTS.DAT
BATCHDET.DAT
BATCHES.DAT
BATCHVAR.DAT
BUSIDAY.DAT
CALTYPE.DAT
DEFMONTH.DAT
EVENTDEF.DAT
EVENTS.DAT
EVTVIEWS.DAT
JOBS.DAT
JOBVIEWS.DAT
RESOURCE.DAT
SERVERS.DAT
UGROUPS.DAT
USERS.DAT
VACATION.DAT
WRKSHEET.DAT
WRKITEM.DAT
ALERTS.IDX
BATCHDET.IDX
BATCHES.IDX
BATCHVAR.IDX
BUSIDAY.IDX
CALTYPE.IDX
DEFMONTH.IDX
EVENTDEF.IDX
EVENTS.IDX
EVTVIEWS.IDX
JOBS.IDX
JOBVIEWS.IDX
17-3
File Glossary
RESOURCE.IDX
SERVERS.IDX
UGROUPS.IDX
USERS.IDX
VACATION.IDX
WRKSHEET.IDX
WRKITEM.IDX
These files are the empty copies of the actual data files that are used by the Rebuild programs to rebuild the data files.
ALERTS.CLD
BATCHDET.CLD
BATCHES.CLD
BATCHVAR.CLD
BUSIDAY.CLD
CALTYPE.CLD
DEFMONTH.CLD
EVENTDEF.CLD
EVENTS.CLD
EVTVIEWS.CLD
JOBS.CLD
JOBVIEWS.CLD
RESOURCE.CLD
SERVERS.CLD
UGROUPS.CLD
USERS.CLD
VACATION.CLD
WRKSHEET.CLD
WRKITEM.CLD
ALERTS.CLI
BATCHDET.CLI
BATCHES.CLI
BATCHVAR.CLI
BUSIDAY.CLI
CALTYPE.CLI
DEFMONTH.CLI
EVENTDEF.CLI
EVENTS.CLI
EVTVIEWS.CLI
JOBS.CLI
JOBVIEWS.CLI
RESOURCE.CLI
SERVERS.CLI
UGROUPS.CLI
USERS.CLI
VACATION.CLI
WRKSHEET.CLI
WRKITEM.CLI
These files are installation files:
17-4
File Glossary
SETUP.INI
SETUP.EXE
GTREE.DLL
VERSION.TXT
SETUP.BMP
READ.ME
AUTORUN.INF
DATAINST
CLNTINST
AGNTINST
LASTDISK
COMMANDS.TXT
DISK
This data file holds the last parameters or options selected for reports client program.
JSETREPO.DAT
These files contain the command lines that the GECS Windows Agent should run before and after every NT Console or DOS command line type job. These files must be accessible by Windows Agents.
PRECMD.TXT
POSTCMD.TXT
GECS Browser Client Files:
*.GIF
*.HTML
*.JPG
This file contains the online manual in Adobe Acrobat format.
GECSMAN.PDF
GECS Program Files
The GECS program files (BAT, CMD, EXE, COM and Windows DLL files) must be in the default subdirectory or
in the search path when the programs are started.
These files are the Windows DLLs that contain program code that the Windows client setup programs need in order
to operate.
GECS32.DLL
GECSAPI.DLL
GECSTREE.DLL
GTREE.DLL
GECSBMAN.DLL
GECSCAL.DLL
GECSLOG.DLL
GECSLOGO.DLL
GECSRES.DLL
GECSRPTS.DLL
GECSSRVA.DLL
GECSSRVC.DLL
GECSUSER.DLL
GECSVAC.DLL
17-5
File Glossary
JOBVIEW.DLL
These files are different versions of the Windows DLL GECS32.DLL. Depending on the network selected in Workstation Setup, one of these files will have been copied to GECS32.DLL. GECSNW32.DLL is used if NetWare Client for Windows Novell from Novell are being used. GECSMS32.DLL is used when the Microsoft client software
supplied with Windows is installed. GECSNN32.DLL is used for no networking.
GECSNW32.DLL
GECSMS32.DLL
GECSNN32.DLL
ECSW.DLL
This program is the Windows Client program.
GECSADMN.EXE
These Windows Agent programs allow keystrokes to be passed to DOS programs in your jobs.
KS.EXE
KSLOAD.COM
WAITKEY.EXE
These files are Btrieve conversion files.
WDBUEI32.DLL
W32MKSET.DLL
W32MKDE.EXE
WDBAUI32.DLL
W32MKRC.DLL
W32MKSET.EXE
W32MKSET.HLP
WBTRV32.DLL
This program allows login passwords to be changed in the GECS user file.
GECSPASS.EXE
This program displays a list of jobs in the queue.
GECSQUEU.EXE
This program displays a list of jobs an Agent can run in the queue.
GECSCAN.EXE
This program displays a list of jobs an Agent can’t run in the queue.
GECSCANT.EXE
This program can be used to rebuild/convert the GECS data files.
GECSRBLD.EXE
This program can be used to validate the GECS data files.
GECSVAL.EXE
This program can be used to add calendar entries.
GECSCALE.EXE
This program can be used to add users.
GECSAUSR.EXE
17-6
File Glossary
This program can be used to flag jobs to override dependencies.
GECSOVER.EXE
This program can be used to trigger completed jobs.
GECSTRIG.EXE
This program can be used to purge old jobs.
GECSPURG.EXE
This program can be used to change a job’s number.
GECSCNUM.EXE
This program can be used to change the submitting user on a job.
GECSCUSE.EXE
This program can be used to flag a running job for termination.
GECSSTP.EXE
This program is used to launch 16 bit Windows programs under Windows NT/2000/XP/2003 when you want to be
able to get the return code.
LAUNCH16.EXE
ECSW.DLL
These programs are used internally when Windows Agents and Controllers are run as a service.
ASERVICE.EXE
CSERVICE.EXE
DSERVICE.EXE
WSERVICE.EXE
This program can be used to test job return codes from Windows Agents.
WINRET32.EXE
WINRET.EXE
DOSRET.EXE
OS2RET.EXE
GECSRET.EXE
This program is used to cause your Windows Controller to pulse at any given time.
PULSENOW.EXE
This program is the GECS Windows Agent program.
GECSAGNT.EXE
This program can be used to hide or minimize the Windows Controller or Agent programs.
GECSHIDE.EXE
This program can be used to check whether a GECS Agent or Controller is running.
GECSPING.EXE
This program can be used to stop a GECS Controller or Agent.
GECSSTOP.EXE
This program can be used to show a hidden or minimized Windows Controller or Agent.
GECSSHOW.EXE
17-7
File Glossary
This program can be used to tell a GECS Agent to immediately run a command.
AGENTRUN.EXE
This program can be used to convert ECS 5.1 or GECS 1.5 data to GECS2.0 format. It is installed in a \CONVERT
subdirectory ‘under’ the program directory along with the necessary Btrieve DLL’s.
GECSCONV.EXE
This program is the actual GECS Controller program.
GECSPROC.EXE
This program is the DBMS program.
GECSDBMS.EXE
This program is the Web Manager program.
GECSWEBS.EXE
This program can be used to delete jobs from the jobs file without using the Client programs.
GECSDEL.EXE
This program can be used to delete logs from the logs file without using the Client programs.
GECSLDEL.EXE
This program can be used to pause and unpause your Windows Controller remotely.
GECSPAUS.EXE
This program can be used to allow one batch to depend on other batches.
BATCHDON.EXE
This program can be used to uninstall GECS from a Windows computer.
GECSUNIN.EXE
This program can be used to export jobs from the jobs file.
GECSDUMP.EXE
This program can be used to export completed jobs.
GECSLDUM.EXE
This program can be used to cleanup the jobs and monitor files automatically after a system failure.
GECSCLEA.EXE
This is the application help file used for the Windows Client programs.
GECSHELP.HLP
This program is the Workstation Setup program that configures and adds icons to your client machines. It also
configures GECS.INI.
W40SETUP.EXE
This program is the Workstation Setup program that configures and adds icons to your Windows Controller machine. It also configures GECS.INI.
C40SETUP.EXE
GECSUTIL.EXE
17-8
File Glossary
This program is the Workstation Setup program that configures and adds icons to a Windows Agent machine. It also
configures GECS.INI, the registry and services.
A40SETUP.EXE
A40SETUP.HLP
This file is used by the Workstation Setup program.
DATALIST
This file is read by the Windows Workstation Setup program. It tells the program about the group to create and the
icons that should be created.
GROUP32C.TXT
GROUP32A.TXT
GROUP32W.TXT
Other Files Created
When your Controller tries to load a WRK file that has syntax errors in it, it renames the file to filespec.BAD.
During operation, your GECS Controller may create the following file:
*.BAD
When Windows Agents execute jobs with command line types set to NT Console or DOS, GECS creates a batch
file. This file is created in the Agent’s default subdirectory. It may also be created in the Local Subdirectory defined
for the Agent if it is defined to login as submitting users.
random.BAT
random.CMD
Files with a .wrk extension can be created using any text editor or emailed to GECS and can be converted into jobs.
*.WRK
When the Rebuild utility is used, it creates temporary files with the name:
NEWFILE.DAT
NEWFILE.IDX
Files named JOBNUM.EL can be used to send return codes to your Windows Controller.
jobnum.EL
Other Required/Optional Files
Your Windows Agents may need to find the command processor. These files should be specified in the COMSPEC
environmental variable.
COMMAND.COM
CMD.EXE
17-9
File Glossary
Overview of Data File Structure
The Global Event Control Server® is comprised of various programs and data files that work together to create a
system for scheduling and executing jobs. The various components are broken up to allow for configurations with
varying levels of security and so that GECS can be easily interfaced to other applications.
The various programs work with two sets of data files. The main GECS data files hold scheduled jobs, users,
Controller, Agents and Events. Newly submitted jobs can be stored in WRK files. When GECS has no jobs to
dispatch, it can look for WRK files and add them to the Scheduled Jobs file to be executed by your Agents. This two
layer method of adding jobs does two things. First it allows GECS to validate jobs before adding them to the real
files. Second, it provides a convenient way for other programs to schedule jobs. WRK files are simple text files.
The principle data files used by GECS are:
ALERTS
This data file contains Events to be displayed in the User’s Events lists.
BATCHDET
This data file contains a record for each defined batch job.
BATCHES
This data file contains a record for each defined batch.
BATCHVAR
This data file contains a record for each defined batch variable.
BUSIDAY
This data file contains a record for each date that is a non-business day. Jobs can be rescheduled based on business
and non-business days.
CALTYPE
This data file contains a record for each defined calendar.
DEFMONTH
This data file contains a record for the first day of each defined month.
EVENTDEF
This data file contains a record for each defined job.
EVENTS
This data file contains a record for each defined job.
EVTVIEWS
This data file contains a record for each defined job.
JOBS
This data file contains a record for each defined job.
17-10
File Glossary
JOBVIEWS
This data file contains a record for each defined job.
RESOURCE
This data file contains a record for each defined resource. The file contains a record for each that contains the
resource and a record for each system resource.
SERVERS
This data file contains a record for each defined Controller and Agent.
UGROUPS
This data file contains a record for each defined resource. The file contains a record for each that contains the
resource and a record for each system resource.
USERS
This data file contains a record for each defined GECS user.
VACATION
This data file contains a record for each defined vacation period. A vacation period is a period of time that jobs of a
particular class should not be allowed to run. Jobs scheduled to run during a vacation period either reschedule
themselves or wait until the vacation period ends before running.
WRKSHEET
This data file contains a record for each work sheet created in the GECS Studio client program.
WRKITEM
This data file contains a record for each item on the GECS Studio work sheets.
PRECMD.TXT
This ASCII text file contains command lines that you would like to have executed before each job is run. This file is
used system wide and will be run before every Windows NT Console, DOS or OS/2 command line type job.
POSTCMD.TXT
This ASCII text file contains command lines that you would like to have executed after each job is run. This file is
used system wide and will be run after every Windows NT Console, DOS or OS/2 command line type job.
GECS.INI
This ASCII text file contains information about the location of the GECS data files for all GECS programs. See the
“Technical Reference” chapter of this manual for details.
Using ODBC to Access GECS Data
You can use ODBC drivers to access GECS data. These drivers are available by purchasing the GECS SDK
product. For information you may contact Vinzant, Incorporated at 800-355-3443 or www.vinsoft.com.
17-11
File Glossary
Job Dump Data Files
Fixed Length Files
Each record has a fixed length of 2104 bytes (including the terminating CR/LF). Each field is a fixed length.
Numeric fields are right justified zero filled. Trailing spaces in text fields are included. Dates and times are in the
format of MM/DD/YYYY and HH:MM:SS respectively. The jobs are written to the file in job number order. Each
FIXED record has a fixed number of fixed length fields. Note that this file format does not include many of the job
parameter fields.
The file layout is :
Field
Offset
Len
Format
Notes
jobnum
0
10
xx...xx
job number
cmdline
10
128
xx...xx
command line to execute
path
138
128
xx...xx
Path to change to before
executing
nextdate
266
10
mm/dd/yyyy
date of next execution
nexttime
276
8
hh:mm:ss
time of next execution
repunit
284
5
nnnnn
0=sec, 1=min, 2=hr,3 =day,
4=week, 5=month, 6=year,
7=business day, 8=nonbusinessday, 9=defined month
repvalue
289
9
nnnnnnnnn
number of units before repeat
repbase
298
5
nnnnn
0=from start, 1=from end,
group
303
8
xxxxxxxx
execute by Agent machine in this
group
priority
311
5
nnnnn
0=high, 9=low
status
316
5
nnnnn
3=completed
0=pending, 1=started, 2=On Hold,
Agent
321
8
xxxxxxxx
Agent to execute
username
349
48
xx...xx
user who submitted job
osreq
397
5
nnnnn
operating system required
2=from schedule
0=Other, 1=Any,
2=WinNT/2000/XP/2003,
3=UnixWare, 4=NetWare,
5=Win95/98/ME, 6=Linux, 7=AIX,
8=HPUX, 9=Solaris, 10=OS/400,
11=Tru64, 12=IRIX
comment
457
128
xx...xx
misc comments
execafter
585
10
xx...xx
job number to execute after
title
595
30
xx...xx
description of job
diskspace
630
9
nnnnnnnnn
minimum megabytes of disk
required
maxretval
639
5
nnnnn
max ret value for execafter
totaltimes
644
5
nnnnn
total times to repeat 0=infinite
timesleft
649
5
nnnnn
remaining times to execute
substcmd
654
5
nnnnn
substitute command line
0=no, 1=yes
filespec
659
128
xx...xx
execute if this file exists
17-12
File Glossary
fileexist
787
5
nnnnn
0=when none of the files exist,
1=when any of the file exists,
2=when any file exists and can be
opened sharable, 3=when any file
exists and can be opened
exclusive, 4=when all files
exist, 5=when all files can be
opened sharable, 6=when all files
can be opened exclusive.
timeafter
792
8
hh:mm:ss
time after execafter job finishes
class
800
8
xxxxxxxx
maps to vacation file
relaabso
808
5
nnnnn
0=relative repetition,
1=absolute repetition,
2=day of week, 3=special
nth
813
5
nnnnn
number of variable units
daytype
818
5
nnnnn
0=days, 1=business days, 2=nonbusiness days,3=weeks,4=months,
5=sundays, 6=mondays, 7=tuesdays,
8=wednesdays, 9=thursdays,
10=fridays, 11=saturdays
begend
823
5
nnnnn
0=from beginning, 1=from end,
2=on or after beginning, 3=on or
before end
period
828
5
nnnnn
0=week,1=month,2=defined month,
3=quarter,4=half,5=year
osver
833
5
nn.nn
the minimum operating system
version
keys
838
255
xx...xx
1st set of keys to shove into the
keyboard buffer
exaft02
1093
10
xx...xx
run job after
exaft03
1103
10
xx...xx
run job after
exaft04
1113
10
xx...xx
run job after
exaft05
1123
10
xx...xx
run job after
exaft06
1133
10
xx...xx
run job after
exaft07
1143
10
xx...xx
run job after
exaft08
1153
10
xx...xx
run job after
exaft09
1163
10
xx...xx
run job after
exaft10
1173
10
xx...xx
run job after
exret02
1183
5
nnnnn
max ret value of job to run after
exret03
1188
5
nnnnn
max ret value of job to run after
exret04
1193
5
nnnnn
max ret value of job to run after
exret05
1198
5
nnnnn
max ret value of job to run after
exret06
1203
5
nnnnn
max ret value of job to run after
exret07
1208
5
nnnnn
max ret value of job to run after
exret08
1213
5
nnnnn
max ret value of job to run after
exret09
1218
5
nnnnn
max ret value of job to run after
exret10
1223
5
nnnnn
max ret value of job to run after
extim02
1228
8
hh:mm:ss
time after execafter job finishes
extim03
1236
8
hh:mm:ss
time after execafter job finishes
extim04
1244
8
hh:mm:ss
time after execafter job finishes
extim05
1252
8
hh:mm:ss
time after execafter job finishes
17-13
File Glossary
extim06
1260
8
hh:mm:ss
time after execafter job finishes
extim07
1268
8
hh:mm:ss
time after execafter job finishes
extim08
1276
8
hh:mm:ss
time after execafter job finishes
extim09
1284
8
hh:mm:ss
time after execafter job finishes
extim10
1292
8
hh:mm:ss
time after execafter job finishes
retryafter
1300
5
nnnnn
retry job if it returns = this
number - 0=noretry
maxjobmin
1305
5
nnnnn
maximum minutes job should be
allowed to run
minnotcode
1310
5
nnnnn
minimum return code to notify
submitter of completion
exetype
1315
5
nnnnn
0=DOS, 1=Win31, 2=OS/2,
3=WinNT/2000/XP/2003, 4=NLM,
5=Win95/98/ME, 6=NT Console,
7=UnixWare, 8=Linux, 9=AIX,
10=HPUX, 11=Solaris,
12=OS/400, 13=Tru64, 14=IRIX
showactivity
1320
5
nnnnn
0=no,1=yes
estjobmin
1325
5
nnnnn
estimated minutes job should run
keys2
1330
255
xx...xx
2nd set of keys to shove into the
keys3
1585
255
xx...xx
3rd set of keys to shove into the
keys4
1840
255
xx...xx
4th set of keys to shove into the
subdate
2095
10
mm/dd/yyyy
date submitted
subtime
2105
8
hh:mm:ss
time submitted
escalmin
2113
5
nnnnn
escalalte after minutes late
failjob
2118
10
xx...xx
job to reactivate on failure
keepdone
2128
5
nnnnn
keep job Completewhen complete
latejob
2133
10
xx...xx
job to reactivate if late
launchmode
2143
5
nnnnn
launch job in this mode
maxgoodret
2148
5
nnnnn
maximum good return code
maxminlate
2153
5
nnnnn
maximum minutes late
message
2158
80
xx...xx
pre job message
relate0
2238
5
nnnnn
0 <=, 1 <, 2 =, 3 >, 4 >=, 5 <>
relate1
2243
5
nnnnn
0 <=, 1 <, 2 =, 3 >, 4 >=, 5 <>
relate2
2248
5
nnnnn
0 <=, 1 <, 2 =, 3 >, 4 >=, 5 <>
relate3
2253
5
nnnnn
0 <=, 1 <, 2 =, 3 >, 4 >=, 5 <>
relate4
2258
5
nnnnn
0 <=, 1 <, 2 =, 3 >, 4 >=, 5 <>
relate5
2263
5
nnnnn
0 <=, 1 <, 2 =, 3 >, 4 >=, 5 <>
relate6
2268
5
nnnnn
0 <=, 1 <, 2 =, 3 >, 4 >=, 5 <>
relate7
2273
5
nnnnn
0 <=, 1 <, 2 =, 3 >, 4 >=, 5 <>
relate8
2278
5
nnnnn
0 <=, 1 <, 2 =, 3 >, 4 >=, 5 <>
relate9
2283
5
nnnnn
0 <=, 1 <, 2 =, 3 >, 4 >=, 5 <>
resource0
2288
8
xx...xx
required resource
resource1
2296
8
xx...xx
required resource
resource2
2304
8
xx...xx
required resource
resource3
2312
8
xx...xx
required resource
resource4
2320
8
xx...xx
required resource
keyboard buffer
keyboard buffer
keyboard buffer
17-14
File Glossary
resource5
2328
8
xx...xx
required resource
resource6
2336
8
xx...xx
required resource
resource7
2344
8
xx...xx
required resource
resource8
2352
8
xx...xx
required resource
resource9
2360
8
xx...xx
required resource
Agent1
2368
8
xx...xx
run on Agent
Agent2
2376
8
xx...xx
run on Agent
Agent3
2384
8
xx...xx
run on Agent
Agent4
2392
8
xx...xx
run on Agent
Agent5
2400
8
xx...xx
run on Agent
Agent6
2408
8
xx...xx
run on Agent
Agent7
2416
8
xx...xx
run on Agent
Agent8
2424
8
xx...xx
run on Agent
Agent9
2432
8
xx...xx
run on Agent
sun
2440
5
nnnnn
run on sunday
mon
2445
5
nnnnn
run on monday
tue
2450
5
nnnnn
run on tuesday
wed
2455
5
nnnnn
run on wednesday
thu
2460
5
nnnnn
run on thursday
fri
2465
5
nnnnn
run on friday
sat
2470
5
nnnnn
run on saturday
caltype
2475
8
xx...xx
calendar type
escalprior
2483
5
nnnnn
escalation priority
beenescal
2488
5
nnnnn
has the jobs priority been
escalated
CR/LF
2493
2
0D0A
carrage return/linefeed
———
2495
Comma Separated Files
Each field is separated with a comma (,). Text fields are enclosed in double quotes (“). If the text fields contain any
double quotes (”), they are changed to single quotes (‘). Trailing spaces in text fields are omitted. Dates and times
are also enclosed in double quotes and are in the format of “MM/DD/YYYY” and “HH:MM:SS” respectively.
Numeric fields are NOT enclosed in quotes. The jobs are written to the file in job number order. Each CSV record
has a fixed number of variable length fields. Each record is terminated with a CR/LF.
The file layout is :
Job Record Field Name
Abbreviation
Format
Notes
Job
number
n,
batch.number-instanc
Command Line
cmdline
“xx...xx”,
command line to execute
Start In Directory
path
“xx...xx”,
path to change to before executing
Schedule Date
nextdate
“mm/dd/yyyy”,
date of next execution
Schedule time
nexttime
“hh:mm:ss”,
time of next execution
Relative-Repeat
repunit
n,
0=sec,1=min,2=hr,3=day,4=week,5=month,
17-15
File Glossary
6=year,7=business day,8=non-business
day, 9=defined month
Relative-Repeat
repvalue
n,
number of units before repeat
Relative-after last
repbase
n,
0=from start, 1=from end, 2=from schedule
Use agent group
group
“xx...xx”,
execute by agent machine in this group
Priority
priority
n,
0=high,9=low
Job Status
status
n,
0=pending,1=started, 2=on hold,
3=completed
Execute by Agent 1
agent
“xx...xx”,
agent to execute
Submitted By
username
“xx...xx”,
user who submitted job
Operating System
osreq
n,
operating system required 0=Other,
1=Any, 2=WinNT/2000/XP/2003, 3=UnixWare,
4=NetWare, 5=Win95/98/ME, 6=Linux, 7=AIX,
8=HPUX, 9=Solaris,10=OS/400, 11=Tru64,
12=IRIX
Job Comments
comment
“xx...xx”,
misc comments
Depends On Job 1
execafter
n,
job number to execute after
Job Title
title
“xx...xx”,
description of job
Minimum Disk Space
mindiskspace
n,
minimum megabytes of disk required
Return Value 1
maxretvalue
n,
max ret value for execafter
Times To Execute
totaltimes
n,
total times to repeat 0=infinite
Remaining Times
remainingtimes n,
remaining times to execute
Enable cmd line Substi substcmd
n,
substitute command line 0=no, 1=yes
File(s) To Check
filespec
“xx...xx”,
execute if this file exists
Execute
fileexist
n,
0=when none of the files exist,
1=when any of the files exist,
2=when a file exists and can be opened
sharable, 3=when a file exists and can
be opened exclusive, 4=when all files
exist, 5=when all files can be opened
sharable, 6=when all files can be opened
exclusive
Job Delay 1
timeafterjob
“hh:mm:ss”,
time after execafter job finishes
Job Class
class
“xx...xx”,
maps to vacation file
Using The
relaabso
n,
0=relative repetition, 1=absolute
repetition, 2=day of the week,
3=special
Absolute-Repeat on Day nth
n,
number of variable units
Absolute-Repeat on Day daytype
n,
0=days, 1=business days, 2=non-business
days, 3=weeks, 4=months, 5=sundays,
6=mondays, 7=tuesdays, 8=wednesdays,
9=thursdays,10=fridays, 11=saturdays
Absolute-Repeat on day begend
n,
0=after beginning, 1=before end, 2=on or
after beginning, 3=on or before end
Absolute-the
period
n,
0=week,1=month,2=defined month,
3=quarter,4=half,5=year
Operating Sys Version osver
n.nn,
the minimum operating system version
Keystrokes 1
keys
“xx...xx”,
1st set of keys to shove into the
Depends On Job 2
exaft02
n,
run job after
keyboard buffer
17-16
File Glossary
Depends On Job 3
exaft03
n,
run job after
Depends On Job 4
exaft04
n,
run job after
Depends On Job 5
exaft05
n,
run job after
Depends On Job 6
exaft06
n,
run job after
Depends On Job 7
exaft07
n,
run job after
Depends On Job 8
exaft08
n,
run job after
Depends On Job 9
exaft09
n,
run job after
Depends On Job 10
exaft10
n,
run job after
Return Code 2
exret02
n,
max ret value of job to run after
Return Code 3
exret03
n,
max ret value of job to run after
Return Code 4
exret04
n,
max ret value of job to run after
Return Code 5
exret05
n,
max ret value of job to run after
Return Code 6
exret06
n,
max ret value of job to run after
Return Code 7
exret07
n,
max ret value of job to run after
Return Code 8
exret08
n,
max ret value of job to run after
Return Code 9
exret09
n,
max ret value of job to run after
Return Code 10
exret10
n,
max ret value of job to run after
Job Delay 2
extim02
“hh:mm:ss”,
time after execafter job finishes
Job Delay 3
extim03
“hh:mm:ss”,
time after execafter job finishes
Job Delay 4
extim04
“hh:mm:ss”,
time after execafter job finishes
Job Delay 5
extim05
“hh:mm:ss”,
time after execafter job finishes
Job Delay 6
extim06
“hh:mm:ss”,
time after execafter job finishes
Job Delay 7
extim07
“hh:mm:ss”,
time after execafter job finishes
Job Delay 8
extim08
“hh:mm:ss”,
time after execafter job finishes
Job Delay 9
extim09
“hh:mm:ss”,
time after execafter job finishes
Job Delay 10
extim10
“hh:mm:ss”,
time after execafter job finishes
Retry on Error Code
retryafter
n,
retry job if it returns = this num -
Maximum Minutes
maxjobminutes
n,
maximum minutes job should be allowed
Minimum Notify Code
minnotifycode
n,
minimum return code to notify submitter
0=noretry
to run
of completion
Job (Status &) Type
exetype
n,
0=DOS, 1=Win31, 2=OS/2,
3=WinNT/2000/XP/2003,
4=NLM, 5=Win95/98/ME, 6=NT Console,
7=UnixWare, 8=Linux, 9=AIX, 10=HPUX,
11=Solaris, 12=OS/400, 13=Tru64,
14=IRIX
Show Activity
showactivity
n,
0=no,1=yes
Estimated Minutes
estjobminutes
n,
estimated minutes job should run
Keystrokes 2
keys2
“xx...xx”,
2nd set of keys to shove into the
keyboard buffer
Keystrokes 3
keys3
“xx...xx”,
3rd set of keys to shove into the
keyboard buffer
Keystrokes 4
keys4
“xx...xx”,
4th set of keys to shove into the
keyboard buffer
Submitted Date
subdate
“mm/dd/yyyy”,
date submitted
Submitted Time
subtime
“hh:mm:ss”
time submitted
Escalate for each x
escalmin
n,
escalate after minutes late
17-17
File Glossary
Reactive Job if this
failjob
“xx...xx”,
job to reactivate on failure
Keep When Complete
keepdone
n,
keep job when complete
Reactive Job if this
latejob
“xx...xx”,
job to reactivate if late
Execute
launchmode
n,
launch job in this mode
If this jobs ret code maxgoodret
n,
maximum good return code
If this job is more
maxminlate
n,
maximum minutes late
Execute Message
message
“xx...xx”,
pre job message
Operation On RetCode1 relate0
n,
0 <=, 1 <, 2 =, 3 >, 4 >=, 5 <>
Operation On RetCode2 relate1
n,
0 <=, 1 <, 2 =, 3 >, 4 >=, 5 <>
Operation On RetCode3 relate2
n,
0 <=, 1 <, 2 =, 3 >, 4 >=, 5 <>
Operation On RetCode4 relate3
n,
0 <=, 1 <, 2 =, 3 >, 4 >=, 5 <>
Operation On RetCode5 relate4
n,
0 <=, 1 <, 2 =, 3 >, 4 >=, 5 <>
Operation On RetCode6 relate5
n,
0 <=, 1 <, 2 =, 3 >, 4 >=, 5 <>
Operation On RetCode7 relate6
n,
0 <=, 1 <, 2 =, 3 >, 4 >=, 5 <>
Operation On RetCode8 relate7
n,
0 <=, 1 <, 2 =, 3 >, 4 >=, 5 <>
Operation On RetCode9 relate8
n,
0 <=, 1 <, 2 =, 3 >, 4 >=, 5 <>
Operation On RetCode10 relate9
n,
0 <=, 1 <, 2 =, 3 >, 4 >=, 5 <>
Resources 1
resource0
“xx...xx”,
required resource
Resources 2
resource1
“xx...xx”,
required resource
Resources 3
resource2
“xx...xx”,
required resource
Resources 4
resource3
“xx...xx”,
required resource
Resources 5
resource4
“xx...xx”,
required resource
Resources 6
resource5
“xx...xx”,
required resource
Resources 7
resource6
“xx...xx”,
required resource
Resources 8
resource7
“xx...xx”,
required resource
Resources 9
resource8
“xx...xx”,
required resource
Resources 10
resource9
“xx...xx”,
required resource
Execute By Agent 2
agent1
“xx...xx”,
run on agent
Execute By Agent 3
agent2
“xx...xx”,
run on agent
Execute By Agent 4
agent3
“xx...xx”,
run on agent
Execute By Agent 5
agent4
“xx...xx”,
run on agent
Execute By Agent 6
agent5
“xx...xx”,
run on agent
Execute By Agent 7
agent6
“xx...xx”,
run on agent
Execute By Agent 8
agent7
“xx...xx”,
run on agent
Execute By Agent 9
agent8
“xx...xx”,
run on agent
Execute By Agent 10
agent9
“xx...xx”,
run on agent
Weekly Schedule
sun
n,
run on sunday
Weekly Schedule
mon
n,
run on monday
Weekly Schedule
tue
n,
run on tuesday
Weekly Schedule
wed
n,
run on wednesday
Weekly Schedule
thu
n,
run on thursday
Weekly Schedule
fri
n,
run on friday
Weekly Schedule
sat
n,
run on saturday
With Calendar
caltype
“xx...xx”,
calendar type
Escalate this job’s
escalprior
n,
escalation priority
beenescal
n
has the jobs priority been escalated
CR/LF
0D0A
carrage return/linefeed
17-18
File Glossary
Completed Job Dump Data Files
Fixed Length Files
Each record has a fixed length of 2104 bytes (including the terminating CR/LF). Each field is a fixed length.
Numeric fields are right justified zero filled. Trailing spaces in text fields are included. Dates and times are in the
format of MM/DD/YYYY and HH:MM:SS respectively. The jobs are written to the file in job number order. Each
FIXED record has a fixed number of fixed length fields.
The file layout is :
Field
Offset
Len
Format
Notes
jobnum
0
10
xx...xx
job number
cmdline
10
128
xx...xx
command line to execute
path
138
128
xx...xx
To path to change to before
executing
begdate
266
10
mm/dd/yyyy
beginning date
begtime
276
8
hh:mm:ss
beginning time
enddate
284
10
mm/dd/yyyy
ending date
endtime
294
8
hh:mm:ss
ending time
nextdate
302
10
mm/dd/yyyy
next scheduled date
nexttime
312
8
hh:mm:ss
next scheduled time
agent
320
8
xx...xx
agent that ran job
priority
328
5
nnnnn
priority
retvalue
333
5
nnnnn
return code
username
338
48
xx...xx
user that submitted job
title
386
30
xx...xx
job title
schddate
416
10
mm/dd/yyyy
date rescheduled for
schdtime
426
8
hh:mm:ss
time rescheduled for
charge
434
15
nn...nn.nn
charge
set4retry
449
5
nnnnn
was job set for retry
newprob
454
5
nnnnn
is job an unviewed problem
CR/LF
459
2
0D0A
carrage return/linefeed
———
461
Comma Separated Files
Each field is separated with a comma (,). Text fields are enclosed in double quotes (“). If the text fields contain any
double quotes (”), they are changed to single quotes (‘). Trailing spaces in text fields are omitted. Dates and times
are also enclosed in double quotes and are in the format of “MM/DD/YYYY” and “HH:MM:SS” respectively.
Numeric fields are NOT enclosed in quotes. The jobs are written to the file in job number order. Each CSV record
has a fixed number of variable length fields. Each record is terminated with a CR/LF.
The file layout is :
Field
Format
Notes
jobnum
“text”,
batch.number-instance
cmdline
“text”,
command line
path
“text”,
command line changed to
17-19
File Glossary
begdate
“mm/dd/yyyy”,
beginning date
begtime
“hh:mm:ss”,
beginning time
enddate
“mm/dd/yyyy”,
ending date
endtime
“hh:mm:ss”,
ending time
nextdate
“mm/dd/yyyy”,
next scheduled date
nexttime
“hh:mm:ss”,
next scheduled time
agent
“text”,
agent that ran job
priority
n,
job priority
retvalue
n,
return code
username
“text”,
submitting user name
title
“text”,
job title
schddate
“mm/dd/yyyy”,
original scheduled date
schdtime
“hh:mm:ss”,
original scheduled time
charge
n.nn,
charge for job
setforretry
n,
was job set for retry (0=no,1=yes)
newproblem
n
is job an unviewed problem (0=no,1=yes)
CR/LF
0D0A
return/linefeed
17-20
Error Numbers
Error Numbers
18-1
Error Numbers
18-2
Error Numbers
Description of Errors
GECS displays error messages that typically describe the situation. Sometimes however, GECS will include an
error number in the message. The error numbers relate either to the database or the operating system. The database
related error numbers are displayed in the format:
Some sort of message. database error n.
where n is the database error number.
The operating system errors are displayed in the format:
Some sort of message. N-n.
where N is the first portion and n is the second portion.
Database Errors
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
56
80
81
82
83
84
85
86
87
88
90
91
92
93
94
97
98
Invalid operation
I/O error
No open
Key not found
Duplicates error
Invalid key number
Different key number
Invalid positioning
End of file
Modifiable error
Invalid file name
File not found
Extension error
Pre-open error
Pre-image error
Expansion error
Close error
Disk full
Unrecoverable error
Record manager inactive
Key buffer error
Record buffer
Position block
Page size
Create I/O error
Number of keys
Key position
Record length
Key length
Btrieve file name
Extend error
Extend I/O error
Extend Name
Directory error
Transaction error
18-3
Begin transaction
Transaction control file
End/abort error
Transaction maximum files
Transaction operation
Incomplete accelerated access
Invalid data record address
Null key path
Inconsistent key flags
Access denied
Maximum open files
Invalid alternate sequence definition
Key type error
Owner already set
Invalid owner
Error writing cache
Invalid interface
Variable page error
Incomplete index
Conflict
Lock error
Lost position
Read outside transaction
Record in use
File in use
File full
Handle full
Mode error
Device full
Server error
Transaction full
Incompatible lock type
Permission error
Data message too small
Internal transaction error
Error Numbers
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
234
235
236
237
238
239
240
241
242
243
244
245
246
XQLP is not loaded
Invalid function code
Invalid cursor ID
Invalid master password
Invalid file name
Invalid password
Maximum number of cursors has been exceeded
Invalid field
The position parameter value is out of range for
this function
Invalid user or group name
Buffer is not large enough to hold all of the data
Maximum record size has been exceeded
Maximum index size has been exceeded
Read access error
Cannot change field rights while file has alter
rights
Invalid lock flag
A join is not allowed on a view ordered by a
user-defined sort
A maximum of 8 files may be joined
A maximum of 24 index segments is allowed
No matching indexes on secondary keys
Invalid syntax for expression or restriction
Insufficient memory in XQLP
Invalid data type for expression
Invalid character in numeric data
The maximum number of fields for an ORDER
BY is 8
Rec. count specified exceeds # of records re
turned by last xFetch
Operand must be a dictionary field
Invalid data length in buffer
Field already exists in this file definition
Incomplete restriction statement
No fields are defined in the view
Field must be in the view
Cannot create external index file
Invalid option for an I/O operation
Cannot update a view with an external index
Index descriptor missing for supplemental index
Supplemental index does not exist
File in the view definition is not in current
dictionary
Field in the view definition is not in the current
dictionary
Cannot update a dictionary file
User does not have write access to this file
User does not have access to update a field
User does not have write access to all fields in
this file
Data dictionary file may not be deleted
User does not have file definition or change
rights
18-4
247 User does not have access for all of the
fields specified
248 Invalid size
249 Incompatible field types
250 Cannot recall view
252 X$View is not open
254 Cannot create VIEW dictionary file
255 Field is not an index
256 Relation must specify at least one file
257 Dictionary filename has been previously
defined
258 Error updating dictionary file definition
259 Error inserting new dictionary file
definition
260 Error updating X$Rights file
261 A variable data type field must be last field
in a view or file def.
262 A variable data type field may not be
defined as an index
263 A view may not be sorted by a variable
data type field
264 Cannot modify or remove the master user
265 Invalid session identified
266 Only one session can be active at a time
267 Only one dictionary can be open at a time
269 Cannot create X$User dictionary file
270 Cannot open X$User dictionary file
271 Cannot create x$Rights dictionary file
272 Cannot open X$Rights dictionary file
273 Cannot read or update X$User dictionary
file
274 Unable to assign owner name to physical
file
275 Duplicate Name for Group or User
276 User is not the master user
277 Invalid access rights code
278 Invalid option
279 Invalid mask
281 Attribute is not in the dictionary
282 Invalid character in data
283 Invalid range value
284 Specified value is not in list of valid values
285 Error opening data dictionary file
286 Attempt to turn off/on security when
security is already off/on
287 Data dictionary is not assigned
288 Data dictionary is in use
290 Data dictionary already exists
291 Data dictionary does not exist in the
specified directory
292 Invalid month number
293 Invalid day of month
294 Invalid time range
295 Invalid open code
Error Numbers
296 Error opening data file for BTRIEVE STAT
function call
297 Field may not be deleted from view
298 Mismatched Quotes
299 Invalid join index for ‘file:n.field’
300 Missing operator for conditional, expected’::’
301 No restriction has been defined
302 Not a computed field
303 Cannot update current sort index if more than one
file is in the view
304 Cannot change another user’s password
305 View name not found in dictionary
306 Error occurred while storing view definition
307 The computed field specified for the join is not in
the view
308 I/O error
309 Valid owner access codes are 0, 1, 2, and 3
310 User does not have access for all of the files
specified
311 Transaction processing has not been activated
312 Transaction aborted
313 Transaction already started
314 Transaction cannot be initiated-file recovery
required
315 Cannot change dictionary or data path within a
transaction
316 You cannot remove Btrieve from memory while
XQL is loaded
317 Dictionary is locked by another user within a
transaction
318 Cannot update view that includes files opened in
READONLY mode
319 Value list definition error
320 Character list definition error
321 Default value definition error
322 Range list definition error
323 Cannot remove a file definition for a file in the
view
324 Unmatched parentheses
325 Record length error
326 Stack overflow
327 Null key error
328 Invalid syntax for date/time arithmetic
329 Invalid number of decimal places
330 Invalid data format
331 Invalid operation performed on security group
332 Dictionary files have not been converted to
version 2.xx
333 Error storing index definitions
334 Supplemental index name already exists
335 Invalid join option
336 Conversion error
401 Please log in first
402 Error opening file that contains the SQL
statement
403 Error recalling stored SQL statement
18-5
404
405
406
407
408
409
410
411
412
413
414
415
416
417
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
Unable to store SQL statement
File already exists
No files found to Store, Recall or Delete
Invalid filename
Error writing output
Please ENTER an SQL statement first
Unable to SAVE configuration
Unable to open dictionary files
Insufficient memory
Out of DOS file handles
Maximum width for XQLI data window is
1,024 bytes
Maximum page length exceeded
Maximum page width exceeded
Invalid dimensions for editing window
Invalid keyword
Invalid SELECT statement
Invalid function code
Invalid OPEN mode
Each item in the attribute list must be
enclosed in quotation marks
Invalid INSERT statement
Invalid UPDATE statement
Invalid DELETE statement
Invalid SET statement
Can only create a TABLE, VIEW,
INDEX, DICTIONARY, or GROUP
Index name is missing
Invalid GRANT statement
Username missing on GRANT/REVOKE
Table name is missing
TABLE keyword should follow ALTER
ADD, MODIFY, or DROP keyword
expected
The FROM clause is missing
Sort order follows field name
AS expected
BY expected
You must supply a view name for the
CREATE VIEW statement
Unknown keyword
GRANT/REVOKE option is missing
Field list is allowed only on SELECT or
UPDATE
Password must be specified for SET
SECURITY
Name cannot be a reserved word
Missing user password
Must provide a character after the equal
sign
Must supply one or more owner names
after the equal sign
Must supply a dictionary path after the
equal sign
Must supply a data file path after the equal
sign
Error Numbers
532 Missing ‘=’
533 Invalid data type specified
534 SELECT keyword expected when creating a
view
535 Index attribute expected
536 Dictionary field name expected
537 Field name already exists in this definition
538 Index name is not in the field list
539 Index is already defined in this definition
540 Field list expected after SELECT, ORDER
BY, or GROUP BY
541 Restrict text expected after WHERE or
HAVING
542 DICTIONARY, INDEX, TABLE, VIEW, or
GROUP keyword expected
543 Mismatched quotation marks
544 Directory path must be specified
545 INTO keyword expected
546 Maximum string size is 255 bytes
547 Attribute list is missing
548 Invalid syntax: WORK or TRANSACTION
keyword expected
549 ORDER BY clause must be specified last
550 Alias name has already been defined
551 Invalid characters for dictionary name
552 Missing SELECT clause
553 Field name too long
554 Security group name expected
555 Expected IN DICTIONARY clause
800 Insufficient memory in XQLM
801 Maximum number of cursors has been
exceeded
802 XQL Manager is not active
803 User must log in first
804 Invalid position
805 Invalid size
806 Invalid number of decimal places
807 Invalid variable
808 Unresolved variables
809 Field in statement is not in the recalled view
810 Invalid number
811 Invalid month
812 Invalid day of month
813 Invalid time range
815 Invalid join field
816 Field name is not defined in this table
818 Field in view must be a group aggregate or in
GROUP BY list
819 Invalid table name
820 Comparison operator expected in HAVING
clause
821 Invalid cursor ID
822 Data buffer is too small
823 ORDER BY index must be in the view list
824 Missing or unbalanced parentheses
825 Cannot do AVG or SUM on STRING, DATE,
or TIME data types
826 Missing or unbalanced parentheses following
WHERE clause
827 GROUP BY field must be in the view list
828 WHERE clause must be specified last
829 Invalid syntax for computed field
830 Operand expected
831 Operand in HAVING clause must be a group
aggregate or constant
832 Stored view buffer is inconsistent-cannot be re
called
833 Field must be in the view list
835 Invalid option for XQLStat
836 Invalid mask
837 Invalid delimiter
838 Number of fields in all view lists must match
839 Type or size mismatch in corresponding fields
840 Stack overflow
841 Unable to create temporary file
842 Subquery in HAVING clause
843 DOS path not specified
845 Field/Heading mismatch
846 Unspecified field name
847 Invalid syntax in WHERE clause
848 Multiple DISTINCT keywords
849 Insufficient buffer space for WHERE clause
850 Data value cannot be converted to new data
type
851 SELECT statement may not access the same
files as INSERT or UPDATE
852 Record count must be greater than zero
853 Access denied
854 No index defined
855 Data conversion requires two views
856 Invalid number of values on INSERT
2001 Insufficient memory in OS/2
2002 Incorrect parameter in OS/2
2101 Data message buffer is too small
2102 Redirection buffer is too small
2103 NW$SQL is not active on the requested
server
2104 Only one dictionary may be open at a time
2105 Server buffer is too small
2106 NW$SQL data message buffer too small
2107 Maximum number of active views has been
exceeded
2108 Device is not assigned to a file server
2109 Too many file servers attached
18-6
Error Numbers
10002
10003
10004
10005
10006
10007
10008
10009
10010
10011
10012
10013
10014
10015
10016
10017
10018
10019
10020
10021
10022
10023
10024
10025
10026
10027
10028
10029
10030
10031
10032
10033
10034
10035
10036
10037
10038
10039
10040
10041
10042
10043
10044
10045
10046
10047
10048
10049
Key value already exists
Could not delete since pntr’s don’t match
Could not find key to delete
Cannot call delete w/o verification with
duplicate keys
c-tree(...) jump table error
Terminate user
sysiocod value when FNOP_ERR caused by
conflicting open requests (server)
sysiocod value when FNOP_ERR,
DCRAT_ERR or KCRAT_ERR caused by
device access error
INTREE parameters require too much space
Bad INTREE parameters
Could not open file: not there or locked
Unknown file type
File corrupt at open
File has been compacted
Could not create index file
Could not create data file
Tried to create existing index file
Tried to create existing data file
Key length too large for node size
Record length too small
File number out of range
Illegal index member info
Could not close file
Bad link in deleted node list. REBUILD
File number not active
drn before beginning of data records
Zero drn in ADDKEY
Zero drn in data file routine
drn exceeds logical end of file
Flag not set on record in delete chain
Attempt to delete record twice in a row
Attempt to use NULL ptr in read/write
Predecessor repeat attempts exhausted
Seek error: check sysiocod value
Read error: check sysiocod error
Write error: check sysiocod error
Could not convert virtual open to actual
No more records availble
Index node size too large
Could not unlock data record
Could not obtain data record lock
Version incompatibility
Data file serial number overflow
Key length exceeds MAXLEN parameter
File number already in use
c-tree has not been initialized
Operation incompatible with type of file
Could not save file
10050 Could not lock node
10051 Could not unlock node
10052 Variable length keys disabled OR invalid key
type
10053 File mode inconsistent with c-tree config
10054 Attempt to write a read only file
10055 File deletion failed
10056 File must be opened exclusive for delete
10057 Proper lock is not held
(CHECKLOCK/READ)
10058 LOADKEY called with incorrect key number.
You cannot continue
10059 LOADKEY called with key out of order You
may skip this key & continue
10060 Percent out of range
10061 NULL fcb detected during I/O
10062 File must be opened exclusively
10063 Start file / log file serial number error
10064 Checkpoint past end of log file
10065 Not enough memory during tran processing
10066 Log file entry failed to find checkpoint
10067 Could not rename file
10068 Could not allocate memory for control list
10069 Node does not belong to index
10070 Transaction already pending
10071 No active transaction
10072 No space for shadow buffer
10073 LOGFIL encountered during shadow only
10074 Recovery: two active tran for user
10075 Recovery: bad tran owner
10076 Recovery: bad tran type
10077 Recovery: file name too long
10078 Transaction abandoned: too many log extents
or dynamic dump wait exhausted
10079 Could not log file opn/cre/cls/del
10080 NULL target or bad keyno
10081 Transaction allocation error
10082 User allocation error
10083 ISAM allocation error
10084 Maximum users exceeded
10085 Reduce lock to read lock after update
10086 Dead lock detected
10087 System not quiet: files in use
10088 Linked list memory allocation error
10089 Memory allocation during tran processing
10090 Could not create queue
10091 Queue write error
10092 Queue memory error during write
10093 Queue read error
10094 Pending error: cannot save or commit tran
10095 Could not start task
10096 Start-file/log open error
18-7
Error Numbers
10097
10098
10099
10100
10101
10102
10103
10122
10123
10124
10125
10126
10127
10128
10129
10130
10131
10132
10133
10134
10135
Bad user handle
Bad transaction mode
Transaction type / filmod conflict
No current record for isam datno
Could not find isam keyno request
Could not open ISAM parameter file
Could not read first 5 parameters in ISAM
parameter file
Too many files in ISAM parameter file
Could noy undo ISAM update. Rebuild Files
Could not read data file record in ISAM
parameter file
Too many keys for data file in ISAM
parameter file
Incorrect keyno for index member in
parameter file
Too many key segments defined in ISAM
parameter file
Could not read segment record in ISAM
parameter file
Could not read index file record in ISAM
parameter file
LKISAM(ENABLE) found pending locks
No memory for user lock table
1st byte of data record equals delete flag or
bad variable length record mark
Key segments do not match key length
Bad mode parameter
Could not read index member record
NXTSET called before FRSSET for keyno
FRSSET called for index with wrong keytyp
Data record length exceeds rebuild max
Tried to update data with
ctISAMKBUFhdr on
Attempt to change fixed vs variable len
Var length header has bad record mark
# of indices does not match (OPNIFIL)
c-tree already initialized
Bad directory path get
Could not send request
Could not receive answer
c-tree not initialized
Null file name pointer in OPNFIL
File name length exceeds msg size
No room for application message buffer
Server is not active
Could not get servers message id
Could not allocate application id
10136
10137
10138
10139
10140
10141
10142
Could not get application msg status
Could not set message appl msg size
Could not get rid of application msg
Badly formed file name
Variable record length too long
Required message size exceeds maximum
Application MAXLEN > server’s MAXLEN
10104
10105
10106
10107
10108
10109
10110
10111
10112
10113
10114
10115
10116
10117
10118
10119
10120
10121
10143
10144
10145
10146
10147
10148
10149
10150
10151
10152
10153
10154
10155
10156
10158
10159
10160
10161
10162
10163
10164
Communications handler not installed
Application could not id output queue
Could not find COMM software
Could not update free space info
Space to be reused is not marked deleted
WRTVREC cannot fit record at recbyt
Varlen less than minimum in ADDVREC
Server is shutting down
Could not shut down. transactions pending
Could not extend logfile
Buffer too small
Zero length record in REDVREC
Native system failure
Timeout error
REDVREC record not marked active
Zero recbyt value
Multi-user interference: index information
updated by the time user got to actual data
record
User appears inactive
Server has gone away
No more room in server lock table
File number out of range
10165
10166
10167
10168
10169
10170
10171
10172
10173
10174
10175
10176
10177
10178
10179
10180
10181
10182
10183
10184
10185
10186
10187
10188
10189
10190
10191
10192
10193
10194
10195
No file control block available
No more ct file control blocks in server
Could not read request
Could not send answer
Create file already opened (in recovery)
Bad function number
Application msg size exceeds server size
Could not allocate server msg buffer
Could not identify server
Could not get server message id
Server could not allocate user msg area
Could not get server msg status
Could not set message server msg size
Unexpected file# assigned to [si] in rcv
Server is at full user capacity
Could not read symbolic key name
Could not get mem for key symb name
No room for sort key. increase MAXFIL
Could not read file field number values
Attempt to reallocate set space
Not enough memory for addt’l sets-batches
Set number out of range
Null buffer in rtread.c
Null target buffer in rtread.c
Join_to skip
Join_to error
Join_to null fill
Detail_for skip
Detail_for error
Detail_for null fill
Could not get mem for dat symb name
18-8
Error Numbers
10196
10197
10198
10199
10370
10400
10401
10402
10403
10404
10405
10406
10407
10408
10409
10410
10411
10412
10413
10414
10415
10416
10417
10418
10419
10420
10421
10422
10423
10424
10425
10426
10427
10428
10429
10430
10431
10432
10433
10434
10435
10436
10437
10438
10439
10440
10441
10442
10443
10444
10445
10446
Exceeded RETRY_LIMIT in RTREAD.C
Could net get memory for ifil block
Improper ifil block
Schema not defined for data file
Sort base: errors SORT_ERR + 101 thru
126 see CTSORT.C or CTERRC.H for
error listing
Resource already enabled
Resources not enabled
File must be exclusive to enable res
Empty resource id
Output buffer to small
Resource id already added
Bad resource search mode
Attempt to get non-resource info
Resource not found
Not in use: available
User not active
Not a superfile
WRL to WXL commit promote pending(CIL)
Superfile host not opened
Cannot nest superfiles
Illegal ADDKEY to superfile
Illegal DELBLD to superfile
Cache page size error
Max name inconsistency
Host superfile does not support recovery
Key update with pending transaction
Filter not supported yet
Other functions not sup
Incomplete
Add list err
Batch in progress
No batch active
Status info already returned
No more info, batch cancelled
Bufsiz too small for record
Request is empty or inconsistent
Aggregate/serialization lock denied
Fixed length string requires len in DODA
Segment def inconsistent with schema
Very long def block not supported
File def memory error
Bad def number
defptr NULL during GETDEFBLK
Requested def blk is empty
No conversion routine for Definition Block
Dynamic dump already in progress
No memory for dynamic dump file buffer
One or more files not available for dump
File length discrepancy
Could not create file during dump rcv
Not enough data to assemble key value
Bad key segment mode
10447
10448
10449
10450
10451
10452
10453
10454
10455
10456
10457
10458
10459
10460
10461
10462
10463
10464
10465
10466
10467
10468
10469
10470
10471
10472
10473
10474
10475
10476
10477
10478
10479
10480
10481
10482
10483
10484
10485
10486
10487
10488
10489
10490
10491
10492
10493
10494
10495
10496
10498
10499
18-9
Only the file’s owner can perform op
Permission to set file definition denied
ADMIN has opened file. Cannot delete file
Invalid user id
Invalid password
Server could not process user/acct info
No such server
Service not supported
User does not belong to group
Group access denied
File password invalid
Write permission not granted
File delete permission denied
Resource not enabled
Bad permission flag
No directory found in superfile
File id uniqueness error
ISAM level logon not performed
Incremental Index: dnumidx < 1
Incremental Index: dfilno not a ISAM file
Incremental Index: aidxnam NULL for 1st
Incremental Index: active tran not allowed
Negative I/O request
Guest logons disabled
Error deleting sortwork file
Error creating unique name
Error opening first dummy file
Too few handles available min 3
Error closing dummy file
Error unlinking dummy file
Error getting first data area
Sinit phase not previously performed-srelease
Sreturn phase already started
No records in data buffers
Sint phase not previously performed-sreturn
Not enough memory
No valid record pointers in merge buffers
Error opening sortwork file
Error creating sortwork.00x file
No records fit in output buffer
Nrror reading sortwork file
Bytes in buf merge buf size
Error adjusting file pointer
Error closing sortwork.00x
Error closing sortwork file
Error deleting sortwork file
Error renaming sortwork.00x
Error closing output file
Error creating output file
Insufficient disk space
Old log file found during log create
Mismatch between recv log & file id
Error Numbers
10500
10501
10502
10503
10504
10505
10506
10507
10508
10509
10510
10511
10512
10513
10514
10515
10516
10517
10518
10519
10520
10521
10522
10527
10528
10529
10530
10531
10532
10533
10534
10535
10536
10538
10539
10540
10541
10542
10543
10544
10545
10546
10547
10548
10549
10550
10551
10555
Server could not init SQL engine
Could not init SQL for a user
Could not access SQL master info
Could not continue SQL request
Server does not support SQL
User profile does not enable SQL
Could open save-restore file
Could not process save-restore file
Save restore inconsistency
Duplicate server
Active chkpnt at start of roll-forward
Index nodes form illegal loop: rebuild
Data file loop detected
FPUTFGET does not support CTSBLDX ()
Queue has been closed
Cannot convert old IFIL structure
ctNOGLOBALS not allocated
‘regid’ is not registered
‘regid’ is already registered
Index logical EOF error
Attempt to update index with inconsistent
tran#
Could not allocate memory for the streettalk
login message buffer
Userid in INTISAM does not match current
login id
Index must be rebuilt:see CTSTATUS.FCS
Key segment length error
System checkpoints terminated
Client does not match server
Index reorg entry error
TRANSAV called with AUTOSAVE on
File header high-water-mark overflow
Yransaction # overflow
ctree not registered. Call REGCTREE
Only automatic REGCTREEs allowed
Client-side bad function array type
sysiocod when file does not appear to contain
any valid information
Null parameter
Transaction log cannot be written
Could not create mirror file
Could not open mirror file
Could not close mirror file
Could not delete mirror file
Could not write to mirror file
Could not save mirror file
Could not read from mirror
Mismatch between mirror headers
Attempt to open primary w/o mirror: or’ing in
a file mode of MIRROR_SKP permits a
primary to be opened w/o error
File already opened without mirror
Could not read primary, switching
10556
10557
10558
10559
10560
10561
10562
10563
10570
10571
10572
10573
10574
10575
10576
10587
10588
10589
10590
10591
10592
10595
10596
10597
10598
10600
10601
10602
10603
10604
10605
10606
10607
10608
10610
10611
10612
10613
10614
10615
10616
10617
10618
10619
10620
10621
10622
18-10
Could not write primary, switching
Could not write mirror,suspend mir
Could not save primary, switching
Could not save mirror, suspend mir
Only one of each monitor at a time
SYSMON: dynamic dump begins
SYSMON: dynamic dump ends
SYSMON: dynamic dump ends (errors)
Incomplete compression
Index rebuild required
Incomplete compression & index re-build
required
Primary\mirror out-of-sync. Copy good
file over bad.
Incomplete compression & primary mirror
out-of-sync
Index rebuild required & primary mirror
out-of-sync
Incomplete compression & index re-build
required & primary\mirror out-of-sync
Close/delete deferred: pending tran
Attempt to close or delete file with
pending tran
Member of ADMIN group required
Could not find ISAM context ID
Old context ID. Call CLSICON()
Context ID exists
Varlen too small in PUTCRES
Missing information
Could not initialize expression
Could not evalutate condtional exp
No more client threads
ctVERIFY detected problems with idx
No memory for system lock table
Could not allocate FCB
Could not increase user files
Records with bad (all FF) serial #s
Could not handle file encoding
Recovery could not enable encoding
IIDX attributes do not match file
CTHIST target==NULL
CTHIST could not access log
CTHIST must be called with ctHISTfirst
CTHIST can only access data or index
No valid ISAM map from index to data
Cannot get index info from data filno
CTHIST cannot be called during a tran
Did not find target
Log scan terminated: EOF or bad entry
CTHIST on data file: recbyt==0
Bufsiz too small
Transaction type not expected
Must reset CTHIST first position
Error Numbers
10623 Not enough memory for CTHIST
10624 Net change only applies to specific match of key
or record
10625 Must specify exactly one matching criteria (user
& node may be combined)
10626 Encountered an UNDTRAN going forward:
must completely restart this CTHIST sequence
10627 Unknown type of request
10628 Must specify filno
10629 Could not initialize internal file ID
10630 Unexpected length in log entry
10633 Null plen (pointer to size)
10634 Negative length specified
10635 Could not create thread sync object
10636 Thread sync object ‘get’ failed
10637 Thread sync object ‘rel’ failed
10638 Queue message truncated to fit
10639 Semaphore must be init with count>0
10640 Semaphore already initialized
10641 Thread sync object ‘cls’ failed
10649 .. reserved ...
10650
10651
10652
10653
10654
10655
10656
10657
10658
10659
10660
10661
10662
10663
10664
10665
20001
Duplicate keys purged and logged
Could not process dup key log
Duplicate keys rejected and listed
Attempt to exceed mapped lock limit
Record length too long for log size
Could not reopen using freopen
Transaction log header is bad
Could not create copy file
Could not write copy file
Could not read entire original file
Rbld complete, but failed mirror copy
Failed process dup log and copy mirror
Dup purged, but could not copy mirror
Dup rejected, but could not copy mirror
Primary log (or start) file failed
Mirrored log (or start) file failed
Unable to communicate with backup
dbms
20002 Backup packet sent to primary dbms
MAPI Error Codes
0
1
2
3
4
5
6
SUCCESS_SUCCESS
USER ABORT
FAILURE
LOGIN FAILURE
DISK FULL
INSUFFICIENT MEMORY
ACCESS DENIED
8 TOO MANY SESSIONS
9 TOO MANY FILES
10 TOO MANY RECIPIENTS
11 ATTACHMENT NOT FOUND
12 ATTACHMENT OPEN FAILURE
13
14
15
16
17
18
19
ATTACHMENT WRITE FAILURE
UNKNOWN RECIPIENT
BAD RECIPTYPE
NO MESSAGES
INVALID MESSAGE
TEXT TOO LARGE
INVALID SESSION
20 TYPE NOT SUPPORTED
21 AMBIGUOUS RECIPIENT
18-11
Error Numbers
VIM Error Numbers
14 NAME EXISTS
15 NAME NOT FOUND
16 NOT SUPPORTED
17 NO COMMON CERTIFICATES
18 NO DEFAULT
19 NO MATCH
20 NO SIGNATURE
21 NO SUCH ATTRIBUTE
22 OPEN FAILURE
23 PASS REQUIRED
24 READ FAILURE
25 UNSUPPORTED TYPE
26 UNSUPPORTED VERSION
27 WRITE FAILURE
0 SUCCESS
1 FAILURE
2 FATAL
3 ALL PARAMS REQUIRED
4 ATTACHMENT NOT FOUND
5 BAD PARAM
6 BUFFER TOO SMALL
7 CONVERSION NOT SUPPORTED
8 INSUFFICIENT MEMORY
9 INVALID CONFIGURATION
10 INVALID OBJECT
11 INVALID PASSWORD
12 INVALID SELECTOR
13 INVALID SIGNATURE
WinExec Errors
When a Windows Agent experiences a problem attempting to launch a job, they will display the WinExec() error
number that relates to the problem as follows:
0
System was out of memory, executable
file was corrupt, or relocations were
invalid.
14 Type of executable file was unknown.
2
File was not found.
15 Attempt was made to load a real-mode
application (developed for an earlier version
of Windows).
3
Path was not found.
5
Attempt was made to dynamically link
to a task, or there was a sharing or
network protection error.
6
Library required separate data segments
for each task.
8
There was insufficient memory to start
the application.
16 Attempt was made to load a second instance
of an executable file containing multiple data
segments that were not marked read-only.
19 Attempt was made to load a compressed
executable file. The file must be decompressed
before it can be loaded.
20 Dynamic-link library (DLL) file was invalid.
One of the DLLs required to run this
application was corrupt.
10 Windows version was incorrect.
11 Executable file was invalid. Either it
was not a Windows application or there
was an error in the .EXE image.
21 Application requires Microsoft Windows 32bit extensions.
12 Application was designed for a different
operating system.
13 Application was designed for MS-DOS 4.0.
18-12
Global ECS System Configuration Worksheet
Global ECS System
Configuration Worksheet
19-1
Global ECS System Configuration Worksheet
19-2
Global ECS System Configuration Worksheet
Global ECS Configuration Worksheet
It is important to keep track of the computer names and IP Addresses of each component being used in your Global
ECS job scheduling system. This configuration can be very simple or very complex. The following worksheet can
be used to help organize the computers that make up your Global ECS System.
Smaller installations may not need to use every cell in this worksheet where larger systems may need to create
copies of this worksheet to include more agents. A sample configuration is displayed below.
GECS
Component Operating
Component
Name
System
IP Address (Name)
IP Port
Http
Port
DBMS
DBMS
Windows
123.123.123.123
2002
2012
Controller
CONTROL
Windows
123.123.123.123
2001
2011
Web
Manager
WEBMGR
Windows
123.123.123.123
2003
2013
Agent
(I)
WILBER
AIX
123.123.123.1
2000
2010
Agent
(II)
LINDA
Linux
123.123.123.2
2000
2010
Agent
(III)
SETH
Solaris
123.123.123.3
2000
2010
Agent
(IV)
LISA
Windows
123.123.123.4
2000
2010
Agent
(V)
PETE
Tru64
123.123.123.5
2000
2010
The chart on the following page can be photo copied and used for your GECS System configuration.
19-3
Global ECS System Configuration Worksheet
GECS
Component
Compone
nt Name
Operating
System
DBMS
DBMS
Controller
Web Manager
IP Port
Http
Port
Windows
2002
2012
CONTROL
Windows
2001
2011
WEBMGR
Windows
2003
2013
2000
2010
IP Address (Name)
Agent
Agent
Agent
Agent
Agent
Agent
Agent
Agent
Agent
Agent
Agent
Agent
Agent
Agent
Agent
Agent
Agent
Agent
Agent
Agent
Agent
Agent
Agent
Agent
Agent
19-4
Global ECS System Configuration Worksheet
Port Default Values
Component
IP Port
Http Port
Controller
2001
2011
DBMS
2002
2012
Web Manager
2003
2013
Agents
2000
2010
19-5
Global ECS System Configuration Worksheet
19-6
Index
Index
20-1
Index
20-2
Index
Index
Absolute Scheduling
5-4
Activate Job due to Bad Return Code
7-10
Active Job due to Late Start Time
7-8
Adding Dependent Jobs Via WRK Files
4-37
Agent Characteristics
9-13
Agent Group names
9-13
AIX command line type jobs
4-8
Automating programs
4-40
Batch and Command Files
4-6
Batch Jobs that Repeat
8-13
Batch Variables
3-5
Batch Variables Screen
8-15
BATCHVAR
17-10
Bindery Emulation
15-14
Business Days & Non-Business Days
3-7
Calendar Date Range
8-33
Calendars
3-6
Can’t Do Program
13-8
Caption Text
4-23
Caption Text for Keystroke Stuffing
4-6
Capturing Return Codes from Executables
4-27
cc:Mail
4-39
cc:Mail (VIM)
2-5
cc:Mail Issues
6-11
Certificate Management
16-4
Changes Due To Fall Daylight Savings Time
15-12
Changes Due To Spring Daylight Saving Time
15-12
Changes Due To Synchronization
15-12
Changing the Sentry WAV Files
15-13
Charge Users for Jobs
10-8
Checking Job Schedules
5-6
Client Programs Overview
8-3
CMD.EXE on Windows Agents
4-8
Comma Separated Files
17-15,
Command Line Overview
4-5
Command Line Parameters
4-7
20-3
17-19
Index
Command Line Types
4-7
COMMAND.COM
4-8
Comments about this Agent
9-13
Completed Job Dump Data Files
17-19
Configuring Sentry for Sound
15-13
Controller Status
10-5
Controller WRK File Defaults
10-11
Copy Calendar
8-34
Copying into Batches
8-20
Database Errors
18-3
Day Of the Week Scheduling
5-5
Days of Events to Keep
11-5
DBMS Status
11-5
Defined Months
8-31
Defining Calendars
5-6
DEFMONTH
17-10
Delete Jobs On Completion
10-7
Description of Agent
9-11
Description of Errors
18-3
Differences When Run As A Service
9-17
Documentation
2-4
DOS Jobs
4-32
DOS Keystroke Stuffing Programs
4-19
Dynamic Scheduling
5-3
effective date
5-6
Enable Command Line Substitution
4-11
Environment Variables
4-7
Escalate Priority due to Late Start
7-9
Estimated Minutes
7-8
Event Network Messaging
15-15
Events
3-6
EVENTS
17-10
Executable Programs and Shell Scripts
4-6
Execute - job start mode
4-18
Execute if
5-10
Exit Filespec
10-10
expiration date
5-6
File Change Utility
5-10
20-4
Index
File Glossary
17-3
File Size Change Utility
5-11
Fixed Length Files
17-12,
GECS Data Files
17-3
GECS Licensing
3-8
GECS Licensing Restrictions
15-13
GECS Program Files
17-5
GECS Service Installation
9-18,
GECS Service Program
9-18
GECS Service Removal
9-18,
GECS.INI
17-11
Halt Filespec
10-9
How Do Batches Work?
8-11
How Will I Use Batches?
8-11
HPUX command line type jobs
4-8
Ignore User Names
9-12
Internet mail
4-39
Internet Mail (SMTP/POP3)
2-5
IP Address
9-3
Job Class
5-8
Job Delay
5-11
Job Dependencies
5-11
Job Dump Data Files
17-12
Job Lateness
7-8
Job Priority
5-13
Job Schedule Lookups
5-6
Job Scheduling
5-4
Job Scheduling Day Types
5-6
Job Status
4-10
Job Title
4-10
Job Trigger Utility
13-20
Job Types
9-13
jobnum.EL
4-26
Jobs That Repeat
5-3
Keep When Complete
4-18
Keystroke Stuffing
4-19
Keyword & Keystroke
4-21
KS.EXE
4-20
20-5
17-19
10-15
10-15
Index
KSLOAD.COM
4-20
LAN Server Version
2-4
Linux command line type jobs
4-8
Login As Submitting User
9-12
Long File Names on Windows Agents
4-6
Lotus Notes mail
4-39
Lotus Notes Mail
2-5
Mail Password
10-12
Mail Subdirectory
10-13,
11-7
Mail System
10-12,
11-6
Mail User Name
10-12,
11-6
MAPI Error Codes
18-5
Mark Jobs Complete Once Started
4-17
Maximum Good Return Code
7-9
Maximum Jobs of a Class
9-11
Maximum Minutes
7-8
Maximum Minutes Per Job
9-12
MHS Mail
2-4
Microsoft mail
4-39
Microsoft Network Version
2-4
Microsoft vs. Novell Drivers
15-14
Microsoft/LAN Server Issues
15-14
Minimizing the Effects Of Daylight Savings Time Changes
15-13
Minimum File Size
5-10
Minutes Between Job Retries
9-12
Monitoring the GECS System
6-3,
MS Mail (MAPI)
2-5
MS Mail and MS Exchange Issues
6-11
Naming and Numbering Schemes
3-11
NetWare Network Version
2-4
Never Late
4-18
Next Run Time
4-9
NLM command line type jobs
4-8
No Network Version
2-4
No Networking Issues
15-15
Non Business Days
8-31
Notify On Errors
11-8
Notifying Users Via cc:Mail
6-9
20-6
7-3
Index
Notifying Users via Lotus Notes Mail
6-10
Notifying Users via MHS
6-10
Notifying Users Via MS Mail or Exchange
6-9
Novell MHS mail
4-39
NT Console command line type jobs
4-8
Operating System
9-13
Operating System Errors
18-5
Operating System Version
9-13
Other Files Created
17-9
Other Required/Optional Files
17-9
Overview of Data File Structure
17-10
Pause At / Unpause At
10-10
Pause Controller from NT Service Manager
10-16
Pause Filespec
10-10
Port
9-11
POSTCMD.TXT
17-11
Pre & Post Job Command Files
4-8
Predecessor Job Parameters
5-11
Process Jobs
9-11
Programs That Require User Input
4-18
Pulse File
10-7
Queue Program
13-16
Read Me File
2-23
Relative Scheduling
5-4
Remaining Times
5-8
Reschedule On
5-4
Reset Command
10-11
Resource Requirements
5-12
Resources
3-7
Retry Job due to Bad Return Code
7-10
Running your agent as a Service
9-16
Scheduling Concepts
5-3
Scheduling Your Batch
8-13
SERVERS
17-11
Set Non-Business Days
8-34
Setting Packet Encryption
16-4
Show Activity
4-18
Simultaneous Jobs
9-11
20-7
Index
Skip Job due to Late Finish
7-9
Skip Job due to Late Start Time
7-9
Solaris command line type jobs
4-8
Special DOS Key Stuffing Commands
4-25
Special Scheduling
5-5
Start In Directory
4-10
Static Scheduling
5-3
Submitting Jobs Via Mail
4-39
Substitution Variable Date Math
4-15
Substitution Variable Formatting
4-16
Substitution Variables
4-7,
Substitution Variables in Jobs
4-11
Supported Operating Systems
3-8
SUSPEND
4-24
System Overview
3-3
System Requirements
2-3
TCP/IP
2-4
Terminology
3-4
Test Job
2-10
Time Sync File Server
10-9,
Times to Execute
5-8
Trigger Files
5-9
Troubleshooting
9-8
Tru64 command line type jobs
4-8
UnixWare command line type jobs
4-8
Update Estimated Minutes
10-7
Updating the GECS License Number
2-23
Use Controller Pause Times
10-10
User Defined Months
3-7
User Names
15-15
USERS
17-11
Using Batch Variables
8-14
Vacation Lookup Screen
8-41
Vacation Periods
3-6,
Valid Time Periods
5-7
Validate Utility
13-20
What are Batch Job Records?
8-12
What are Batch Submission Variables?
8-12
20-8
4-11
11-7
5-8
Index
What Do Batches Do?
8-11
What is a Batch?
8-11
What is Removing Batch Jobs?
8-13
What is Scheduling Batch Jobs?
8-12
Windows 95/98/ME command line type jobs
4-8
Windows command line type jobs
4-7
Windows NT/2000/XP/2003 command line type jobs
4-7
With Calendar
5-4
Within Hours
5-11
WRK File Path
10-8
WRK Files
3-6,
20-9
4-33
Download PDF
Similar pages