Professional Documents
Culture Documents
Reference Guide
4.5
This documentation and related computer software program (hereinafter referred to as the “Documentation”) is for
the end user’s informational purposes only and is subject to change or withdrawal by Computer Associates
International, Inc. (“CA”) at any time.
This documentation may not be copied, transferred, reproduced, disclosed or duplicated, in whole or in part,
without the prior written consent of CA. This documentation is proprietary information of CA and protected by the
copyright laws of the United States and international treaties.
Notwithstanding the foregoing, licensed users may print a reasonable number of copies of this documentation for
their own internal use, provided that all CA copyright notices and legends are affixed to each reproduced copy. Only
authorized employees, consultants, or agents of the user who are bound by the confidentiality provisions of the
license for the software are permitted to have access to such copies.
This right to print copies is limited to the period during which the license for the product remains in full force and
effect. Should the license terminate for any reason, it shall be the user’s responsibility to return to CA the reproduced
copies or to certify to CA that same have been destroyed.
To the extent permitted by applicable law, CA provides this documentation “as is” without warranty of any kind,
including without limitation, any implied warranties of merchantability, fitness for a particular purpose or
noninfringement. In no event will CA be liable to the end user or any third party for any loss or damage, direct or
indirect, from the use of this documentation, including without limitation, lost profits, business interruption,
goodwill, or lost data, even if CA is expressly advised of such loss or damage.
The use of any product referenced in this documentation and this documentation is governed by the end user’s
applicable license agreement.
Provided with “Restricted Rights” as set forth in 48 C.F.R. Section 12.212, 48 C.F.R. Sections 52.227-19(c)(1) and (2) or
DFARS Section 252.227-7013(c)(1)(ii) or applicable successor provisions.
Chapter 1: Introduction
Audience .....................................................................................1–1
Notational Conventions ....................................................................1–1
Related Publications ...........................................................................1–2
Chapter 2: Commands
Functional Listing of Commands ...............................................................2–2
archive_events ................................................................................2–4
asrcs_config ..................................................................................2–8
Contents iv
Event State Abbreviations................................................................. 2–32
autosc ...................................................................................... 2–39
Contents v
Creating eTrust AC Administrative Hosts .............................................. 2–62
Deleting eTrust AC Administrative Hosts .............................................. 2–62
Showing eTrust AC Administrative Hosts .............................................. 2–63
Authorizing an Administrator to Access an eTrust AC Administrative Host ............... 2–63
Removing Authorization for an Administrator to Access an eTrust AC Administrative Host 2–63
Showing All Administrators who can Administer from an eTrust AC Administrative Host . 2–64
Administer eTrust AC Remote Subscribers ............................................. 2–65
Creating eTrust AC Remote Subscribers................................................ 2–65
Deleting eTrust AC Remote Subscribers ................................................ 2–65
Showing eTrust AC Remote Subscribers ............................................... 2–66
Get Encrypted Passwords for Adapters .................................................... 2–66
autotimezone ............................................................................... 2–69
TZ Variable Syntax ...................................................................... 2–71
autotrack ................................................................................... 2–75
chase ....................................................................................... 2–82
Running chase Automatically ......................................................... 2–84
chk_auto_up ................................................................................ 2–86
Return Codes ........................................................................... 2–88
chk_cond (SP) ............................................................................... 2–90
clean_files .................................................................................. 2–92
cron2jil ..................................................................................... 2–94
dbstatistics ................................................................................. 2–96
eventor ..................................................................................... 2–97
Log Files ............................................................................ 2–98
jil ......................................................................................... 2–101
job_depends ............................................................................... 2–106
job_delete ................................................................................. 2–112
monbro ................................................................................... 2–113
record_sounds ............................................................................. 2–116
Record Sounds: ..................................................................... 2–117
sendevent ................................................................................. 2–118
vi Reference Guide
sendevent (SP).............................................................................. 2–130
start_rcs ................................................................................... 2–132
Contents vii
job_name (GUI only) ........................................................................ 3–49
job_terminator .............................................................................. 3–50
job_type .................................................................................... 3–52
machine .................................................................................... 3–54
max_exit_success ............................................................................ 3–57
max_run_alarm ............................................................................. 3–59
min_run_alarm ............................................................................. 3–61
n_retrys .................................................................................... 3–63
override_job ................................................................................ 3–64
owner ...................................................................................... 3–67
permission.................................................................................. 3–72
User Types .......................................................................... 3–73
Permission Types .................................................................... 3–73
User and Permission Types ........................................................... 3–75
Job Permissions and Windows ............................................................ 3–76
priority ..................................................................................... 3–77
profile ...................................................................................... 3–79
run_calendar................................................................................ 3–83
run_window ................................................................................ 3–85
Run Windows in Boxes ............................................................... 3–86
start_mins .................................................................................. 3–88
start_times .................................................................................. 3–90
std_err_file ................................................................................. 3–92
std_in_file .................................................................................. 3–95
std_out_file ................................................................................. 3–97
term_run_time ............................................................................. 3–100
timezone .................................................................................. 3–102
update_job ................................................................................ 3–106
watch_file ................................................................................. 3–107
watch_file_min_size ........................................................................ 3–110
watch_interval ............................................................................. 3–112
success...................................................................................... 5–29
terminated .................................................................................. 5–30
update_monbro ............................................................................. 5–31
Contents ix
Appendix A: System States
Events....................................................................................... A–1
ALARM (106) ............................................................................ A–1
CHANGE_PRIORITY (120) ................................................................ A–1
CHANGE_STATUS (101).................................................................. A–2
CHECK_HEARTBEAT (116) ............................................................... A–2
CHK_BOX_TERM (118) ................................................................... A–2
CHK_MAX_ALARM (114) ................................................................ A–2
x Reference Guide
SUCCESS (4) ............................................................................ A–7
TERMINATED (6) ....................................................................... A–7
Alarms ..................................................................................... A–8
AUTO_PING (526) ....................................................................... A–8
CHASE (514) ............................................................................ A–8
DATABASE_COMM (516) ................................................................ A–8
DB_PROBLEM (523) ..................................................................... A–8
DB_ROLLOVER (519) .................................................................... A–8
DUPLICATE_EVENT (524) ............................................................... A–8
EP_HIGH_AVAIL (522) .................................................................. A–9
EP_ROLLOVER (520)..................................................................... A–9
EP_SHUTDOWN (521) ................................................................... A–9
EVENT_HDLR_ERROR (507) ............................................................. A–9
EVENT_QUE_ERROR (508) ............................................................... A–9
EXTERN_DEPS_ERROR (529) ............................................................. A–9
FORKFAIL (501) ........................................................................ A–10
INSTANCE_UNAVAILABLE (525) ....................................................... A–10
JOBFAILURE (503) ...................................................................... A–10
JOBNOT_ONICEHOLD (509) ............................................................ A–10
MAX_RETRYS (505) ..................................................................... A–11
MAXRUNALARM (510) ................................................................. A–11
MINRUNALARM (502) ................................................................. A–11
MISSING_HEARTBEAT (513) ............................................................ A–11
MULTIPLE_EP_SHUTDOWN (530) ...................................................... A–11
RESOURCE (512) ....................................................................... A–12
STARTJOBFAIL (506) ................................................................... A–12
VERSION_MISMATCH (518) ............................................................ A–12
Exit Codes ................................................................................. A–13
Contents xi
Appendix B: Database Tables and Codes
Tables and Views............................................................................. B–1
alarmode ................................................................................ B–2
alarm .................................................................................... B–2
audit_info ............................................................................... B–2
audit_msg ............................................................................... B–2
avg_job_runs ............................................................................. B–2
calendar ................................................................................. B–2
chase .................................................................................... B–3
cred ..................................................................................... B–3
event .................................................................................... B–3
event0 ................................................................................... B–3
event2 ................................................................................... B–3
eventvu.................................................................................. B–4
ext_job .................................................................................. B–4
glob ..................................................................................... B–4
intcodes ................................................................................. B–4
job ...................................................................................... B–4
job2 ..................................................................................... B–4
job_cond ................................................................................. B–5
job_runs ................................................................................. B–5
job_status ................................................................................ B–5
jobst ..................................................................................... B–5
keymaster ............................................................................... B–5
last_Eoid_counter ........................................................................ B–5
machine ................................................................................. B–6
monbro .................................................................................. B–6
msg_ack ................................................................................. B–6
next_oid ................................................................................. B–6
next_run_num ........................................................................... B–6
overjob .................................................................................. B–6
req_job .................................................................................. B–6
restart ................................................................................... B–7
timezones ................................................................................ B–7
wait_que ................................................................................ B–7
Appendix C: API
Accessing Events from the Database ............................................................ C–2
get_auto_event ( ) ......................................................................... C–3
Sending Heartbeats ........................................................................... C–5
Contents xiii
Chapter
Introduction
1
Audience
This guide is intended for system administrators and operations personnel who
will be responsible for defining jobs, and monitoring and managing these jobs.
This guide lists the system states and commands, as well as job, machine,
monitor, and report definition parameters.
Notational Conventions
This image is associated with information that is specific only to the Microsoft
Windows operating system.
Unless otherwise noted, the term Windows refers to any Microsoft Windows
operating system supported by Unicenter.
In this guide, the term Windows refers to Microsoft Windows operating systems
Windows NT, Windows 2000, and Windows XP Professional. Unless specifically
designated, Windows refers to any Microsoft Windows operating system
supported.
Introduction 1–1
Related Publications
Related Publications
For more information about Unicenter AutoSys JM, see the following:
■ Unicenter AutoSys Job Management Upgrade for UNIX and Windows User
Guide, which describes how to upgrade to the current version of Unicenter
AutoSys JM.
■ Unicenter AutoSys Job Management for UNIX User Guide, which describes
how to define, run, monitor and report on jobs. In addition this guide
describes how to run, manage, secure and administer Unicenter AutoSys JM.
Commands
2
This chapter provides a list of commands followed by an alphabetical listing of
all the commands used to control, configure, and report on jobs.
You can execute commands in a command prompt window using options and
arguments to specify exactly what you want them to do. You can also embed
many of these commands within batch files.
You can execute commands at the UNIX operating system prompt using
options and arguments to specify exactly what you want them to do. You can
also embed many of these commands within shell scripts. You can create
aliases for commands you use frequently. For example the sendevent command
that is used for starting jobs.
Note: The command reference found in this chapter is also available online,
through the UNIX man command. For example, to access the reference page for
the sendevent command, enter:
man sendevent
If this action does not display the proper man page, it is because the MANPATH
environment variable is not set correctly. This variable is usually set in the
$AUTOUSER/autosys.* files used for setting up the environment (* = .csh.host
name, .sh.host name, or ksh.host name).
Commands 2–1
Functional Listing of Commands
autoping
autosyslog
chase
chk_auto_up
autocal_asc
autotrack
clean_files
dbstatistics
job_delete
Task Command
Managing security autosys_secure
autostatus
monbro
Commands 2–3
archive_events
archive_events
Function
Removes old information from the database. archive_events will optionally copy
the information to an archive directory before deletion.
Syntax
Description
archive_events removes data from various database tables that are older than the
specified number of days. You use this command to prevent the database from
becoming full. If the -A option is used; the data is archived before it is deleted. It
is copied into a default directory unless you specify a different directory with -d
option. The –n option removes events and any alarms associated with them from
the event table. The -j option removes information from the job_runs table.
Because data from both the event and the job_runs tables is used to generate
reports with autorep, we recommend that you always archive the same number
of days of information from both tables. The -l option removes autotrack
information from the audit_info and audit_msg tables.
In Dual-Server mode, the data is archived from both servers at the same time.
If information from these tables is not regularly purged from the database, the
database can fill up rather quickly, stopping all processing. We highly
recommend that you run archive_events during the database maintenance cycle.
The DBMaint script, which runs daily by default, will do this for you.
Options
-n num_of_days Indicates that records older than the num_of_days should be deleted from the
event table. The num_of_days value indicates the number of days of
information that should be left in the database. If a row in the table is as old as
or older than this value, it will be deleted.
-j num_of_days Indicates that the information older than the num_of_days should be deleted
from the job_runs table. The num_of_days value indicates the number of days
of information that should be left in the database. If a row in the table is as old
as or older than this value, it will be deleted.
-1 num_of_days Indicates that the autotrack information older than the num_of_days should be
deleted from the audit_msg tables. The num_of_days value indicates the
number of days of information that should be left in the database. If a row in
the table is as old as or older than this value, it will be deleted.
For events, archive_events generates a file name for the file in which events are
stored. This file is:
archive_events.%AUTOSERV%.MM.DD.YYYY
For job_runs, archive_events generates a file name for the file in which the
job_runs information is stored. This file is:
archive_job_runs.%AUTOSERV%.MM.DD.YYYY
For autotrack tables, archive_events generates a file name for the file in which
the job_runs information is stored. This file is:
archive_audit.%AUTOSERV%.MM.DD.YYYY
where:
MM.DD.YYYY Specifies the date on which the archive_events command was run.
Commands 2–5
archive_events
For events, archive_events generates a file name for the file in which events are
stored. This file is:
archive_events.$AUTOSERV.MM.DD.YYYY
For job_runs, archive_events generates a file name for the file in which the
job_runs information is stored. This file is:
archive_job_runs.$AUTOSERV.MM.DD.YYYY
For autotrack tables, archive_events generates a file name for the file in which
the job_runs information is stored. This file is:
archive_audit.$AUTOSERV.MM.DD.YYYY
where:
WARNING! If you run the archive_events command more than once a day, this
file will be overwritten in that 24-hour period.
For Sybase or Microsoft SQL Server, the default number of events to archive at
one time is 100, which should be used unless the database is dangerously full
and the transaction log is likely to become full if 100 events are moved at once.
Each transaction (in this case the deletion of a Single-Event) is recorded in the
database’s transaction file, which shares file space with the actual data. If the
data space is almost full, you might want to remove only a few events at a time.
The maximum value is 500.
-D Indicates the name of the Sybase data server, and the specific database within
data_server:database it, from which events are to be archived.
-D TNSname Indicates the TNS alias name of the Oracle data server from which events are to
be archived.
-t Specifies the number of seconds to wait before timing out your SQL connection.
timeout_in_secs
This Value is used only by Sybase (Oracle silently ignores it.) When archiving
large event tables, set timeout_in_secs to a large number to prevent your SQL
connection from timing out. If the default setting of 300 seconds is insufficient,
increase the setting in 300-second increments. If timeout_in_secs is larger than
the DBLibWaitTime configuration parameter value (in the configuration file,)
archive_events will use the new time-out for the current session only. If –t is not
specified, archive_events defaults to 300 seconds, regardless of the Database
Wait Time setting.
Examples
1. To copy all events in the events table older than 5 days to the default archive
file, and delete it from the database, enter:
archive_events -A -n 5
Commands 2–7
asrcs_config
asrcs_config
Function
Syntax
asrcs_config
asrcs_config [-h] [-p PortNumber] [-a|-r] [-m Host/IP] [-d Directory ]
Description
Options
Running asrcs_config
Since asrcs_config modifies certain critical files and registry (Windows), only
privileged users can run asrcs_config. When executed, asrcs_config prints the
following:
AutoSys/RCS Configuration Utility
The user has to be a part of the administrator group. If any other user runs
asrcs_config, the following message is displayed:
***You need administrative privileges to run this program***
Only root can run asrcs_config, all other users will see the following message:
Commands 2–9
asrcs_config
The RCS communicates with its clients using a well-known port. This port
number can be specified during the installation. Currently the port number
defaults to 4444. If you want to change the port number after the installation,
asrcs_config can be used to change it. By choosing Administer RCS Port
Number, current RCS port number is displayed, and you can change the port
number at this time. The utility validates the user input for numeric value and
verifies it is not in the reserved port range before updating the port number.
Note: The port number change will take effect when RCS is restarted.
To view or edit RCS port number after the installation, select option [1] in
asrcs_config main menu. The RCS Port Number menu is below:
Please select from the following options:
[1] Change RCS Port Number.
[2] Show RCS Port Number.
[3] Exit from "Administer RCS Port Number" menu.
> 1
New RCS Port Number (or hit enter to cancel): 2372
Are you sure you wish to take this action? [y/n]: y
*** RCS Port number modified.
Please select from the following options:
[1] Change RCS Port Number.
[2] Show RCS Port Number.
[3] Exit from "Administer RCS Port Number" menu.
> 2
RCS Port Number: 2372
RCS Hosts
The RCS is permitted to communicate only with a set of hosts, called Valid
Hosts/IPs, and requests from other hosts are denied. The Valid Hosts/IPs is
specified during the installation.
To remove or add Valid Hosts/IPs after the installation, select option [2] in
asrcs_config main menu. The Valid Hosts/IP menu is shown following:
Please select from the following options:
[1] Create a Valid Host/IP entry.
[2] Delete a Valid Host/IP entry.
[3] Show all Valid Hosts/IPs.
[4] Exit from "Administer Valid Hosts/IPs" menu.
>
Create and Delete will prompt the user for the host or IP to create or delete.
Show all Valid Hosts/IPs displays all the hosts that are allowed to communicate
with RCS.
Please select from the following options:
[1] Create a Valid Host/IP entry.
[2] Delete a Valid Host/IP entry.
[3] Show all Valid Hosts/IPs.
[4] Exit from "Administer Valid Hosts/IPs" menu.
> 1
Host/IP to Add (or hit enter to cancel): myHost
*** myHost added to Valid Hosts.
Commands 2–11
asrcs_config
RCS Directories
(Web)Clients can request data or files from the RCS including the EP Log, Job
Log, and the Remote Agent Log. In order to prevent malicious requests for
sensitive files, RCS will only honor requests for files in a set of directories called
Valid Directories, while requests for files in other directories are denied. Valid
Directories are specified during the installation.
To remove or add Valid Directories after the installation, select option [3] in
asrcs_config main menu. Valid Directories menu is shown following:
Please select from the following options:
[1] Create a Valid Directory.
[2] Delete a Valid Directory.
[3] Show all Valid Directories.
[4] Exit from "Administer Valid Directories" menu.
>
The Create and Delete option will prompt you for a directory to add or delete.
The Show all Valid Directories option displays the valid directories.
Please select from the following options:
[1] Create a Valid Directory.
[2] Delete a Valid Directory.
[3] Show all Valid Directories.
[4] Exit from "Administer Valid Directories" menu.
> 1
Directory to Add (or hit enter to cancel): myDir
*** myDir added to Valid Directories.
autocal
Function
Syntax
autocal
Description
The autocal command is used to start up the Calendar Editor to define and
maintain calendars. The autocal command is used to start up the Graphical
Calendar to define and maintain calendars. You can also start the facility by
clicking Calendar Editor from the GUI Control Panel, or from the Date/Time
tab in the Job Editor.
Calendars are lists of dates that you can use to schedule the days on which jobs
should, or should not, run. This facility lets you define calendars using a point-
and-click approach on different screens that display a real-world calendar.
The Calendar Editor and Calendar Facility lets you do the following:
Commands 2–13
autocal
Calendars created using the Calendar Feature are actually a collection of dates,
which can be referenced in a job definition. Use one of the following methods to
apply a calendar:
■ In the Job Definition Date/Time Options dialog, enter a calendar name in the
Run on Days in Calendar field or the Do NOT Run on Days in Calendar
(Exclude) field.
For more information, see the chapter “Calendar Editor,” in the Unicenter
AutoSys Job Management for Windows User Guide, or the chapter “The
Graphical Calendar Facility,” in the Unicenter AutoSys Job Management for
UNIX User Guide.
Example
autocal
autocal &
autocal_asc
Function
Syntax
autocal_asc
Description
Once created, calendars can be referenced in a job definition. Use one of the
following methods to apply a calendar:
■ In the Job Definition Date/Time Options dialog, enter a calendar name in the
Run on Days in Calendar field or the Do NOT Run on Days in Calendar
Exclude field.
For more information, see the chapter “Calendar Editor,” in the Unicenter
AutoSys Job Management for Windows User Guide, or the chapter “The
Graphical Calendar Facility,” in the Unicenter AutoSys Job Management for
UNIX User Guide.
Commands 2–15
autocal_asc
Example
To start autocal_asc you will need to enter the calendar information, follow these
steps:
2. At this point you can enter the name of an existing calendar you want to
edit, or the name of a new calendar.
Note: If you enter D to delete, the same prompt appears, and you can enter the
date and time you want to delete from the calendar definition. If you enter P to
print, the screen displays a summary of the specified calendar.
4. Using the following format, enter the date and, optionally, the time:
MM/DD/[YY]YY [HH:MM]
where:
This prompt is repeated as long as dates are entered in response to the prompt.
Note: If you enter a two-digit year, Unicenter AutoSys JM saves the setting to
the database as a four-digit year. If you enter 79 or less, Unicenter AutoSys JM
prepends 20, and, if you enter 80 or greater, Unicenter AutoSys JM prepends 19.
Commands 2–17
autocons
autocons
Function
Syntax
autocons
Description
The Consoles lets you specify job selection criteria, which can be dynamically
changed, to control, which jobs you want to view. This criteria includes the
current job state, the job name (with wildcarding), and the machine on which the
job runs. You can select any job and view more detailed information about it,
including its starting conditions, dependent jobs, and autorep reports. You can
invoke the job definition automatically, allowing you to change the job, if the
correct permissions are set.
The Operator Console and the Scheduler Console provides an Alarm Manager,
which allows the monitoring of alarms as they are generated. In the Alarm
Manager, you can do the following:
For more information, see the chapter “Scheduler Console,” in the Unicenter
AutoSys Job Management for Windows User Guide, or the chapter “The
Operator Console,” in the Unicenter AutoSys Job Management for UNIX User
Guide.
Example
autocons
autocons &
Commands 2–19
autoeac_test
autoeac_test
Function
Syntax
autoeac_test [ STAT | JOB | LIST | MACHINE | CONTROL | CALENDAR | OWNER |
GLOBAL_VAR] resource_name [X | W| R| C | D | U] optional_user_name
Description
Options
JOB job_name [X|W|R|C|D|U] Issues a security check to the local eTrust pmdb for job resource
job_name.instance to test if access is granted to the execute, write, read, create,
delete, or update operation.
Note: The autoeac_test tool automatically appends the current instance name
to job_name so that a resource check will be made for job_name.instance.
MACHINE machine_name Issues a security check to the local eTrust pmdb for machine resource
[X|W|R|C|D|U] machine_name.instance to test if access is granted to the execute, write, read,
create, delete, or update operation.
Note: The autoeac_test tool automatically appends the current instance name
to machine_name so that a resource check will be made for
machine_name.instance.
GLOBAL_VAR glovar_name Issues a security check to the local eTrust pmdb for global variable resource
[X|W|R|C|D|U] glovar_name.instance to test if access is granted to the execute, write, read,
create, delete, or update operation.
Note: The autoeac_test tool automatically appends the current instance name
to glovar_name so that a resource check will be made for
glovar_name.instance.
CALENDAR calendar_name Issues a security check to the local eTrust pmdb for calendar resource
[X|W|R|C|D|U] calendar_name.instance to test if access is granted to the execute, write, read,
create, delete, or update operation.
OWNER owner_name Issues a security check to the local eTrust pmdb for owner resource
owner_name to test if access is granted to the execute operation.
LIST Issues a security check to the local eTrust pmdb for one of the list resources
[AUTOCAL|AUTOCONS|AUTOREP| listed to test if access is granted to the read operation.
JOBDEF| JOBDEP|MONBRO|XPERT]
Note: The autoeac_test tool automatically appends the current instance name
to the list resource name. For example: AUTCAL.instance
CONTROL Issues a security check to the local eTrust pmdb for one of the control resources
[EPLOG|SECADM|STOP_DEMON| listed to test if access is granted to the execute operation.
WEBADM]
Note: The autoeac_test tool automatically appends the current instance name
to the list resource name. For example: EPLOG.instance
X Specifies to execute.
Commands 2–21
autoeac_test
W Specifies to write.
R Specifies to read.
C Specifies to create.
D Specifies to delete.
U Specifies to update.
Examples
If execute access rights for the job have been granted to the logged-on user, then
the following will display:
Security check passed!
If execute access rights for the job have been granted to user jane@taurus, then
the following will display:
Security check passed!
autoflags
Function
Syntax
autoflags [-a | -i | -o | -d | -v | -x | -r | -h | -n]
Description
The autoflags command prints out the version and release number, the database
being used, and the operating system. You also use autoflags to determine the
proper host name and host id for license key generation.
Options
-d Displays the database type to standard output, either SYB for Sybase or ORA
for Oracle.
Commands 2–23
autoflags
Example
autoping
Function
Verifies that the various communication facilities are correctly configured and
functioning.
Syntax
autoping -m {machine|ALL} [-A] [-D]
Description
autoping verifies that the server and client machines are properly configured
and are communicating successfully. It also checks and verifies that the Remote
Agent and the Remote Agent’s database connection are functioning correctly. If
you are running Dual-Event Servers, it checks both database connections. If
requested, it generates an alarm when problems are detected.
When autoping is executed, the server (the machine from which autoping is
issued) establishes a connection with the client machine and waits for the
Remote Agent to respond. If successful, the following message will be
displayed on standard output at the server:
AutoPinging Machine [machine]
AutoPing WAS SUCCESSFUL!
If there is a problem with the configuration, a message indicating that the remote
machine has not responded (or that there is a more serious problem, such as a
socket read error) will be displayed.
Commands 2–25
autoping
When autoping is executed, the server (the machine from which autoping is
issued) establishes a connection with the client machine, which starts a Remote
Agent on that machine, and the server waits for the Remote Agent to respond.
If successful, the following message will be displayed on standard output at the
server:
AutoPinging Machine [machine]
AutoPing WAS SUCCESSFUL!
If there is a problem with the configuration, a message indicating that the remote
machine has not responded or that there is a more serious problem, such as a
socket read error will be displayed. Most of the time, these problems have to do
with the improper installation of the Remote Agent with regard to the
configuration of the internet demon inetd.
Options
-m machine|ALL In order to use the -m ALL option, you must first define machines to the
database using the insert_machine command. If you do not define the
machines, autoping will display the following message:
-m The name of the machine to be verified. This must be a real machine, and must
be accessible through TCP/IP network protocol on the machine from which the
command is issued. ALL checks all machines.
-m The name of the machine to be verified. This must be a real machine, and must
be listed in the /etc/hosts file on the machine from which the command is
issued. ALL checks all machines.
Example
To check whether the machine “venice” is properly configured, and that its
Remote Agent can function properly, enter:
autoping -m venice
Commands 2–27
autorep
autorep
Function
Reports information about a job, jobs within boxes, machines, and machine
status. Also reports information about job overrides and global variables.
Syntax
Description
autorep lists a variety of information about jobs, machines, and global variables
currently defined in the database. You can use it to list a summary of all
currently defined jobs, or to display current machine load information. autorep
serves as a problem tracking tool by listing all relevant event information for the
last run of any given job, or a specified job run. You can also use it to extract job
definitions in JIL script format and save them to an output file for later re-
loading into AutoSys, as a means of backing up job definitions.
autorep retrieves data from the database to formulate the reports. Any data that
has been archived with archive_events will not appear in the reports.
When listing nested jobs, subordinate jobs are indented to illustrate the
hierarchy. The following sections describe the types of autorep reports.
When a summary is requested, autorep prints the current status, if the job is still
running, or the status for a previous run. The summary report reflects the last
status posted to the database.
When detail is requested, autorep prints all events for the job that are recorded in
the event table in the database. If the job is running, it posts events for the
current run. If the job is not running, it posts events for the most recent run, or, if
requested, a previous run.
For all machines defined, you can use autorep to examine the current load and
the defined maximum load and factor.
autorep can print information for a specified override, based on job name and
override number. In addition to the overridden job definition fields, it also
displays user, time and run information.
Commands 2–29
autorep
The columns in an autorep report vary with the type of report requested. The
following table describes the columns.
Status Abbreviations
The following table lists the abbreviations used in the ST (status) column of the
autorep report, and gives the status for each abbreviation.
FA FAILURE
IN INACTIVE
OH ON_HOLD
OI ON_ICE
QU QUE_WAIT
RE RESTART
RU RUNNING
ST STARTING
SU SUCCESS
TE TERMINATED
Commands 2–31
autorep
The following table lists the abbreviations used in the ES (event state) column of
the autorep report, and gives the status for each abbreviation.
PD Processed
PG Processing
UP Unprocessed
US Unsent
Options
-J job_name Indicates that a Job Report is desired. job_name specifies the name of the job on
which to report. Any valid job name may be specified. To report on all jobs,
specify ALL. The percent (%) character may be used in the job name as a
wildcard (For example: %box% will select all jobs containing the string “box”).
Note: The underscore (_) character may also be used as a wildcard to match
exactly one character. However, this can lead to some unexpected results when
the job name itself contains an underscore “_” character. For example, specifying
the job name “mon_%” will select all jobs beginning with the string “mon,” such
as mon_box, monet, and so on.
-M machine_name Indicates that a Machine Report is desired, which lists the machine’s Max Load,
Current Load, and Factor. machine_name specifies the machine on which to
report. This may be a virtual machine, a real machine, or ALL for all machines;
the machine must be defined.
-G global_name Indicates that a global variable report is desired, listing the variable name,
value, and last modification date. global_name specifies the name of a global
variable that has been set using the sendevent command or the Send Event
dialog. In the specification, you can use ALL or wildcard characters.
For a Job Report, the following information is provided: Start date/ time, End
date/time, Current Status, Run Number, and Priority. You can request a report
on a specific job run with the -r option. If the –r option is omitted, the most
current job run is used.
For a Machine Report, the following information will be provided for each
specified machine: Machine Name, Max Load, Current Load, and Factor.
For example; if you have JobA with a name that was 64 characters long, autorep
would cut off a portion of the name to save space for formatting. However,
with –w, the entire job name would be shown.
For a Job Report, all events from the last run of the requested job will be listed.
For each event, the following data is provided: Status, Date/ Time, Try
Number, Event State (whether the event has been processed by the Event
Processor yet), Process Date/Time, and the Machine on which the job was run.
Also specifies if a job was run with an override and lists the override number.
For a Machine Report, the following information will be provided for each
specified machine: Machine Name, Maximum Load, Current Load, and Factor.
In addition, for any jobs currently running on the specified machines, the
following information will be provided: Job Name, Machine, Status, Load, and
Priority.
Commands 2–33
autorep
-o over_num Indicates an Override Report is desired, providing the overrides for the
specified override number (over_num) and job_name. If the most current
override is desired, the value of over_num should be zero. The job attributes
and their associated overrides are displayed to standard output. You must
supply a job name (-J job_name) with this option.
-R run_num Indicates a report is desired for a specific job run (run_num). This option can
only be used with the -s and -d options. If this option is omitted, or run_num is
zero, the most current job run is reported. A minus sign (-) can be used before
the run_num value to indicate a relative counter for a past job run, relative to
the current run number. For example, the option -r -2 would generate a report
for the job run two runs back.
-L print_level (Job reports only.) Indicates the number of levels of nesting for boxes for which
the specified information should be listed. For example, a level of 2 means list
the information for the specified job (a box) as well as two levels of jobs within
that box.
This value may be any valid numeric value; to list the outermost box alone,
specify “0.” The default is to list all levels within the box.
-N Retry Specifies the number of times autorep should attempt to reconnect to the
database before giving up. The default number of attempts is 3.
-t Requests that the time zone, if one is specified in the job definition, appear in
the report. If requested, the time zone will appear in parentheses beneath the
job name and the Time column of the report will be based on the specified time
zone.
-D Indicates the name of the Sybase or Microsoft SQL Server data server, and the
data_server: specific database within it, to be searched for the specified information.
database
Normally, autorep consults the Unicenter AutoSys Administrator (which are
read from the Windows Registry) to determine which database to connect to.
This option enables autorep to report on any Event Server on the network.
-D Indicates the name of the Sybase data server, and the specific database within
data_server: it, to be searched for the specified information. Normally, autorep consults the
database
configuration file ($AUTOUSER/ config.$AUTOSERV) to determine which
database to connect to. This option enables autorep to report on any Event
Server on the network.
-D TNSname Indicates the TNS alias name of the Oracle data server to be searched for the
specified information. Normally, autorep consults the configuration file
($AUTOUSER/config.$AUTOSERV) on UNIX, or the Windows NT Registry, to
determine which database to connect to. This option enables autorep to report
on any Event Server on the network.
Examples
2. The following is the detail report that shows each event and status for each
job. This command requests the report:
autorep -J Nightly_Download -d
Job Name Last Start Last End ST Run Pri/Xit
________________ ____________________________________________________
Nightly_Download 11/10/1997 17:00 11/10/1997 17:52SU 101/1
Status/[Event] Time Ntry ES ProcessTime Machine
-------------- -------------------------------------------------------
RUNNING 11/10/1997 17:00:12 1 PD 11/10/1997 17:00:17
SUCCESS 11/10/1997 17:52:31 1 PD 11/10/1997 17:52:32
Watch_4_file 11/10/1997 17:00 11/10/1997 17:13 SU 101/1
Status/[Event] Time Ntry ES ProcessTime Machine
-------------- -------------------------------------------------------
STARTING 11/10/1997 17:00:13 1 PD 11/10/1997 17:00:19
RUNNING 11/10/1997 17:00:19 1 PD 11/10/1997 17:00:29 gateway
SUCCESS 11/10/1997 17:13:22 1 PD 11/10/1997 17:13:31
filter_data 11/10/1997 17:13 11/10/1997 17:24 SU 101/1
Status/[Event] Time Ntry ES ProcessTime Machine
-------------- -------------------------------------------------------
STARTING 11/10/1997 17:13:32 1 PD 11/10/1997 17:13:34 gateway
RUNNING 11/10/1997 17:13:38 1 PD 11/10/1997 17:13:45 gateway
SUCCESS 11/10/1997 17:24:23 1 PD 11/10/1997 17:24:30
update_DBMS 11/10/1997 17:24 11/10/1997 17:52 SU 101/1
Status/[Event] Time Ntry ES ProcessTime Machine
-------------- -------------------------------------------------------
STARTING 11/10/1997 17:24:16 1 PD 11/10/1997 17:24:22 gateway
RUNNING 11/10/1997 17:24:20 1 PD 11/10/1997 17:24:29 gateway
SUCCESS 11/10/1997 17:52:23 1 PD 11/10/1997 17:52:31
Commands 2–35
autorep
3. The following is an example of a detailed report for one run back. This
command requests the report:
autorep -J RunData -d -r -1
Job Name Last Start Last End ST Run Pri/Xit
_____________ ________________________________________________________
RunData 08/15/1997 12:14 08/15/1997 12:15 FA 2565/11
Status/[Event] Time Ntry ES ProcessTime Machine
-------------- -----------------------------------------------------
STARTING 08/15/1997 12:14:56 1 PD 08/15/1997 12:15:00 venice
RUNNING 08/15/1997 12:14:58 1 PD 08/15/1997 12:15:05 venice
FAILURE 08/15/1997 12:15:00 1 PD 08/15/1997 12:15:05
[*** ALARM ***]
JOBFAILURE 08/15/1997 12:15:04 1 PD 08/15/1997 12:15:10 venice
[STARTJOB] 08/15/1997 12:15:38 0 PD 08/15/1997 12:15:46
4. The following example lists all machines defined on the data server. This
command requests the report:
autorep -M ALL
Machine Name Max Load Current LoadFactor O/S
_______________ ________ __________________ _____
london 100 0 1.00 Unix
berlin 90 0 0.90 NT
v_italy.rome 0 0 0.00 Unix
v_italy.venice 0 0 0.00 Unix
v_france.paris 100 0 1.00 NT
v_france.cannes 75 0 1.00 NT
6. The following is an override report, showing the first one-time job override
for the job. This command requests the report:
autorep -J RunData -o 1
/* -------------------- over -------------------- */
override_job: RunData
/* Over-Ride #1 Set by User: roger@venice on [07/25/1997 18:23:45] */
/* Was RUN on run_num=175, Started on: 07/25 18:24:01 */
command: /bin/rundata1
7. To list the value of a specific variable, specify the variable using the –G
option, as shown in the following example:
autorep -G DAY
The output from this command would look similar to the following:
Wednesday
8. To list the value of all global variables that have been set, enter:
autorep -G ALL
The output from this command would look similar to the following:
Global Name Value Last Changed
------------ ------------ -------------------
DAY Wednesday 11/12/1997 12:18:27
AUDIT_DIR /usr/audit11/12 /1997 12:41:00
DINNER_TIME 18:30 11/12/1997 12:40:00
MAX_VAL 2048 11/12/1997 12:30:24
9. To list a summary report on the top two levels of boxes in the job named
“Box3,” enter:
autorep -J Box3 -s -L 2
10. To include the time zone specification in a detailed report for the last run of
the job named “MyJob,” enter:
autorep -J MyJob -d -t
When you use the -t option, the time reported in the Time column is translated to
the time zone specified in the job definition. The time reported in the
ProcessTime column is not affected by the -t option. It shows the time the event
processor processed the events (server time).
The output from this command would look similar to the following:
Job Name Last Start Last End ST Run Pri/Xit
_____________________________ _________________ _______ _____ _______
MyJob 12/10/1997 17:30 12/10/1997 17:30 SU 102/1
(Chicago)
Status/[Event] Time Ntry ES ProcessTime Machine
-----------------------------------------------------------------------------
STARTING 12/10/1997 17:30:05 1 PD 12/10/1997 16:30:13 localhost
RUNNING 12/10/1997 17:30:08 1 PD 12/10/1997 16:30:13 localhost
SUCCESS 12/10/1997 17:30:10 1 PD 12/10/1997 16:30:13
[STARTJOB] 12/10/1997 17:30:00 0 UP
<Event was Scheduled based on Job Definition.>
Commands 2–37
autorep
11. You can use the autorep command to extract job definitions in JIL script
format and direct the output to a file. The following example shows how to
save all job definitions to a file.
autorep -J ALL -q > dump_file
Note: The owner field of each job definition is commented out unless the Edit
Superuser ran the autorep command to generate this report. Only the Edit
Superuser can change the owner field.
You can save this file as a backup of job definitions, or you can use a text editor
to quickly edit the job definitions. To re-load the job definitions into the
database, use the following jil command:
jil < dump_file
autosc
Function
Syntax
autosc
Description
The autosc starts up the GUI. From the GUI Control Panel, you can open
applications and dialogs to define jobs, monitors, reports (browsers), and
custom run or exclude calendars, as well as access the Operator Console.
For more information, see the Unicenter AutoSys Job Management for UNIX
User Guide.
Example
autosc &
Commands 2–39
autostatus
autostatus
Function
Reports the current status of a specific job, or the value of a global variable.
Syntax
autostatus {-J job_name | -G global_name} [-S autoserv_instance]
Description
autostatus writes the current status of the specified job or the current value of a
global variable to standard output. This facility is especially useful in two
circumstances:
■ When complex starting conditions are required that is beyond the scope of
the starting conditions that can be easily specified in the job definition.
As an example of the latter situation, a job may need to be started when two out
of a set of three jobs have completed successfully. This situation could be
encoded by way of the starting conditions, but the conditions would be very
cumbersome to define. Instead, you could use autostatus in a shell script to
check the status of these jobs, and perform the appropriate action. A detailed
description of this is given in the Examples section, following.
Options
-J job_name Specifies the name of the job whose status needs to be determined. The current
status is returned to standard output.
-G global_name Specifies the name of a global variable that has been set using the sendevent
command or the Send Event dialog. The value of the global variable is returned
to standard output.
-S autoserv_instance Specifies the three-character code of the instance to be queried. The UNIX
default is the value of $AUTOSERV from the current environment. Or, in
Windows the default is the value of %AUTOSERV%.
Examples
1. To check the current status of the job named “test_install” in the current
instance, enter:
autostatus -J test_install
b. To create a batch file with the name “New_Stats.bat” to run for the job
named “New_Stats_Starter.” This batch file will determine if the job
“New_Stats” should be started. It communicates its decision by exiting
with a “0” (SUCCESS) or nonzero (FAILURE) exit code. The job named
“New_Stats” bases its starting condition on that exit code.
@REM ECHO OFF
@REM Program to determine when to start New_Stats
@REM
@REM Check for 13th of month, if it is, exit with 2
@echo | more | date > testdate.out
@findstr /c:"/13/" testdate.out
@if errorlevel 1 goto not13
@if errorlevel 0 echo 13th of the month
@del testdate.out
@autostatus -J %1 > test1.dat
@findstr SUCCESS test1.dat
@if errorlevel 1 goto nosuccess
@if errorlevel 0 goto sayok
:nosuccess
@del test1.dat
@REM false is supplied in %AUTOSYS%\bin
@false 1
@goto exit:
:sayok
@del test1.dat
Commands 2–41
autostatus
@goto exit
:not13
@del testdate.out
@REM false is supplied in %AUTOSYS%\bin
@false 2
:exit
Note: Reference jobs running on other instances, the $AUTOSERV for that
instance needs to be supplied in the call to autostatus.
Note: Reference jobs running on other instances, the $AUTOSERV for that
instance needs to be supplied in the call to autostatus.
c. Create the job named “New_Stats” and specify that it should start when
the previous job completes successfully. Use the following starting
condition as its job definition:
condition: success(New_Stats_Starter)
autosyslog
Function
Syntax
autosyslog [-e | -J job_name] [-p]
Description
autosyslog is used to view either the event processor log file or the Remote
Agent log file for the specified job. Both the Remote Agent and Event Processor
write diagnostic messages to their respective logs, as part of their normal
operations and in response to detected error conditions.
Using autosyslog to view the event processor log is the same as issuing the
following command:
tail -f $AUTOUSER/out/event_demon.$AUTOSERV
The last 10 lines of the event processor log file are displayed when the
autosyslog command is issued. The log file is updated continually as processing
occurs. To terminate the display of the log, press Ctrl+C in the display window.
The autosyslog utility can be a useful diagnostic tool when jobs fail. This
command, when provided with the name of a job, displays the log of the job’s
most recent run. Although the Remote Agent’s log file is automatically deleted
by default after a successful job run, the log file will not be deleted at job
completion if the job ended with a FAILURE status.
Commands 2–43
autosyslog
The event processor log contains a timestamped history of each event that
occurs. Viewing this log is an alternative to monitoring “all jobs” and “all
events.”
Options
-e Indicates that the event processor log is to be monitored. When in this mode, in
order to terminate the command, you must press Ctrl+C.
To view the event processor log, you must execute this command on the
machine that is running the event processor, or on a machine that can access the
same %AUTOUSER% file system. Also, the %AUTOUSER% and
%AUTOSERV% environment variables must be set the same as it was when the
event processor was run.
To view the event processor log, you must execute this command on the
machine that is running the event processor, or on a machine that can access the
same $AUTOUSER file system. Also, the $AUTOUSER and $AUTOSERV
environment variables must be set the same as it was when the event processor
was run.
-J job_name Indicates that the Remote Agent log for the specified job_name is to be viewed.
You must issue this command on the machine where job_name ran. Otherwise,
the following message will display:
Note: View the Remote Agent log, you must execute this command from the
machine on which the specified job ran last.
Examples
1. To view the event processor log, enter this on the command line of the
system where the event processor is running, or where it ran last:
autosyslog –e
You can enter this command on any machine that can access the same file
system for example %AUTOUSER% as the event processor.
You can enter this command on any machine that can access the same file
system for example $AUTOUSER as the event processor.
2. To view the Remote Agent log of the last run of the “test_install” job, you
would issue the following command on the command line of the machine
where the “test_install” job ran:
autosyslog –J test_install
autosyslog –j job_name –p
This command will display the log file first, appending the profile output, if
there is any. If no profile output file exists, the profile output section will be
empty, for example:
Commands 2–45
autosys_secure
autosys_secure
Function
Syntax
autosys_secure
or:
Description
You use the autosys_secure command to specify the Edit Superuser and Exec
Superuser, the database password, remote authentication method, and Windows
user IDs and passwords. You can also use autosys_secure to enable eTrust
security within Unicenter AutoSys JM and perform basic eTrust administration
operations.
Two users have administrator privileges: the Edit Superuser and the Exec
Superuser.
The Edit Superuser is the only user with permission to do the following:
■ Edit or delete any job, regardless of who owns it and what permissions are
set for it.
■ Issue start or kill any job, regardless of the execution permissions on the
specified job. This user can affect how jobs run, typically by issuing the
sendevent command.
■ Shut down the Event processor (by sending the STOP_DEMON event).
Database Password
The database password is used by the Event processor, GUIs, and command-line
utilities to securely access the database (Event Server). By default, this password
is stored in the database as autosys, but you can change it by using
autosys_secure.
Every Event Server in an instance must have the same database password. If you
are running in Dual-Server mode, autosys_secure changes the password on both
Event Servers.
Note: If you have rolled over to Single-Server mode, do not change the
password until you have established Dual-Server mode again.
Remote authentication methods are used to verify one or both of the following:
The remote authentication methods are stored in the database and are referenced
when a client initializes.
Commands 2–47
autosys_secure
Windows user IDs and passwords must be entered into the database in order
for jobs to run on Windows client machines. When a Remote Agent runs a job
on a machine, it logs on and impersonates the user who owns the job. To enable
the Remote Agent to do this, the event processor passes both the job
information and an encrypted version of the job owner’s password from the
database to the Remote Agent. The Edit Superuser must enter these passwords,
and the Edit Superuser can do this from one machine using autosys_secure,
either interactively or from the command line. After the IDs and passwords are
entered, any user that knows an existing user ID and password can change the
password or delete that user ID and password.
Running autosys_secure
When a user other than the Edit Superuser invokes autosys_secure, the following
menu displays:
AutoSys Security Utility.
Only the AutoSys EDIT superuser has access to all options!
Please select an action to perform:
Options 1 thru 4 for superusers only
[5] Change AutoSys User@Host or Domain password.
[6] Delete AutoSys User@Host or Domain password.
[7] Exit autosys_secure.
Any user that knows an existing user ID and password combination can change
the password or delete the user from the database.
You can run autosys_secure from the command line to enter, change, or delete
Windows user IDs and passwords. This option allows you to write interactive
programs or batch files to enter or modify large numbers of user IDs and
passwords, if necessary. To do this, you can use Windows Batch or Perl (Perl is
shipped with Unicenter AutoSys JM for Windows).
Commands 2–49
autosys_secure
You can run autosys_secure from the command line to enter, change, or delete
Windows user IDs and passwords. This option allows you to write interactive
programs, scripts, or batch files to enter or modify large numbers of user IDs
and passwords, if necessary. To do this, you can use any scripting language,
such as Windows Batch or Perl (Perl is shipped with Unicenter AutoSys JM for
Windows).
Print the usage statement for the command-line options to the screen, enter this
command:
autosys_secure –h
The first time option [1] in the autosys_secure menu is chosen after Unicenter
AutoSys JM is installed, you are prompted for the names of the users who
should be assigned the Edit Superuser and Exec Superuser privileges. Both these
privileges can be assigned to the same user. These users must be valid users on
the host or domain that you are logged onto.
After the initial assignments, only the Edit Superuser can change these
assignments. Option [1] displays the current settings and allows the Edit
Superuser to accept the same users by clicking Enter, or change the users by
entering a new specification.
Database Password
Option [2] in the autosys_secure menu displays a prompt at which you can
change the database password. This option changes the database password for
the autosys user. By default, the password is autosys.
Only the Edit Superuser can change the database password. The password must
be between 6 and 20 characters in length. It can contain uppercase and lowercase
alpha characters, numbers, and punctuation marks; it cannot contain single or
double quotes, spaces, or control characters.
Note: For Bundled Sybase users only, the sa system administrator user
password is sysadmin by default. To change the password for the sa user, use
the xql utility.
Only the Edit Superuser can change the remote authentication method. When
option [3] in the autosys_secure menu is chosen, the following menu displays.
No Remote Authentication
Commands 2–51
autosys_secure
Note: The Edit Superuser can override this type of remote authentication by
changing the ownership of a job from the form user@host_or_domain to the form
user. As a result, remote authentication on the job on the target machine at
execution time is not performed.
Note: The Edit Superuser can override this type of remote authentication by
changing the ownership of a job from the form user@machine to the form user.
As a result, remote authentication on the job on the target machine at execution
time is not performed.
Notes:
Commands 2–53
autosys_secure
Before activating Event Processor authentication, you must set up and properly
configure the /etc/.autostuff file on every client machine that will participate
in this authentication method.
When this option is selected, both the Remote Agent user and the Event
Processor authentication methods will be used. If this option is enabled, both
methods of authentication must succeed for the job to run.
When this option is selected, both the UNIX ruserok() and the Event Processor
authentication methods will be used. If this option is enabled, both methods of
authentication must succeed for the job to run.
Option [4] in the autosys_secure menu lets you enter a user name, a host or
domain name, and a password for a user. autosys_secure accepts a NULL
password. A message appears to confirm the user was created. No validation is
done to verify the password is correct (but the process does verify that the
password can be encrypted and decrypted correctly). You must enter Windows
user IDs and passwords for all users that will be job owners (users that will be
specified by the owner job attribute). If the Windows user ID and password
combination is not valid, the Remote Agent will issue an error when it attempts
to run a job as that user, because it will not be able to log on when the job is to
be run. Windows user names can be from 1 to 20 characters in length and can
contain all characters except the following:
[]+:;“<>.,?/\|
Once eTrust security has been enabled, a subscriber authentication security word
must be set, otherwise access to secured operations within the product will
automatically be denied.
For more information on subscriber authentication security word, see the topic
Subscriber Authentication Security Word in this chapter.
Note: These options are only available from the interactive mode of
autosys_secure and have no command line arguments.
There are three criteria which must be satisfied before a user is able to modify
security policies within the eTrust environment or use the eTrust administration
options within autosys_secure:
Commands 2–55
autosys_secure
Notes:
autosys_secure does not impose an operating system user format. You can
specify a UNIX formatted user (user@host) if accessing the UNIX pmdb from
a Windows terminal, similarly you can specify a Windows formatted user
(MACHINE\user or DOMAIN\user) if accessing the Windows pmdb from a
UNIX terminal.
If an eTrust AC administrative host has a user owner associated with it, then
that user is automatically granted authorization to administer from the
administrative host.
For more information on how to create Administrative Hosts, see the section,
Administer eTrust AC Administrative Hosts, in this chapter.
3. A list of all the eTrust AC administrative users that are authorized to use the
eTrust administrative host created in Step 2 (including the administrator
created in Step 1) must be defined within the eTrust environment.
Commands 2–57
autosys_secure
When option [7] Administer eTrust Access Control (eTrust AC) in the
autosys_secure menu is chosen the following options will be displayed:
Note: Once eTrust has been enabled, the remaining eTrust administrative
options will attempt to verify that execute access to the eTrust resource
SECADM.<instance> pertaining to the eTrust user-defined class as-control has
been granted before proceeding. If as-control\SECADM execute access has been
denied, autosys_secure will display a message saying that the user is not
authorized.
When autosys_secure is invoked after eTrust AC has been enabled and you
select option [7] Administer eTrust Access Control, the following menu is
displayed:
Please select from the following options:
[1] Disable eTrust Access Control.
[2] Set subscriber authentication security word.
[3] Administer eTrust Access Control administrators.
[4] Administer eTrust Access Control administrative hosts.
[5] Administer eTrust Access Control remote subscribers.
[6] Exit from "Administer eTrust Access Control" menu.
When you establish your security word, run autosys_secure as a user from a host
that you are authorized to administer the eTrust PMDB You will be prompted
for your security word. The only time you will ever be prompted for this word
again is if you decide to change your security word.
Important! If you have reason to believe that your security word has been
compromised, you should change it using autosys_secure. With that
information it would be possible for a malicious user to setup a local eTrust
policy and circumvent security.
Commands 2–59
autosys_secure
Option [1] in the autosys_secure menu lets you enter an administrator name, a
host or domain name, and a host of where the autosys PMDB resides. If the
eTrust AC administrator is to be created in the local seosdb press Enter when
prompted for the host of the autosys PMDB. A message appears to confirm the
eTrust AC administrator was created.
Option [2] in the autosys_secure menu lets you enter an administrator name, a
host or domain name, and a host of where the autosys PMDB resides. If the
eTrust AC administrator is to be deleted from the local seosdb press Enter when
prompted for the host of the autosys PMDB. You will be prompted to confirm
this action. Once confirmed, a message appears to confirm the eTrust AC
administrator was deleted.
Option [3] in the autosys_secure menu lets you enter a host of where the autosys
PMDB resides. If the eTrust AC administrators to be displayed reside in the local
seosdb press Enter when prompted for the host of the autosys PMDB. A list of
eTrust AC administrators appears or a message is written to confirm the
operation was successful stating:
No eTrust Access Control administrators found
Example
Commands 2–61
autosys_secure
Option [1] in the autosys_secure menu lets you enter an administrative host,
name of the administrative host resource owner, and a host of where the autosys
PMDB resides. If the eTrust AC administrative host is to be created in the local
seosdb press Enter when prompted for the host of the autosys PMDB. A message
appears to confirm the eTrust AC administrative host was created.
Option [2] in the autosys_secure menu lets you enter an administrative host, and
a host of where the autosys PMDB resides. If the eTrust AC administrative host
is to be deleted from the local seosdb press Enter when prompted for the host of
the autosys PMDB. You will be prompted to confirm this action, and a message
appears to confirm the eTrust AC administrative host was deleted.
Option [3] in the autosys_secure menu lets you enter a host of where the autosys
PMDB resides. If the eTrust AC administrative hosts to be displayed reside in the
local seosdb press Enter when prompted for the host of the autosys PMDB. A list
of eTrust AC administrative hosts appears or a message is written to confirm the
operation was successful stating:
No eTrust Access Control administrative hosts found
Option [4] in the autosys_secure menu lets you enter an administrative host, the
names of all the administrators to be authorized (comma-separated), and a host
of where the autosys PMDB resides. If the authorizations to the eTrust AC
administrative host are to be added into the local seosdb press Enter when
prompted for the host of the autosys PMDB. A message appears to confirm the
users have been granted access to administer from an eTrust AC administrative
host.
Option [5] in the autosys_secure menu lets you enter an administrative host, the
names of all the administrators to remove authorization (comma-separated), and
a host of where the autosys PMDB resides and a host of where the autosys
PMDB resides. If the authorizations to the eTrust AC administrative host are to
be removed from the local seosdb press Enter when prompted for the host of the
autosys PMDB. You will be prompted to confirm this action, and a message
appears to confirm that the user authorizations to the eTrust AC administrative
host were removed.
Commands 2–63
autosys_secure
Showing All Administrators who can Administer from an eTrust AC Administrative Host
Option [6] in the autosys_secure menu lets you enter an administrative host and
a host of where the autosys PMDB resides. If the users authorized to use an
eTrust AC administrative host to be displayed reside in the local seosdb press
Enter when prompted for the host of the autosys PMDB. A list of administrators
that can administer from the eTrust AC administrative host appears to confirm
the operation was successful.
Example
3. Press enter at the host owner prompt for no owner (or enter a user name)
To authorize a Windows user jane on the NEWYORK domain to use the eTrust
AC administrative Windows host capricorn.corp.com to administer eTrust
policies in the autosys@taurus PMDB using autosys_secure (assumes eTrust
security has been enabled and as-control\SECADM execute rights have been
granted)
Option [1] in the autosys_secure menu lets you enter a remote subscriber, and a
host of where the autosys PMDB resides. If the eTrust remote subscriber is to be
created in the local seosdb press Enter when prompted for the host of the autosys
PMDB. A message appears to confirm the eTrust AC remote subscriber was
created.
Option [2] in the autosys_secure menu lets you enter a remote subscriber, and a
host of where the autosys PMDB resides. If the eTrust remote subscriber is to be
deleted from the local seosdb press Enter when prompted for the host of the
autosys PMDB. You will be prompted to confirm this action. Once confirmed, a
message appears to confirm the eTrust remote subscriber was deleted.
Commands 2–65
autosys_secure
Option [3] in the autosys_secure menu lets you enter a host of where the autosys
PMDB resides. If the eTrust AC remote subscribers to be displayed reside in the
local seosdb press Enter when prompted for the host of the autosys PMDB. A list
of eTrust AC remote subscribers appear or a message is written to confirm the
operation was successful stating:
No eTrust Access Control remote subscribers found
Example
This option is used to generate encrypted passwords for the Unicenter AutoSys
JM Adapter configuration files. For more information on how to generate these
passwords, see your Adapter documentation.
Options
-h Displays help. Use this option to get help on the autosys_secure command-line
options.
-q Specifies to run in quiet mode and not print any messages to the screen. When
run in quiet mode, autosys_secure will not print any error messages. You can,
however, check the return code to see if there were any run errors. To check the
return code, enter a command similar to the following:
echo %ERRORLEVEL%
-q
If autosys_secure is successful, the return value is 0; and if it is unsuccessful,
the value is 1.
-a Specifies to add a user ID and password. You must also supply the –u and –p
options.
-c Specifies to change an existing user password. You must also supply the –u, -o,
and –p options.
-d Specifies to delete an existing user password. You must also supply the –u and
-o options.
-u Specifies the Windows user whose password you are entering. Windows user
user@host_or_domain names can be from 1 to 20 characters in length and can contain all characters
except the following:
*[]+:;“<>.,?/\|
-o old_password Specifies the password for an existing user. If you are changing a password or
deleting a user ID and password, you must supply this option. If the password
is NULL, enter NULL.
-p password Specifies the password for the user@host_or_domain that you want entered in
the database. If you are adding a user or changing a password, you must
supply this option. Windows passwords can be a maximum of 14 characters in
length. Passwords are case-sensitive and can contain any character except a
space. NULL passwords are accepted. To specify a NULL password, enter
NULL.
- editu Specifies that the user@host_or_domain that you wish to add, delete, or change
is a superedit user. This option is used along with the –a, -d, or –c options.
- execu Specifies that the user@host_or_domain that you wish to add, delete, or change
is a superexec user. This option is used along with the –a, -d, or –c options
- host Used only for the –editu/-execu with –c option. Specifies a change in the
host_or_domain for an existing user@host_or_domain that you entered in the
database. A NULL host_or_domain is accepted. To specify a NULL
host_or_domain, enter NULL.
Commands 2–67
autosys_secure
Example
autotimezone
Function
Syntax
autotimezone [-a entry_name value] [-c entry_name value]
[-t timezone_name] [-d entry_name] [-q entry_name | sql_pattern]
[-l]
Description
autotimezone lets you query the timezones table, and add and delete timezones
table entries. The timezones table contains entries that you can specify in a job
definition using the timezone attribute. The timezones table maps cities and
common aliases to valid POSIX TZ environment variables. The table contains
entries for all the common time zones that are recognized by most operating
systems, as well as many cities in the world.
The timezones table has three entry “Types,” Zone, Alias, and City, as shown in
the following excerpt from the timezones table:
Commands 2–69
autotimezone
All “Alias” and “City” Types are eventually resolved to “Zone” Types. The
“Zone” Types resolved to TZ Variables (in the Zone column) that correspond to
those recognized by the operating system for the machine on which the Event
Server is running. TZ variable syntax is compatible with Windows NT TZ
variables, but has been extended to allow full control over the day and time
that daylight saving time changes occur. If the time zone specification in a job
definition is not a TZ variable, the timezones table will be read multiple times
until it resolves to a TZ variable. For example, assume a job definition included
the attribute timezone:Berlin. Berlin would be resolved to Europe/Berlin the
first time the table is read. The second time the table was read, Europe/Berlin
would be resolved to MET, which is a TZ variable. If a time zone is not resolved
within five lookups, it is considered invalid and the job specifying the time
zone will fail.
The timezones table is complete and accurate and should not need modification.
However, the syntax of TZ variables is provided in the following section if you
want to add or modify entries in the timezones table.
Important! If you change the timezones table, be sure you do not change or
delete entries that are used by pre-existing STARTJOB and other events that
were scheduled using the old timezones table.
All “Alias” and “City” Types are eventually resolved to “Zone” Types. The
“Zone” Types resolved to TZ Variables (in the Zone column) that correspond to
those recognized by the operating system for the machine on which the Event
Server is running. For details on the format of the TZ variable, refer to your
system time, timezone, or environ man page.
When processing a job definition that includes a time zone, Unicenter AutoSys
JM first tries to resolve the specified time zone using the zones known to the
operating system. If it is not found there, Unicenter AutoSys JM looks up the
zone in the timezones table. If the time zone specification is not a TZ Variable for
example a “Zone” Type, the timezones table will be read multiple times until it
resolves to a TZ Variable. For example, assume a job definition included the
attribute timezone:Berlin. Berlin would be resolved to Europe/Berlin the first
time the table was read. The second time the table was read, Europe/Berlin
would be resolved to METS-1METD, which is a TZ Variable. If a time zone is not
resolved within five lookups, it is considered invalid and the job specifying the
time zone will fail.
Important! If you change the timezones table, make sure you do not change or
delete entries that are used by pre-existing STARTJOB and other events that
were scheduled using the old timezones table.
TZ Variable Syntax
std and dst An abbreviation of three or more characters representing standard and daylight
saving time for the time zone. Std is required and dst is optional. If dst is not
specified, it is assumed that the time zone does not observe daylight saving
time.
Commands 2–71
autotimezone
Offset Indicates the amount of time to be added to the local time to arrive at GMT. If
dst is specified but does not have an offset specification, it is assumed that
daylight saving time is one hour ahead of standard time.
Start and end Indicate when to change to and from daylight saving time, respectively. The
format is one of the following three types:
Jn
The Julian day n (1 <= n <= 365). Leap days are ignored, meaning December 31
is always day 365 and February 29 cannot be specified.
N
The zero-based Julian day n (0 <= n <= 365). Leap days are counted.
Mm.n.d
Specifies that the time change occurs on the nth occurrence of a particular day
of a specific month (for example, the first Sunday in April). January is month 1,
and Sunday is day 0. When n is 5, it means the last occurrence of that day in
month m. Valid value ranges are:
1 <= m <= 12
0 <= n <= 5
0 <= d <= 6
If start and end are omitted, United States daylight saving time defaults are
assumed. That is, start is the first Sunday in April and end is the last Sunday in
October.
Time Specifies the time of day that the change to daylight saving or standard time
occurs. The format is:
hh[:mm[:ss]]
Options
-a entry_name value Adds an Alias entry to the timezones table. An Alias entry associates a name
with a time zone. For example, you could alias “US/Mountain” to “MST.”
Entry_name is a string between 1 and 50 characters; and can include upper- or
lowercase letters, digits, slash ( / ), hyphen (— ), and underscore ( _ ). Value
must correspond to a time zone recognized by the operating system. Use spaces
to separate the entry_name and the value.
-c entry_name value Adds a City entry to the timezones table. A City entry is a type of Alias that
maps a city to a time zone. Entries added to the table through the –c argument
will display as type “City” in a listing of the timezones table. See the –a
argument, previously shown for a description of entry_name and value.
-t timezone_name Adds a time zone entry to the timezones table. A Zone entry must be of the
format of a valid POSIX standard timezone (TZ) environment variable.
-q entry_name | Queries the timezones table for the setting of a specific alias, city, or zone.
sql_pattern Queries are case insensitive, and you can use the wildcard character, percent
( % ) or the SQL underscore
Commands 2–73
autotimezone
Examples
2. The following command deletes the city named “San-Jose” from the
timezones table:
autotimezone –d San-Jose
3. The following command queries the timezones table for all entries beginning
with the letter “d”:
autotimezone –q d%
autotrack
Function
Syntax
autotrack [-D data_server:database | -D TNSname] [-u 0|1|2] [-l]
[-h|H] [-v] [-F “from_time”] [-T “to_time”] [-U user_name]
[-m machine] [-J job_name] [-t A|B|C|J|M|O|S|T]
Description
autotrack tracks changes to the database for example: job definition changes,
sendevent calls, and job overrides and writes this information to the database.
When you query for this information, autotrack prints a report to the screen, or
you can redirect the output to a file. Autotrack can track changes to job
definitions, both from JIL or the GUIs. Changes made directly to the database
through SQL commands cannot be tracked.
autotrack tracks changes to the database for example: job definition changes,
sendevent calls, and job overrides and writes this information to the database.
When you query for this information, autotrack prints a report to the screen, or
you can use standard UNIX file redirection to save the output to a file.
Autotrack can track changes to job definitions, both from JIL or the GUIs.
Changes made directly to the database through SQL commands cannot be
tracked.
■ Sites where multiple users have permission to edit job definitions or send
AutoSys events.
Start tracking, use the autotrack –u command to set the tracking level to 1 or 2,
depending on the amount of detail you want tracked. By default, autotrack is set
to level 0 (no tracking). Autotrack –l lists the current tracking level.
Note: Only the Exec or Edit Superuser can change the tracking level.
Commands 2–75
autotrack
Use the autotrack command with one or more query options (-J, -U, -m, -F, -T,
and –t) to request reporting on a specific job, user, machine, time window, or
event type. Typing autotrack with no arguments retrieves information on all
events, but omits the detail.
For example:
autotrack –u 0
jil –V none < whole_thing.jil
autotrack –u 1
Running archive_events will help prevent the database from filling up with
autotrack output. The archive_events –l num_of_days command archives
information from the audit_info and audit_msg tables older than the specified
number of days.
Options
-D Indicates the name of the Sybase or Microsoft SQL Server data server, and the
data_server: specific database within it, to be searched for the specified information.
database
Normally, autotrack consults the environment variables and the Administrator
configuration settings to determine to which database to connect. This option
enables autotrack to report on any Unicenter AutoSys JM Event Server on the
network.
Indicates the name of the Sybase data server, and the specific database within
it, to be searched for the specified information. Normally, autotrack consults
the environment variables and the configuration file to determine to which
database to connect. This option enables autotrack to report on any Unicenter
AutoSys JM Event Server on the network.
-D TNSname Indicates the TNS alias name of the Oracle data server to be searched for the
specified information. Normally, autotrack consults the environment variables
and the Administrator configuration settings to determine to which database to
connect. This option enables autotrack to report on any Unicenter AutoSys JM
Event Server on the network.
Indicates the TNS alias name of the Oracle data server to be searched for the
specified information. Normally, autotrack consults the environment variables
and the configuration file to determine to which database to connect. This
option enables autotrack to report on any Unicenter AutoSys JM Event Server
on the network.
Commands 2–77
autotrack
-u tracking_level Updates the level of detail that autotrack writes to the database, using Level 0,
1, or 2.
Level 0
Level 1
Tracks job, calendar, monitor, browser, and machine definition changes; job
overrides; and autosys_secure, autotrack, and sendevent calls. It condenses
each tracked event to a one-line summary.
Level 2
Tracks the same information as Level 1, but also writes the entire job definition
for overrides and job definition changes. Level 2 is very database intensive and
will significantly impair jil performance.
-v Verbose reporting.
-F "from_time" Reports changes or events that occurred from this date and time forward; the
format is “MM/DD/[YY]YY HH:MM.”
If you enter a two-digit year, Unicenter AutoSys JM saves the setting to the
database as a four-digit year. If you enter 79 or less, Unicenter AutoSys JM
prepends 20, and, if you enter 80 or greater, Unicenter AutoSys JM prepends
19.
-T "to_time" Reports changes or events that occurred up to this date and time; the format is
“MM/DD/[YY]YY HH:MM.”
If you enter a two-digit year, Unicenter AutoSys JM saves the setting to the
database as a four-digit year. If you enter 79 or less, Unicenter AutoSys JM
prepends 20, and, if you enter 80 or greater, Unicenter AutoSys JM prepends
19.
-J job_name Reports on the specified job. The percent (%) character may be used in the job
name as a wildcard.
Note: The underscore (_) may also be used as a wildcard to match exactly one
character. However, this can lead to some unexpected results when the job name
itself contains a (_) character. For example, specifying the job name “mon_%”
will select all jobs beginning with the string “mon”, such as mon_box, monet,
and so on. The SQL ESCAPE option is not supported for wildcards.
-t autotrack_type Reports on a specific event; an event can be one of the following types:
Commands 2–79
autotrack
Examples
The amount of detail written to the database (and, thus, available to query
against) is determined by the autotrack tracking level. Level 2 tracking provides
much more detail than does Level 1, as shown in examples 1 and 2.
If the autotrack tracking level had been set to 1, the output of this request
would resemble that shown following.
jane@taurus
11/21 10:04:54
job definition change
::::::::::::::::::::::::::::::::::::::::::::::::
jane@taurus
11/21 10:05:49
job definition change
command: date
::::::::::::::::::::::::::::::::::::::::::::::::
jane@taurus
11/21 10:06:29
sendevent issued
If the tracking level had been set to 2, autotrack would have written much
more detail to the database. Thus, the same query
autotrack -J NightlyReport -v
would produce a report that includes the entire job definition with changes
indicated by an asterisk.
A query without verbose reporting omits all indented detail; only the first
three lines for each event appears, as shown in the following:
jane@taurus
11/21 10:04:54
job definition change
::::::::::::::::::::::::::::::::::::::::::::
jane@taurus
11/21 10:05:49
job definition change
::::::::::::::::::::::::::::::::::::::::::::
jane@taurus
11/21 10:06:29
sendevent issued
3. View all the changes that occurred to the job “NightlyReport” after 1 a.m. on
November 12, 1997, enter:
autotrack -F "11/12/1997 01:00" -J NightlyReport
4. View all changes made by user “sue” over the weekend of November 16 and
17, 1997, enter:
autotrack -U sue -F "11/16/1997 01:00" -T "11/17/1997 23:59"
5. View all autosys_secure changes that occurred from the machine “gemini,”
enter:
autotrack -t A -m gemini
Commands 2–81
chase
chase
Function
Verifies that the jobs that the database indicates are running, are running. This
process also checks the associated Remote Agents.
Syntax
chase [-A] [-E]
Description
chase determines from the database, which jobs are in the STARTING or
RUNNING state, and on which machine. For each client machine, chase passes
to a Remote Agent a list of jobs that are supposed to be running there and
instructs the Remote Agent to verify that the processes actually are running. For
Command jobs running on a UNIX machine, the Remote Agent also checks for
the pid of the UNIX process.
Chase also verifies that the Remote Agent is running. When the event processor
service is started, chase is automatically invoked. Since chase uses the same
mechanism as the event processor to communicate with the Remote Agent
machines, it gives an accurate picture of the system’s state of health.
When verifying that the Remote Agent is running, chase checks that the
Remote Agent has a lock on the Remote Agent log file. (This is more reliable
than checking the Remote Agent’s process ID.)
Note: If you have disabled file locking on the client machine, chase will not be
able to verify if a Remote Agent is running. Therefore, ensure that the directory
specified by the AutoRemoteDir parameter in the configuration file is on a file
system that has file locking enabled.
When the event processor is started (by way of the eventor command), chase is
automatically invoked. Since chase uses the same mechanism as the event
processor to communicate with the Remote Agent machines, it gives an accurate
picture of the system’s state of health.
Note: The event processor does not have to be running while chase is run, but
the database must be available.
Errors detected by chase are sent to standard output. Optional arguments used
with chase further determine what actions to take when error conditions are
detected. The -A option sends an alarm to alert the user that problems were
found. If the -E option is specified, chase will force a FAILURE of any job that is
supposed to be running but is not. This will trigger an automatic restart of the
job if the n_retrys attribute has been defined. The Event processor must be
running for chase to automatically restart jobs.
If jobs are stuck in the STARTING state, chase will not automatically restart
them. Instead, it will write a message to standard output that manual
intervention may be required. Jobs stuck in the STARTING state should not be
automatically restarted—it is possible, due to network problems that the job may
be running or have run, and its state not yet communicated to the database. The
actual status of these jobs should be verified before they are restarted and their
status is changed.
Commands 2–83
chase
Run the chase process automatically, you can use Unicenter AutoSys JM to run
it as a job. The $AUTOSYS/install/data/chase.jil file contains the JIL
statements that will instruct Unicenter AutoSys JM to run chase every 10
minutes on the machine running the event processor (“charley,” in the example
following). You can change the specific parameters in this script to suit your
own environment, then submit it to the jil command.
The following are examples of JIL statements for automatically running chase.
# chase function
#
insert_job: chase
machine: charley
command: $AUTOSYS/bin/chase -A -E
date_conditions: yes
days_of_week: all
start_mins: 05,15,25,35,45,55
max_run_alarm: 5 # change if many jobs are running
term_run_time: 10 # ditto
# These output files can be changed
std_out_file: $AUTOUSER/out/chase.out
std_err_file: $AUTOUSER/out/chase.err
Options
-A Indicates that if chase detects any inconsistencies, for example; jobs that should
be running, but are not, it sends alarms to the RDBMSs.
-E Indicates that if a job and the job’s Remote Agent are not running on the client
machine, but the database indicates they should be, chase puts the job in
FAILURE status, triggering the job to be restarted if the job definition includes
the n_retrys attribute.
Note: If chase is run without any options, Unicenter AutoSys JM performs all
chase activities and writes the results to standard output. No alarms or job
restart events are sent.
Example
If a job is running longer than expected and you suspect it may have abnormally
ended (but still shows as “running”), you should run chase. To verify that the job
is running, receive an alarm if there is an inconsistency, and restart the job if
necessary, enter:
chase -A –E
Commands 2–85
chk_auto_up
chk_auto_up
Function
Syntax
chk_auto_up [-Q]
Description
chk_auto_up determines if the Event Server (database) and the event processor
are running. This facility is essential for locating the cause of problems, such as
jobs not being started at the scheduled time. The Event Server and the event
processor must both be running for a job to start.
For more information see the chapter “Administrator,” in the Unicenter AutoSys
Job Management for Windows User Guide, or the chapter “Configuring,” in the
Unicenter AutoSys Job Management for UNIX User Guide.
chk_auto_up will look for event processors both on the current machine and on
machines in the Network Machine List, which is specified on the Administrator
event processor screen.
chk_auto_up will look for event processors both on the current machine and on
machines in the EDMachines list, which is located in the configuration file
$AUTOUSER/config.$AUTOSERV.
Note: If you change the original list of machine names, you must stop and
restart the event processor in order for the EDMachines= entry to be updated.
Options
-Q Indicates that the command should output just the exit code without any
descriptive message. This makes the command useful for inclusion in shell
scripts. In this case, the return code is sufficient to indicate the status.
Commands 2–87
chk_auto_up
Return Codes
One of the return codes listed following is returned by chk_auto_up. If you omit
the -Q option, a descriptive message also will be displayed.
10 Event Processor up; Event Server name invalid, probably because the Event Server
(EventServer parameter in the configuration file) was correct when the event
processor was started, but was corrupted before you ran:
chk_auto_up.
11 Event Processor up; Event Server up.
20 Shadow Event Processor up; Event Server name invalid (see return code 10).
21 Shadow Event Processor up; Primary Event Processor not running; Event Server up.
22 Shadow Event Processor up; Primary Event Processor not running; Primary and
Dual-Event Servers up.
30 Primary and Shadow Event Processors up; Event Server name invalid (see return
code 10).
32 Primary and Shadow Event Processors up; Primary and Dual-Event Servers up.
50 Event Processor “not running” because could not connect to machine in the
EDMachines list in the AutoSys configuration file; No Event Server.
51 Event Processor “not running” (see return code 50); Event Server up.
52 Event Processor “not running” (see return code 50); Primary and Dual-Event Servers
up.
60 Event Processor “not running” because no machines listed in the EDMachines list in
the AutoSys configuration file; No Event Server.
61 Event Processor “not running” (see return code 60); Event Server up.
■ One or more of the following environment variables is not set or is set incorrectly:
AUTOSYS, AUTOSERV, AUTOUSER.
Example
To check that the database and Event Processor are up and to view the results on
your monitor, enter:
chk_auto_up
Commands 2–89
chk_cond (SP)
chk_cond (SP)
Stored Procedure.
Function
Prints diagnostics if a job has starting conditions based on another job that does
not exist.
Syntax
chk_cond job_name
Description
The chk_cond (SP) prints a report containing diagnostics about a job having
starting conditions that are based on another job that does not exist.
chk_cond is supported for Sybase and Microsoft SQL Server databases only.
Options
job_name Specifies the name of the job against which diagnostics should be run. If
job_name is not specified, the stored procedure will be run against all jobs.
Example
To print out diagnostics for all jobs in a Sybase data server, enter:
1> chk_cond
2> go
Note: You can also use the chk_cond stored procedure with a Microsoft SQL
Server database, using the ISQL/w graphical query interface.
Commands 2–91
clean_files
clean_files
Function
Syntax
clean_files -d days
Description
The clean_files command deletes old Remote Agent log files. It performs this
task by searching the database for all machines which have had jobs started on
them, then sending a command to the Remote Agent on that machine to purge
all remaining log files from the machine’s Remote Agent Log directory
(specified during the installation process or in the Local Agent Logging
Directory field of the Administrator Remote Agent screen).
Remote Agent log files are deleted automatically only if the job completed
normally, and if the Clean Temporary Files box is checked on in the
Administrator Event Processor screen.
Remote Agent logs for failed jobs are not deleted, and these files can take up
valuable disk space. Therefore, we recommend that you run the clean_files
command daily, as part of the daily Database Maintenance cycle, which you can
set up in the Administrator Event Processor screen.
The clean_files command deletes old Remote Agent log files. It performs this
task by searching the database for all machines which have had jobs started on
them, then sending a command to the Remote Agent on that machine to purge
all remaining log files from the machine’s Remote Agent Log directory
(specified by AutoRemoteDir in the configuration file).
Remote Agent log files are deleted automatically only if the job completed
normally, and if the CleanTmpFiles parameter in the configuration file specifies
that the log files be deleted at the end of each job.
Remote Agent logs for failed jobs are not deleted, and these files can take up
valuable disk space. Therefore, we recommend that you run the clean_files
command daily, as part of the daily DBMaint cycle.
Note: If you are experiencing problems running jobs successfully, the Remote
Agent log files are very useful diagnostic tools. In this case, you should not run
clean_files, or remove the Remote Agent log files using any other method, until
the problem has been diagnosed and resolved.
Options
-d days Specifies that log files older than the number of days will be removed.
Note: This option is only effective on NTFS file systems. On other file systems,
which do not store file timestamps (For example: FAT), all Remote Agent log
files are removed.
Example
To start clean_files and delete all Remote Agent log files older than 1 day, enter:
clean_files -d 1
Commands 2–93
cron2jil
cron2jil
Function
Syntax
cron2jil -f crontab_file [-d output_directory] [-i include_file] [-m machine] [-p
prefix]
Description
When cron2jil reads a crontab file, it assigns job names by combining the base
name of the job’s command and the line number of the file. For example, the
following crontab entries would result in the job names “cp_1” and “mail_2”
respectively.
>>0,59 0,23 * * 0,6 /bin/cp /etc/passwd /etc/passwd.bak
>>0,59 * * * 0,6 /usr/ucb/mail root@support1 < /tmp/errorLog
After translation, cron commands involving pipes and I/O redirection perform
just as they did in the cron environment. If run calendars are created, cron2jil
only generates calendars with a one year duration. After conversion, pipe and
I/O redirections may not take full advantage of the fault tolerance mechanisms
of AutoSys. For example, the exit code of a failed command in a pipe may not
result in the failure of the complete command expression. Because of this
behavior, translated JIL scripts should be edited and pipes should be split into
separate jobs with the appropriate conditions and job control. With this
approach, problems can be detected and reported at the point of failure.
Cron2jil does not generate JIL files for jobs that are defined in crontab to start
every minute; for example with an asterisk (*) specified in the first field of the
cron listing. In the environment, this is a special case and should be remedied by
using a starting condition for the job that is the successful completion of the job
itself.
Note: Once any *.jil or *.cal files are generated, you must submit these files to
the database using the jil and the autocal_asc commands, respectively.
Options
-d output_directory Specifies the directory to which the *.jil and *.cal files should be written. The
default is the current working directory.
-i include_file Specifies the name of a file containing JIL statements that are to be included in
every generated *.jil file. This file must be created before the conversion, and it
can contain any default JIL statements.
-m machine Specifies the name of the machine on which the translation should occur. If no
machine is specified, the default is “localhost.”
-p prefix Specifies a prefix that should be inserted before each job’s name. For example, if
a prefix of “AUTO” is specified, the jobs cited in the example previous would
have the following names: “AUTOcp_1” and “AUTOmail_2.”
Example
cron2jil -f daily
Commands 2–95
dbstatistics
dbstatistics
Function
Syntax
dbstatistics
Description
■ For Sybase only: dbstatistics recompiles stored procedures in the event, job,
and job_status tables by invoking the Sybase Transact-SQL command
sp_recompile.
■ dbstatistics runs the dbspace command to check the available space in the
database. dbspace prints a summary of the free space versus the used space
in the database. If the amount of free space is insufficient, dbspace issues
warning messages and generates a DB_PROBLEM alarm.
Note: If you use an Oracle database, running DBMaint may report that your
database is close to full when this is not the case. This can occur because
DBMaint calculates how much space is allocated for extents not the number of
bytes that are in use. The extents may be nearly empty, but DBMaint reports the
whole extent as used space.
■ dbstatistics calculates and updates the average job run statistics in the
avg_job_run table. The old data is overwritten with the new data. The
update statistics command returns either a 0 or 1; 0 indicates success and 1
indicates failure.
eventor
Function
Syntax
eventor [-f] [-n] [-q][-G] [-M shadow_machine]
Description
Use the eventor command to bring up the event processor (and, optionally, the
Shadow Event Processor), also referred to as the “event demon.” eventor runs
in the background, by default. It first makes sure that another Event processor
of the same instance is not running on the same machine as this instance (as
determined by the $AUTOSERV variable), unless two event processors are
specified in the configuration file.
It then runs chase, which inspects the database to determine which jobs are
supposed to be running, and then checks each machine to verify that the jobs are
there. If problems are detected, chase sends alarms or failure events, depending
on the options specified, for any missing jobs. If the missing jobs can be
restarted, they are automatically restarted.
The eventor -M command brings up the Primary and the Shadow Event
Processor (which takes over if the Primary Event Processor machine fails).
If the event processor has been down for a long period of downtime, you can
start it in Global AutoHold mode by specifying the -G option. This prevents the
system from being flooded at once with numerous jobs, which were scheduled to
run during the downtime.
For more information see the section “High-Availability Option: Shadow Event
Processor,” in the chapter “Introduction,” in the Unicenter AutoSys Job
Management for UNIX User Guide.
Commands 2–97
eventor
Log Files
By default, eventor executes the tail -f command against the log file. This tail is
useful for monitoring the execution of the event processor, particularly when
there are problems with its startup. For example, if the machine from which
eventor is issued does not have a valid license, the event processor will not start.
The only indication that this condition exists is a message output by the Event
Processor in its log file. To exit the tail command, use Ctrl+C in the window
displaying the event processor log.
Options
-f Specifies that the event processor should run in the foreground, and all of its
output should be sent to the display from which the command was issued.
Note: The -f option is not recommended for production use. The default
behavior is to run the Event processor in the background, with all output going
to the $AUTOUSER/out/event_demon.$AUTOSERV file.
-n Specifies that eventor is not to run the chase command on startup. The default
behavior is to run the chase -A -E command. The chase command inspects the
database to find out what jobs are supposed to be running, then it checks each
machine to verify that the jobs are there. If there are any problems, chase sends
alarms, changes the missing jobs’ states to FAILURE, and, if conditions permit,
causes the missing jobs to be restarted.
-q Specifies that eventor should run in quiet mode, meaning that after the event
processor has been started, eventor should not execute the tail -f command on
the event_demon log file.
When Global AutoHold is on, the following message appears after every
timestamp:
If Global AutoHold is on, you cannot take a job OFF_HOLD through the
Operator Console or the sendevent command. The only way to start a job when
Global AutoHold is on is with the FORCE_STARTJOB event. When sent, this
event will override the AutoHold mode.
If you start a Shadow Event Processor with the -G flag, the Shadow Event
Processor will also be in Global AutoHold mode.
Turn off Global AutoHold, you must shut down the event processor, then start it
up again without the -G flag.
No Options Set This is the recommended way to bring up the event processor. All restart
checks are performed, alarms are sent, and output is recorded in the log file.
Note: Do not attempt to start the event processor by invoking the event_demon
binary at the command line. The eventor script is required to properly check and
configure the environment for the event processor.
Commands 2–99
eventor
Examples
2. To start the Event Processor on the local machine, and a Shadow Event
Processor on the machine named “jupiter,” enter:
eventor -M jupiter
jil
Function
Runs the Job Information Language (JIL) processor to add, update, and delete
jobs, machines, monitors, and reports. Also used to insert one-time job override
definitions.
Syntax
jil [-q] [-S autoserv_instance] [-V none | job | batch]
Description
The jil executable is the language processor for the Job Information Language
(JIL). Using JIL (the language itself), you can define and update jobs, monitors,
reports, and machines. The jil command can be used in one of two ways:
A JIL file contains a sub-command such as insert_job and a set of attributes for
that job, in a specific format. The complete syntax rules are defined following.
The JIL sub-commands listed in the following table are used to create, update,
delete, or override a job definition.
Sub-command Action
insert_job Add a new job.
delete_box Delete this box job, and recursively delete all the jobs
contained in the box.
Commands 2–101
jil
Rule 1
sub_command: job_name
where:
Rule 2
attribute_keyword: value
where:
Rule 3
Multiple attribute statements can be entered on the same line; however, they
must be separated by at least one space.
Rule 4
A box that contains jobs must be defined before the jobs can be placed in it.
Rule 5
Legal value settings can include any of the following characters: upper and
lowercase letters, numbers, colons (if the colon is escaped), and the “at”
symbol(@).
Rule 6
Any colons used in an attribute statement’s value setting must be escaped, since
JIL parses on the combination of keyword followed by a colon. For example, to
specify the time to start a job, specify “10:00.” The colon may also be escaped
with a preceding backslash (\), as in 10\:00.
Rule 7
■ An entire line can be commented by placing a pound sign (#) in the first
column.
■ The C programming syntax used for beginning a comment with “/*” and
ending it with “*/” can be used; this allows comments to span multiple lines.
The following is an example:
/* this is a comment */
One of the primary advantages of using JIL is the ability to use the UNIX tools
that are available for file manipulation that create and control AutoSys job
definitions. For example, you run the following command on every
workstation:
rm /tmp/stuff/*
Then, it would be far simpler to create a “generic” JIL template (text file), and
copy it for each machine, changing only the machine attribute of the job. In fact,
you could iteratively copy the template to a temporary file, replacing the
machine name, and redirecting the temporary file into jil.
Commands 2–103
jil
Options
-q Specifies that jil should be run in “quiet” mode and that it should only output
error messages. This is useful when entering a large number of jobs, so that
errors can be easily seen. The default is to also output status messages,
indicating the success or failure of the JIL subcommands. This information is
very useful and should typically be allowed to print out.
-S autoserv Specifies the three-character instance name, for example; ACE, (and therefore
_instance the RDBMS) to which to apply the definitions. If not specified, jil will use the
value of the environment variable named %AUTOSERV%.
Specifies the three-character instance name, for example; ACE, (and therefore
the RDBMS) to which to apply the definitions. If not specified, jil will use the
value of the environment variable named $AUTOSERV.
-V none | job | batch Specifies whether or not the JIL processor should verify that jobs specified in
the job dependency condition for the job actually exist in the AutoSys database.
By default, the JIL processor always performs this operation on a job-by-job
basis, when jobs are submitted to the database. You can use this option to
bypass this behavior by using the none or batch arguments. The none option
does not perform any job dependency verification. The batch option checks the
database after the JIL file has been entirely processed. The job option checks the
database on a job-by-job basis; this is the same as not using the –V option.
When you use this option, the jobs specified in job dependencies that do not exist
in the AutoSys database are reported to standard output. The display will look
something similar to the following:
________________________________________________________
Insert/Updating Job: JobA
*** WARNING: The Following Jobs are referenced in the ***
Conditions for this Job, YET are not defined!
1) JobC
Database Change WAS Successful!
________________________________________________________
Examples
1. To redirect a text file named “job1” containing JIL statements into jil, enter:
jil < job1
2. To redirect a text file named “job1” containing JIL statements into jil and
prohibit the JIL processor from verifying the existence of specified jobs in its
job dependencies, enter:
jil < job1 -V none
Commands 2–105
job_depends
job_depends
Function
Syntax
job_depends [-c | -d | -t] [-J job_name] [-F from_date/time][-T to_date/time]
[-L print_level] [-D data_server:database | -D TNS_alias_name]
Description
Options
-c Current Condition Status. Prints out the current state of a job and the names of
any jobs that are dependent on this job. The information from this option is
similar to that displayed in the Job Dependencies dialog, which you can open
from the Scheduler Console.
Current Condition Status. Prints out the current state of a job and the names of
any jobs that are dependent on this job. The output of this option is similar to
that displayed in the Starting Conditions area of the Job Activity Console.
-d Dependencies Only. Prints out the starting conditions for a job; no indication of
the current status of the job is provided. For box jobs, jobs inside the box are
shown hierarchically. The -L option controls how many levels of nesting are
displayed.
-t Time Dependencies. Prints out the starting conditions for a job; however, the
top level of jobs (or boxes) that are reported are limited to those that will start
within the time period specified by the job or box’s date conditions. In the event
that a box will satisfy those date conditions, all of the jobs within it will also be
printed. The level of nesting displayed can be controlled with the -L option.
job_depends -t does not calculate all complex job dependencies when reporting
on the jobs and boxes that are scheduled to run. For example, “JobB” may have a
date condition and be dependent on “JobA.” The date conditions for “JobB” may
be met for a given day, while those for “JobA” are not. As a result, “JobA” will
not run, and neither will “JobB.” However, “JobB” will appear on the report
produced by job_depends. For this reason, the starting conditions are also
printed; for example next to “JobB” would be the condition:
success(JobA).
-J job_name Indicates the job on which to report, where job_name is the name of the target
job. To report on all jobs, enter the word ALL for the job_name. Wildcards are
also supported, using the percent symbol (%). For example, to print all jobs that
have ‘Backup’ in their job name, enter:
%Backup%
Note: The underscore (_) character may also be used as a wildcard to match
exactly one character. However, this can lead to some unexpected results when
the job name itself contains a (_) character. For example, specifying the job name
“mon_%” will select all jobs beginning with the string “mon,” such as mon_box,
monet, and so on.
-F from_date/time Indicates the report start date and time, where from_date/time is the date and
time of the first job in the report. This option is used with the -T option only.
The format is MM/DD/[YY]YY HH:MM.
If you enter a two-digit year, Unicenter AutoSys JM saves the setting to the
database as a four-digit year. If you enter 79 or less, Unicenter AutoSys JM
prepends 20, and, if you enter 80 or greater, Unicenter AutoSys JM prepends 19.
-T to_date/time Indicates the report end date and time, where to_date/time is the date and
time of the last job in the report. This option is used with the -F option only.
The format is MM/DD/[YY]YY HH:MM. If this option is not specified,
job_depends will search without limitation into the future.
If you enter a two-digit year, Unicenter AutoSys JM saves the setting to the
database as a four-digit year. If you enter 79 or less, Unicenter AutoSys JM
prepends 20, and, if you enter 80 or greater, Unicenter AutoSys JM prepends 19.
Commands 2–107
job_depends
-L print_level Indicates the print level for the report, where print_level is any valid numeric
value specifying the number of levels of nesting to display for a box job. This
option is used with the -d and -t options only.
For example, a print_level of 2 indicates that information for the specified box
job and two levels of jobs within that box, should be shown. If you want to
report on the outer most box alone, specify “0.” The default is to list all levels
within the box.
-D data_server: Indicates the name of the Sybase or Microsoft SQL Server data server, and the
database specific database within it, to be searched for the specified information.
Normally, job_depends consults the environment variables and the
Administrator configuration settings to determine to which database to
connect. This option enables job_depends to report on any Unicenter AutoSys
JM Event Server on the network.
Indicates the name of the Sybase data server, and the specific database within
it, to be searched for the specified information. Normally, job_depends consults
the environment variables and the configuration file to determine to which
database to connect. This option enables job_depends to report on any
Unicenter AutoSys JM Event Server on the network.
-D TNS_alias_ Indicates the TNS alias name of the Oracle data server to be searched for the
name specified information. Normally, job_depends consults the environment
variables and the Administrator configuration settings to determine to which
database to connect. This option enables job_depends to report on any
Unicenter AutoSys JM Event Server on the network.
Indicates the TNS alias name of the Oracle data server to be searched for the
specified information. Normally, job_depends consults the environment
variables and the configuration file to determine to which database to connect.
This option enables job_depends to report on any Unicenter AutoSys JM Event
Server on the network.
Example
This report shows that “jobX” has no date or starting conditions, but another
job, “jobY” is dependent on it.
This report shows that even though the date conditions have been met for
“jobA,” it is in the INACTIVE state because its starting conditions have not
been met. An “F” next to an atomic condition indicates that the atomic
condition has not been satisfied (F = False, T = True).
Commands 2–109
job_depends
3. To display a report on the box job named “job_bxA” showing all the nested
levels of jobs and boxes within this job, you would enter the following
command:
job_depends -d -J job_bxA
In this report, all the nested jobs and boxes within “job_bxA” are shown. If a
job has a date condition or any atomic starting conditions, these are
indicated. Starting conditions are abbreviated as follows: s = SUCCESS, f =
FAILURE, d = DONE, t = TERMINATED, and n = NOTRUNNING.
4. To display a report on jobs that are scheduled to run on New Years day, you
would enter the following command:
job_depends -t -J ALL -F "01/01/1998 00:00"
-T "01/02/1998 00:00"
The -F (from date/time) and -T (to date/time) options allow you to specify
the date and time for the beginning and end of the report. You would see a
report similar to the following displayed to standard output:
________________________________________________________________
Job Forecast Report
From: 01/01/1998 00:00:00 To: 01/02/1998 00:00:00
Job Name NextStart Atomic Start Conditions
_________________________________________________________
job1 01/01/191 12:05 -------
job_bxA ------- d(job1)
job2
job_bxB ------- -------
job_bxC ------- -------
job3 ------- -------
job4 ------- -------
job5 ------- -------
job6 ------- -------
job7 ------- s(job5)
s(job6)
job8 01/01/1998 02:00 -------
job_bxD ------- d(job8)
job_bxE ------- -------
job9 ------- -------
job10 ------- -------
job11 ------- -------
job12 ------- -------
job13 ------- -------
job14 ------- s(job11)
s(job12)
s(job13)
job15 01/02/1998 04:00 -------
job_bxF ------- d(job15)
job_bxG ------- -------
job16 ------- -------
job17 ------- -------
job18 ------- -------
job19 ------- -------
job20 ------- s(job18)
s(job19)
________________________________________________________________
Commands 2–111
job_delete
job_delete
Product Binary
Function
Syntax
Job_delete {-N num_of_days}
Description
The job_delete binary is used to clean the job_delete table during database
maintenance. When a job is deleted either for jil or jobdef, an entry is inserted
into the job_delete table consisting of the time and user who deleted the job.
Job_delete will remove all the entries when the time is as old as or older than the
date specified.
The num_of_days value indicates the number of days of information that should
be left in the database. If a row in the table is as old as or older than the
num_of_days value, it will be deleted.
Options
-N num_of_days Specifies that records older than the num_of_days are to be deleted from the
job_delete table.
Example
job_delete –N 7
This example will remove all entries in the job_delete table that were inserted
seven or more days before the date time of Event Server A.
monbro
Function
Syntax
monbro -N name [-P poll_frequency] [-D data_server:database| -D TNS_alias_name]
[-q]
Description
monbro runs a monitor or report (browser) that has already been defined,
either using jil or the Monitor/Browser Editor.
The definition of the monitor or report to be run must reside on the database for
the instance you are accessing. monbro can connect to any database that your
instance is configured to use. By default, it will inspect the environment
variables %AUTOSYS%, %AUTOUSER% and %AUTOSERV% to determine
which database to connect to. This default can be overridden by using the -D
option.
When you define a monitor using the Monitor/Browser Editor, you define the
instance to which it should connect in the New Monitor/ Browser dialog, which
you open from the New option on the File menu.
For more information see the Unicenter AutoSys Job Management for Windows
User Guide, or the Unicenter AutoSys Job Management for UNIX User Guide.
Commands 2–113
monbro
monbro runs a monitor or report (browser) that has already been defined,
either using either jil or the GUI.
The definition of the monitor or report to be run must reside on the database for
the instance you are accessing. monbro can connect to any that your instance is
configured to use. By default, it will inspect the environment variables
$AUTOSYS, $AUTOUSER and $AUTOSERV to determine which database to
connect to. This default can be overridden by using the -D option.
Options
-N name Specifies the name of the monitor or report (browser) to be run. The percent (%)
character may be used in the name as a wildcard; or you can enter ALL for all.
-P poll_frequency Applies to monitors only, and indicates the time interval (in seconds) to sleep
between polls of the database. The default is 10 seconds.
-D Specifies the name of the Sybase or Microsoft SQL Server data server, and the
data_server specific database within it, from which to retrieve events and the monitor or
:database
report definition. The default behavior is to inspect the environment variables
and Administrator configuration settings to determine which data server and
database to use.
Specifies the name of the Sybase data server, and the specific database within it,
from which to retrieve events and the monitor or report definition. The default
behavior is to inspect the environment variables and configuration file to
determine which data server and database to use.
-D TNS_alias_ Specifies the TNS alias name of the Oracle database from which to retrieve
name events and the monitor or report definition. The default behavior is to inspect
the environment variables and Administrator configuration settings to
determine which database instance to use.
Specifies the TNS alias name of the Oracle database from which to retrieve
events and the monitor or report definition. The default behavior is to inspect
the environment variables and configuration file to determine which database
instance to use.
Examples
To run a monitor called “mon1” which is defined in the default database, enter:
monbro -N mon1
Commands 2–115
record_sounds
record_sounds
Function
Syntax
record_sounds AutoSys_password
Description
This utility records sounds for playback in monitors. It stores the sounds in files
located in the $AUTOUSER/sounds directory.
It assumes that the workstation you are on is equipped for sound, has a
microphone plugged in, and is set up correctly.
As of this printing, the sound facility is supported on Solaris, and SGI platforms.
Record_sounds is an interactive tool that will record sounds for jobs (the Job
Names) or System Phrases (for example; RUNNING or SUCCESS). The
recordings for all System Phrases come with Unicenter AutoSys JM. However,
we recommend that the person who records the Job Names should also re-record
the System Phrases.
Record_sounds inspects the database to get lists of Job Names and System
Phrases. You will be prompted for each sound to record.
Sounds are stored in various files in the $AUTOUSER/sounds directory. The file
name for these files is constructed using the Job Name or the System Phrase
name. For example, the sound file for the job “DB_Backup” is stored in the
$AUTOUSER/sounds/DB_Backup file, and the MINRUNALARM System
Message is stored in the $AUTOUSER/sounds/MINRUNALARM file. If you
have a favorite pre-recorded sound that you want to use, simply copy it into the
appropriate file.
If you have a favorite pre-recorded sound you want to use, you can simply copy
it into the proper file. record_sounds gets lists of jobs names and system phrases
from the database. The sound clips themselves are stored in files in the
$AUTOUSER/sounds directory. When you run the command, you are prompted
to decide which sounds you will record.
Record Sounds:
To record sounds, follow these steps:
1. Choose whether to record job names, system phrases, or one sound only. If
you choose one sound, you must supply the file name. If you choose to
record job names or system phrases, you are prompted by the following
message:
Record only those sounds that are missing? y/n
If you answer y, you will then be prompted to record those sounds that are
not already in the $AUTOUSER/sounds directory. Selecting this option is
useful for maintaining a complete set of sounds when new jobs are added.
If you answer n, you will be prompted to record all of the sounds until you
finish or exit.
2. At each prompt, you are asked to click Enter to start recording, then speak or
play a sound into the microphone, and click Enter to end the recording.
Example
When recording sounds, be sure the workstation you are on is equipped for
sound, has a microphone plugged in, and is set up correctly, then, enter:
record_sounds
Commands 2–117
sendevent
sendevent
Function
Syntax
sendevent -E event [-S autoserv_instance] [-A alarm] [-J job_name]
[-s status] [-C comment] [-P priority] [-M max_send_trys]
[-q job_queue_priority] [-T "time_of_event"]
[-G "global_name=value"] [-k signal_numbers] [-u]
Description
The event that is sent is written to the database, which the event processor is
continually polling. The event processor reads and processes the event.
The Send Event Tool can also be used to send an event. You access this tool
from Scheduler Console and Alarm Manager.
The Send Event dialog can be used to send an event. You access this dialog by
clicking Send Event in the Job Activity Console.
Note: To issue a sendevent on a job, you must have execute permission on that
job. Only alarms, comments, and set global can be sent without regard to
permissions.
Options
-E event Specifies the event to be sent. This option is required. Any one of the following
events may be specified:
STARTJOB
Start the job specified in -J job_name if the starting conditions are satisfied. A
STARTJOB event ignores time and date conditions, but it does consider other
start conditions, such as dependencies on other jobs. This command cannot be
used on jobs in boxes. Jobs in boxes inherit the starting conditions of the box they
are in; as a result, they will be started when that box is started.
KILLJOB
Kill the job specified in -J job_name. The action depends on one of the following
job types:
■ Command Jobs
If the job is running on UNIX, this kills the process that is currently running
and all the processes that it has spawned; for example: the process group. It
will not kill orphan processes. It sends a signal to the process, waits five
seconds, then sends a second signal, if the process is still there. The default kill
signals to be sent are specified in the Kill Signals field in the Administrator
Event Processor screen. This enables the application programmer to program
commands that will react intelligently to the KILLJOB event. For UNIX
processes, specific signals can be specified, or default signals can be overridden
using the -k option.
Windows does not support the concept of process groups. If the job that
was launched was a *.exe, KILLJOB will kill the process specified in the
command definition. If the job being run is not a *.exe (for example,
*.bat, *.cmd, or *.com), AutoSys uses CMD.EXE to launch the job, and
KILLJOB will kill only the CMD.EXE process. The Job Status will be set
according to the return code of the killed CMD.EXE process. This status
can be any one of the following: SUCCESS, FAILURE, or TERMINATED.
Any processes that were launched by user applications or batch (*.bat)
files will not be killed.
Commands 2–119
sendevent
Note: Work around this KILLJOB limitation, you can use the
SEND_SIGNAL event. Your application must watch for a specified
semaphore signal and react accordingly, and you can use the
SEND_SIGNAL event to implement this behavior.
Kills the process that is currently running and all the processes that it has
spawned; for example; the process group. It will not kill orphan processes. It
sends a signal to the process, waits five seconds, then sends a second signal, if
the process is still there. The default kill signals to be sent are specified in the
configuration file with the KillSignals parameter, and typically the signals are
SIGINT and SIGKILL. This enables the application programmer to program
commands that will react intelligently to the KILLJOB event. For UNIX
processes, specific signals can be specified, or default signals can be overridden
using the -k option.
■ Box Jobs
Changes the status to TERMINATED. No more jobs within the box will
be started. Jobs that are already running will continue to run to
completion.
Kills the file watcher job and changes the status to TERMINATED.
DELETEJOB
Delete the job specified in -J job_name from the database. If the job is a box,
deletes the box and all the jobs in the box.
FORCE_STARTJOB
Do not force start a job in QUE_WAIT state because jobs in QUE_WAIT state
are already “started” and are waiting for machine resources to become
available to run. If you want a job in QUE_WAIT to start running
immediately, change the job queue priority to 0 (using the
CHANGE_PRIORITY event).
If a job fails inside a box and you fix the problem manually, use
FORCE_STARTJOB to rerun the job.
Note: If you force start a job, Unicenter AutoSys JM will start the job right away
on the machine specified in the job definition, regardless of the current load on
the machine or the job_load specified for the job.
JOB_ON_ICE
Puts the job specified in -J job_name “on ice.” When a job is placed on ice, it
effects downstream jobs dependent upon that job. For example, the starting
conditions for jobs downstream from “JobA,” which has been put “on ice,”
will evaluate as shown in the following table:
exitcode FALSE
JOB_OFF_ICE
Takes the job specified in -J job_name “Off Ice.” Jobs that are taken “Off Ice”
will not start until the next time their starting conditions are met.
JOB_ON_HOLD
Puts the job specified in -J job_name “On Hold.” When a job is “On Hold,”
it will not be started, and downstream dependent jobs will not run. A box
cannot successfully complete if a job within it is ON_HOLD. If the job is
already STARTING or RUNNING, you cannot put it ON_HOLD.
Commands 2–121
sendevent
JOB_OFF_HOLD
Takes the job specified in -J job_name “Off Hold.” If the starting conditions
are met, the job will be started.
CHANGE_STATUS
When you send a CHANGE_STATUS event, you are changing the status of
the job in the database; this event does not affect the current running of the
job. That is, if you change the status to running, the status is changed in the
database but the job is not run. You will have to change the status to a
termination state before the job can be run again.
STOP_DEMON
Stops the event processor service (event demon). This is the only way to stop
the event processor. This command does not stop the database.
Stops the event processor (event demon). This is the only way to stop the event
processor. This command does not stop the database.
CHANGE_PRIORITY
Changes the Job Queue Priority of the job specified in -J job_name to the
priority specified by the -q priority arguments. Queue priority is the relative
priority of all jobs in the queue. The lower the number, the higher the
priority; zero means to run the job right away. If the job has not been started,
priority is changed for the next run only. If the job has been started, and is in
a queue, priority is changed immediately.
COMMENT
ALARM
SET_GLOBAL
Sets a global variable. This event is sent with a high priority so the Event
Processor will process the variable before it is referenced by any jobs at
runtime. The -G ”global_name=value” option must be used with this event.
SEND_SIGNAL
Sends a signal to a running job. For processes running on UNIX systems, you
must use the -k signal_numbers and -J job_name options with this event. For
processes running on Windows, you must use the -k signal_name and -J
job_name options with this event.
On Windows NT, you can use the SEND_SIGNAL event to signal a specific
named semaphore. Then, you can program your application to watch for
and react to that semaphore signal.
-S autoserv Specifies the three-character instance, for example; ACE, to which the event
_instance should be sent. If not specified, sendevent will use the value of the environment
variable named %AUTOSERV%.
Specifies the three-character instance, for example; ACE, to which the event
should be sent. If not specified, sendevent will use the value of the environment
variable named $AUTOSERV.
-A alarm Specifies the name of the alarm to be sent. This option is only used when the
specified event is ALARM; it is required when using this event.
-J job_name Specifies the name of the job to which the specified event should be sent. This
option is required for all events except STOP_DEMON, COMMENT, ALARM,
or SET_GLOBAL.
Commands 2–123
sendevent
-s status Specifies the status to which the job specified in -J job_name should be changed.
This option is used only when the specified event is CHANGE_STATUS, which
requires this option.
Note: Changing the status to RUNNING does not cause the job to run. It only
changes the status of the job in the database. Changing the status of a box to
INACTIVE will cause all the jobs in the box to be changed also to INACTIVE.
For example, this option can be used to document why a KILLJOB event was
sent, in which case it is attached to the KILLJOB event and is viewable in an
autorep report. Or, it may be a stand-alone comment (when issued with the
COMMENT event), in which case it can be used to post a note to the event log.
For example, this option might be used to indicate a condition, which was
noticed by the operator, and is “viewable” by using the autosyslog utility.
-P priority Specifies the priority to be assigned to the event being sent. The value may be
from 1 to 1000, with 1 being the highest priority and 1000 the lowest. The
default value is 10. Assign a high priority if the event must be processed
immediately (for example, when attempting to place a job which is about to be
started on hold).
-M max_send_trys Specifies the maximum number of times sendevent will attempt to send the
event to the database. Any number of attempts may be specified. If all the
specified send attempts resulted in failure, sendevent will exit with an exit code
of “1.” The default is 0, meaning sendevent will try indefinitely.
-q job_queue_priority Specifies the new queue priority to be assigned to the job. This option is only
used, and is required, with the CHANGE_PRIORITY event. The priority must
be a numeric value from 0 to 99, with higher numbers indicating a lower
priority. A value of 0 signifies to start the job immediately.
-T "time_of_event" Specifies the date and time when the event should be processed. The format is
MM/DD/[YY]YY hh:mm, where hh denotes hours and must be from 0 to 23.
Double quotes are required as part of the specification. This is used to schedule
an event in the future. The default is to process the event immediately.
If you enter a two-digit year, Unicenter AutoSys JM writes the setting to the
database as a four-digit year. If you enter 79 or less, Unicenter AutoSys JM
prepends 20, and, if you enter 80 or greater, Unicenter AutoSys JM prepends 19.
-G Specifies the name and value of a global variable when a SET_GLOBAL event
"global_name=value" is sent. The global_name and the value can each be a maximum of 30 characters
(leading and trailing spaces in the value are ignored). Once a global variable is
set, it can be referenced by jobs at runtime using the syntax by the indicated job
attributes in the following table.
Delete a global variable from the database, set it with a value of DELETE, like:
Notes:
Global variables are stored in the database, they are not set in the environment.
Therefore, they cannot be referenced in the job’s profile.
Global variables are stored in the database, they are not set in the environment.
Therefore, they cannot be referenced in the default (etc/auto.profile) or the
job’s defined profile.
Commands 2–125
sendevent
-k signal_numbers or For processes running on UNIX, this argument specifies the signal number.
signal_name This option is only used with the SEND_SIGNAL or KILLJOB event. This
argument is required for the SEND_SIGNAL event. For KILLJOB events this
option overrides any KillSignals specified in the configuration file. The
signal_numbers value can contain a comma delimited list of signals to send to
the process. In this case, the Remote Agent will send the first signal, sleep for
five seconds, then send the next signal, and so forth. To send a signal to an
entire process group, place a minus sign (-) before the appropriate
signal_numbers values.
For processes running on Windows, this argument is used only with the
SEND_SIGNAL event, and it specifies the name of the semaphore that the
application is watching.
Windows does not support the concept of process groups, and thus the KILLJOB
event functions differently on Windows. Any processes that were launched by
user applications or batch (*.bat) files will not be killed; only the CMD.EXE
process will be killed. To work around this limitation, you can use modify your
programs to watch for an signal from an AutoSys job running on a Windows
machine, and you can implement this using the SEND_SIGNAL event.
-u Cancels the event specified in the -E event option. This option can be used only
for unprocessed events that are scheduled to be processed in the future. If no
time is specified with the -T option, all events satisfying the indicated criteria
(options) will be canceled. If multiple future events exist, the -T option can be
used to specify a specific event for cancellation.
Canceled events are not deleted from the database. Their status is changed, for
example: que_status=4, which prevents them from being processed.
Examples
4. To prevent a job called “lock_out” from running between the hours of 11:00
a.m. and 2:00 p.m., a pair of sendevent commands could be used to place it
on hold during that time. (These same sendevent commands could be placed
in a job that is run daily to perpetuate this condition on a regular basis.)
6. To stop the Event processor at 2:30 a.m. on November 9, 1997 (it is always a
good idea to attach a comment to this event), enter:
sendevent -E STOP_DEMON -T "11/09/1997 02:30" -C "stopped for upgrade"
The above command will change the job queue priority only for the next run
of the job.
Commands 2–127
sendevent
11. To send the Unix signal number 1 to a job named “RunData,” enter:
sendevent -E SEND_SIGNAL -J RunData -k 1
12. When running a job on Windows, you can program your application to
watch for a signal. More than one job can be programmed to watch for the
same signal. The following code example uses a thread to create and then
block on a semaphore named MyFirstSignal. This semaphore can then be
signaled using the sendevent SEND_SIGNAL command. Then, as shown in
the example program, the watchsem job watches for a signal on both the
MyFirstSignal and MySecondSignal semaphores. A second application,
such as a child process of the original job (application), could also watch
and react to these signals. To signal the jobs, use this sendevent command
from an Instance Command Prompt window:
sendevent -E SEND_SIGNAL -J watchsem -K MyFirstSignal
This is the example program, which you can compile using cl watchsem.c:
#include <windows.h>
/*Prototypes*/
void WatchForAutosysSignal(char *SignalName);
DWORD WINAPI WatchAutosysSignalThread(LPVOID Parm);
void main(void)
{
printf("This is your application running.\n");
printf("Call the WatchForAutosysSignal function\
with a name of a semaphore.\n");
WatchForAutosysSignal("MyFirstSignal");
printf("You can set up multiple watches if you choose.\n");
WatchForAutosysSignal("MySecondSignal");
printf("Go on about your application.");
Sleep(-1);
}
void WatchForAutosysSignal(char *SignalName)
{
HANDLE ThisThread;
DWORD tid;
char *SignalCopy;
/* Use this to pass in the signal name without referencing any */
/* global values */
SignalCopy=_strdup(SignalName);
ThisThread=CreateThread(NULL,0,WatchAutosysSignalThread,
(LPVOID)SignalCopy,0,&tid);
if (ThisThread==NULL)
{
free(SignalCopy);
printf("Failed to CreateThread for WatchAutosysSignalThread\
error %ld.\n",GetLastError());
return;
}
printf("Created thread for WatchAutosysSignalThread.\n");
if (!CloseHandle(ThisThread)) /*Drop the handle*/
printf("Failed to Close the thread handle error\
%ld.\n",GetLastError());
return;
}
DWORD WINAPI WatchAutosysSignalThread(LPVOID Parm)
{
HANDLE ThisSem;
DWORD dwrc;
char *SignalName;
SignalName=(char *)Parm;
printf("Beginning to wait for %s.\n",SignalName);
/* Autosys will Open the event semaphore and then call*/
/* PulseEvent to signal the semaphore and reset it to */
/* unsignaled. This way you can watch for the signal */
/* multiple times. If more than one application is waiting */
/* for the signal, make sure to create it with the */
/* ManualReset value set to TRUE. */
ThisSem=CreateEvent(NULL,TRUE,FALSE,SignalName);
if (ThisSem==NULL)
{
printf("Failed to create semaphore %s with error\
%ld.\n",SignalName,GetLastError());
return(0);
}
dwrc=WaitForSingleObject(ThisSem,INFINITE);
if (dwrc!=WAIT_OBJECT_0)
{
printf("WaitForSingleObject for %s failed with %ld and\
%ld.\n",SignalName,dwrc,GetLastError());
CloseHandle(ThisSem);
return(0);
}
printf("Received signal on %s.\n",SignalName);
CloseHandle(ThisSem);
printf("You may react to the signal in any way you choose.\n");
exit(0); /* In this case just kill the application */
}
Commands 2–129
sendevent (SP)
sendevent (SP)
Stored Procedure
Function
Syntax
sendevent ’event’, ’job_name’, ’status’, ’alarm’, ’time_of_event’, ’comment’
Description
The sendevent (SP) is a call made directly to the data server to execute a
sendevent command. To execute the procedure, you must be logged on to the
data server, and you must enter the command statement using the syntax
required by the target database. All options (fields) must be entered, even if they
contain no information.
This stored procedure only can be sent to the data server you are currently
logged on to. If you are running Dual-Event Servers, the event processor will
copy the event to the second Event Server before it is processed. If you are using
non-UNIX applications that can access the data server, they can also issue this
stored procedure.
Note: Since this procedure is done directly from the database, other database
actions can call this interface. For example, updates to tables can be configured to
generate the sendevent (SP) through “triggers” to initiate a job.
Important! Using sendevent (SP) bypasses the security feature for Execute
permissions on jobs.
Options
job_name Specifies the name of the job to which the specified event should be sent. If the
event is SET_GLOBAL, specify global_name=value instead of job_name.
status Use this option only when the specified event is CHANGE_STATUS; in this
case, this option is required. status specifies the status to which the job specified
in job_name should be changed.
alarm Use this option only when the specified event is ALARM; in this case, this
option is required. alarm specifies the name of the alarm to be sent.
time_of_event Specifies the date and time when the event should be posted. The format is the
same date and time format that is currently being used for the Event Server to
which the command is issued. If a null is input, the current date and time is
used.
comment Specifies a textual comment (up to 255 characters) to be attached to this event.
Examples
1. To immediately start a job named “test_job” on a Sybase data server that you
are currently logged onto, enter:
1> sendevent ’STARTJOB’,’test_job’,’’,’’,’’,’’
2> go
Note: You can also use the sendevent stored procedure with a Microsoft SQL
Server database, using the ISQL/w graphical query interface.
2. If you are currently logged onto an Oracle data server and want to change
the status of a job named “test_job” to INACTIVE on December 25, 1997,
with a textual comment, enter:
SQL> declare
2 rc int;
3 begin
4 rc := sendevent
(’CHANGE_STATUS’,’test_job’,
’INACTIVE’,’’, ’12:00:00 12/25/1997’,
’Reset for today’);
5 end;
6 /
3. To set a global variable named “Today” on a Sybase data server that you are
currently logged onto, enter:
1> sendevent ’SET_GLOBAL’,’Today=12/12/1997’,’’,
2> ’’,’’,’’
3> go
Commands 2–131
start_rcs
start_rcs
Function
Syntax
start_rcs
stop_rcs
Function
Syntax
stop_rcs
xql
Function
Provides direct access to the Sybase data server, allowing the user to query the
database itself.
Syntax
Description
xql is the supplied utility that accesses the Sybase data server from any
properly configured client. It can be used as an interactive interface to the data
server (like isql), as a command issued in an Instance Command Prompt
window, or in a batch file (batch mode) to send requests to the server and
output results.
xql also serves as a useful tool for determining whether or not the AutoSys
database is accessible at all, given the current configuration and state of the
environment variables. Often, when problems arise, these variables are not set
correctly, or the Sybase configuration files are not set up properly. xql can be
used to detect that situation; as a result, xql should not be overlooked as a
troubleshooting tool.
xql is the supplied utility that accesses the Sybase data server from any
properly configured client. It can be used as an interactive interface to the data
server (like isql), as a command issued at the UNIX command line, or in a shell
script (batch mode) to send requests to the server and output results.
xql also serves as a useful tool for determining whether or not the database is
accessible at all, given the current configuration and state of the environment
variables. Often, when problems arise, these variables are not set correctly, or the
Unicenter AutoSys JM or Sybase configuration files are not set up properly. xql
can be used to detect that situation; as a result, xql should not be overlooked as a
troubleshooting tool.
Commands 2–133
xql
Batch Mode
To execute xql in batch mode and have the results sent to standard output, you
specify either the -c option, the -f option, or redirect standard input into xql.
The -c option will read its SQL input from the command_string argument and
the -f option will read its SQL input from the file specified in input_file. Batch
mode is particularly useful for embedding SQL statements inside of batch files.
(An example is given following.) When using the -c option, you must enter
“go” to mark the end of the SQL statement.
To execute xql in batch mode and have the results sent to standard output, you
specify either the -c option, the -f option, or redirect standard input into xql.
The -c option will read its SQL input from the command_string argument and
the -f option will read its SQL input from the file specified in input_file. Batch
mode is particularly useful for embedding SQL statements inside of shell
scripts. (An example script is given following.) When using the -c option, you
must enter “go” to mark the end of the SQL statement.
Interactive Mode
To execute xql interactively, you omit the -c and -f options; as a result, the
standard output will not be redirected into xql. The xql prompt looks like the
following:
xql>>[AutoSysDB][autosys] 1>
The second token in the prompt (AUTOSYSDB in this example) displays the
name of the data server to which you are connected. The third token is the name
of the database that you are currently in. At this prompt, xql is waiting for input,
in the form of Transact SQL—Sybase’s extended SQL language. The SQL can
extend across multiple lines. To execute the SQL, you enter a semi-colon (;) at the
end of the SQL statements, or enter “go” on a new line.
There is a history feature, which allows you to reuse past commands stored in
the buffer. Also, an editing feature, which uses emacs or vi, is available to edit
the buffer before sending it to the Server. To exit xql, you enter exit at the prompt
and press Enter or Ctrl+D.
Notes:
xql is provided only for use with the Sybase database. If you are using Oracle,
you can use Oracle’s SQL*Plus command language interface. If you are using a
Microsoft SQL Server, you can use the ISQL/w graphical query interface.
xql is provided only for use with the Sybase database. If you are using Oracle,
you can use Oracle’s sqlplus.
Options
-U user_name Specifies the name of the Sybase user to log in as, and can be any valid Sybase
user. This is typically “autosys” for the AutoSys user, or “sa” for the system
administrator.
-P password Specifies the Sybase password for the specified user_name. By default, the
“autosys” user’s password is “autosys” and, for bundled Sybase, the “sa”
password is “sysadmin.” You can change both of these passwords, and you
should for security reasons. The password must not be null.
-S server Specifies the name of the Sybase data server to be accessed. The default value is
taken from the environment variable %DSQUERY%. If no server is specified,
and %DSQUERY% is not defined, xql will terminate. For the database bundled
with AutoSys, this value is normally AUTOSYSDB.
Specifies the name of the Sybase data server to be accessed. The default value is
taken from the environment variable $DSQUERY. If no server is specified, and
$DSQUERY is not defined, xql will terminate. For the database bundled with
AutoSys, this value is normally AUTOSYSDB.
Commands 2–135
xql
-D database Specifies the specific Sybase database to be accessed. For the bundled database,
this value is normally “autosys.” If no database is specified, it is taken from the
environment variable %DSDB%, if defined. If this variable is not defined, the
default database for the identified user is taken from the user table in the
master database. For the user “sa,” this is typically “master”; for “autosys,” it is
normally “autosys.”
Specifies the specific Sybase database to be accessed. For the bundled database,
this value is normally “autosys.” If no database is specified, it is taken from the
environment variable $DSDB, if defined. If this variable is not defined, the
default database for the identified user is taken from the user table in the
master database. For the user “sa”, this is typically “master”; for “autosys,” it is
normally “autosys.”
In this non-interactive mode, column names, for example; field names are not
output unless the -l option is also specified.
-d delimiter Specifies the delimiter to be used for output, which is written to standard
output. The default delimiter is the pipe symbol (|), which is placed between
all output fields. This option is useful for creating a flat file of data that uses
delimiters for processing at a later time. The delimiter is not restricted to a
single character, and can even be a string of characters with special characters.
Be sure not to use a character that your batch file could mistakenly interpret,
especially the asterisk symbol (*).
-l Specifies that a long listing is desired, meaning that the output should be
displayed as one column name, for example; field name with its corresponding
value per line. The default in non-interactive mode (using the -c or -f options) is
to output the selected “records” one per line, with multiple fields of a single
record appearing on the same line. No field names are output in the non-
interactive “short” mode. This option has no effect in interactive mode.
-T timeout_interval Specifies a period of time after which xql will terminate the session if no
activity has occurred. The interval is specified in minutes; any number can be
specified. To specify that xql should never terminate the session, enter 0. The
default is 15 minutes.
Commands 2–137
xql
Examples
The following examples assume that the Sybase account and password are
“autosys” and “autosys” respectively. The examples also assume that the data
server defaults to AUTOSYSDB, and the database defaults to “autosys.”
1. To select the job ID and job name (the field names are assigned) from the job
table in the default data server and database, enter this (using the “autosys”
user and the “autosys”, or the appropriate, password):
xql -Uautosys -Pautosys
Assuming that there are only three jobs, this will be the output:
joid job_name
-------- -----------------------------
101 tester
106 test1
107 domail.tibet
Note the “go” at the end of the command line—a semi-colon will not be
accepted.
3. To use the percent sign (%) as the delimiter and specify a file name named
“test.sql” containing the same select statement as shown previously, enter:
xql -Uautosys -Pautosys -f test.sql -d %
7. By invoking xql with the -c or -f option, or by redirecting input into it, xql
will execute the command or file of commands, and write its results to
standard output, then exit. This use is most common in batch files where
data from the database is needed. Suppose that you want to store the
number of jobs defined in the “autosys” database in a batch file. To
accomplish this, enter the following in the batch file:
@REM
@REM Get the number of jobs in AutoSysDb
@REM
@xql -Uautosys -Pautosys -S%DSQUERY% -DAutoSysDb -c"select
count (*) from job"
Commands 2–139
xql
7. By invoking xql with the -c or -f option, or by redirecting input into it, xql
will execute the command or file of commands, and write its results to
standard output, then exit. This use is most common in shell scripts where
data from the database is needed. Suppose that you want to store the
number of jobs defined in the “autosys” database in a Bourne shell script.
To accomplish this, enter the following in the script:
#!/bin/sh
#
# Example program
# Get the number of Jobs in AutoSys
num_jobs=`xql -Uautosys -Pautosys -c "select count(*) from
job”`
if [ $numjobs -gt 100 ]
then
echo "Lots of Jobs in AutoSys"
fi
8. To obtain help in interactive mode, enter help at the xql prompt as shown
following:
xql>>[AUTOSYSDB][autosys] 1> help
JIL/GUI Definitions
3
JIL Subcommands
JIL subcommands are used to establish if you are creating, updating, or
deleting a job. When using the Unicenter AutoSys JM Job Editor, the same
instructions are conveyed by opening the window, and by entering values or
selecting buttons in the various fields on the various tabs.
Job Attributes
Unicenter AutoSys JM job attributes are used to specify everything from the
name of a new job to the specific exit conditions, which must be “successful” in
order for the job to be considered completed. Job attributes can be defined
using JIL statements, which are input to the JIL command, or they can be
defined using the Unicenter AutoSys JM Graphical User Interface (GUI), Job
Editor. Regardless of method, the attributes are virtually the same.
Unicenter AutoSys JM job attributes are used to specify everything from the
name of a new job to the specific exit conditions, which must be “successful” in
order for the job to be considered completed. Job attributes can be defined
using JIL statements, which are input to the JIL command, or they can be
defined using the Unicenter AutoSys JM Graphical User Interface (GUI).
Regardless of method, the attributes are virtually the same.
alarm_if_fail
JIL attribute
GUI Path
JIL Syntax
alarm_if_fail: toggle
Description
Indicates whether an alarm should be posted to the Event processor if the job
fails or is terminated. The alarm is informational only. A defined monitor, the
Alarm Sentry, or the Alarm Manager needs to be running to view the alarm as it
occurs, and an operator must take the appropriate steps to address the situation.
Where Applicable
Values
GUI: Check the check box for Yes, and clear it for No.
GUI: Select the Yes or No option button; to change your selection, click the
other button.
Example
Set the job currently being created or updated to post an alarm if it fails or is
terminated, enter:
alarm_if_fail: y
auto_delete
JIL Attribute
GUI Path
JIL Syntax
auto_delete: value
Description
Indicates whether the job should be automatically deleted after completion. This
attribute is useful for using Unicenter AutoSys JM to schedule and run a one-
time batch job. The number of Hours after the job’s completion, at which time the
job should be deleted, can be specified (including “0” for immediately). If it is a
box job, the box and all the jobs in the box will be deleted.
Where Applicable
Values
JIL: value can be any number of hours; 0 indicates immediate deletion, while -1
indicates that the job should not be deleted.
GUI: Select the check box, and enter the number of Hours, which can be any
number of hours; 0 indicates immediate deletion. The keyword auto_delete is
omitted.
GUI: Enter the value, which can be any number of hours; 0 indicates immediate
deletion. The keyword auto_delete is omitted.
Example
auto_hold
Job Attribute
GUI Path
JIL Syntax
auto_hold: toggle
Description
This feature is only for jobs that are in a box. When a job is in a box, it inherits
the starting conditions of the box. This means that when a box goes into the
RUNNING state, the box job will start all the jobs within it (unless other
conditions are not satisfied).
Where Applicable
Values
GUI: Check the check box to indicate Yes, and clear it to indicate No.
GUI: Select the Yes or No option button; to change your selection, click the
other button.
Example
JIL Syntax
avg_runtime: value
Description
Indicates an average runtime (in minutes) for a job that is newly submitted to
the database; it establishes this value in the absence of the job having been run
multiple times. This attribute is used solely to establish an average runtime for
the new job in the avg_job_runs table.
Indicates an average runtime (in minutes) for a job that is newly submitted to
the database; it establishes this value in the absence of the job having been run
multiple times.
Note: When the DBMaint script executes, it recalculates the average runtime for
each job in the database. If a new job has been submitted with the avg_runtime
attribute and has not been run yet, its average runtime will be changed to 0.
Where Applicable
Values
Example
To set the average runtime for a new job to be five minutes, enter:
avg_runtime: 5
box_failure
Job Attribute
GUI Path
JIL Syntax
box_failure: conditions
Description
Where Applicable
Values
JIL: conditions can specify any of the dependencies described in the Starting
Parameters section of the Unicenter AutoSys Job Management for Windows User
Guide and the Unicenter AutoSys Job Management for UNIX User Guide.
GUI: Enter the conditions, which can be any of the dependencies described in the
Starting Parameters section of the Unicenter AutoSys Job Management for
Windows User Guide and the Unicenter AutoSys Job Management for UNIX
User Guide. The keyword box_failure is omitted.
The default Failure Condition is that all the jobs in the box have run and at least
one failed.
Examples
1. Set the status of the box currently being created or updated to FAILURE if
“JobA” fails or “JobB” fails, but ignoring if “JobC” fails, enter:
box_failure: failure(JobA) OR failure(JobB)
2. Set the status of the box currently being created or updated to FAILURE only
if all three jobs fail, enter:
box_failure: failure(JobA) AND failure(JobB) AND failure(JobC)
Note: In JIL, multiple lines of input up to 255 characters can be specified without
any continuation characters.
box_name
Job Attribute
GUI Path
JIL Syntax
box_name: name
Description
Indicates the name of the box in which this job is to be placed. Boxes allow for a
set of jobs to be manipulated as a group. This feature is particularly useful for
setting starting conditions at the box level, to “gate” the jobs inside the box, then
specify their starting conditions relative to each other individually, if necessary.
The specified box must already exist.
Where Applicable
Values
GUI: Enter or Search for the Box name, which can be any string of up to 30
alphanumeric characters, plus the underscore character ( _ ). The box_name
keyword is omitted. The entered name, the box job, must already exist.
Example
To specify the job currently being created or updated should be put in the box
named “Box1,” enter:
box_name: Box1
box_success
Job Attribute
GUI Path
JIL Syntax
box_success: conditions
Description
The default condition for a box to be considered successful is that every job in
the box completed with a success condition. A box can contain complex
branching logic, which can take a number of different paths, all of which
constitute success. In this case, some jobs in the box may never need to be run,
but if the default box behavior is applied, the jobs that had not run would keep
the box from ever completing.
This attribute can be used to specify what is considered a success, which could
be as simple as the success of a single job, or as complex as necessary.
For more information, see the section Starting Parameters, in the chapter “Jobs,”
in the Unicenter AutoSys Job Management for Windows User Guide, or the
section Starting Parameters, in the chapter “Jobs,” in the Unicenter AutoSys Job
Management for UNIX User Guide.
Where Applicable
Values
JIL: conditions can specify any of the dependencies described in the Starting
Parameters section in the Unicenter AutoSys Job Management for Windows User
Guide and the Unicenter AutoSys Job Management for UNIX User Guide.
GUI: Enter the Success Conditions, which can be any of the dependencies
described in the Starting Parameters section in the Unicenter AutoSys Job
Management for Windows User Guide and the Unicenter AutoSys Job
Management for UNIX User Guide. The keyword box_success is omitted.
The default success condition is that all the jobs in the box ran and all completed
successfully.
Examples
1. Set the status of the box currently being created or updated to SUCCESS only
when “JobA” succeeds or “JobB” succeeds, but ignoring the status of “JobC,”
enter:
box_success: success(JobA) OR success(JobB)
2. Set the status of the box currently being created or updated to SUCCESS only
if all three jobs succeed, and they are the only jobs in the box, enter nothing.
This is the default behavior of box jobs.
3. Set the status of the box currently being created or updated to SUCCESS only
if jobs “JobA” and “JobB” succeed, and “JobC” completes, regardless of its
status, enter:
box_success: success(JobA) AND success(JobB) AND done(JobC)
box_terminator
Job Attribute
GUI Path
Job Editor, Alarms/Terminators tab, If this job fails, terminate the box it is in.
Job Definition, Adv Features, If this Job Fails should the Box it is in be
Terminated?
JIL Syntax
box_terminator: toggle
Description
This attribute specifies whether the box containing this job should be terminated
if the job fails or terminates. By using this attribute in combination with the If the
box fails, terminate this box setting, you can control how nested jobs react when
a job fails. This attribute can only be specified if the job being defined is being
placed in a box.
Where Applicable
Values
GUI: Check the check box to indicate Yes, or clear it to indicate No.
GUI: Click the Yes or No option button; to change your selection, click the other
button.
Example
Specify that if the job currently being created or updated fails, the box it is in
should be terminated, enter:
box_terminator: y
chk_files
Job Attribute
GUI Path
JIL Syntax
Description
This resource check specifies the minimum amount of file space that must be
available on designated drives for the job to be started. One or more drives,
specified with the corresponding drive letter, and their corresponding sizes,
can be specified. Only drives are checked; directories, if specified, are ignored.
If multiple drivers are specified, separate them with a single space. When the
Remote Agent is preparing to start the job on the client machine, it checks
whether the required space is available before starting the job.
If the requirements are not met, an alarm is generated. If the job is a command
job, the job will not be started; after a logarithmic-back off type delay, another
attempt will be made to check the file system space and start the job. If the job is
a file watcher job, it will be started regardless of the lack of available space.
In the case of a file watcher definition, the drive should identify the drive on
which the file is expected to arrive, as specified in the File to Watch attribute, and
the minimum file size should be the same as the Minimum File Size attribute.
This resource check specifies the minimum amount of file space that must be
available on designated file systems for the job to be started. One or more file
systems, specified with full path names or directory names, and their
corresponding sizes, can be specified. If multiple file systems are specified,
separate them with a single space. When the Remote Agent is preparing to start
the job on the client machine, it checks whether the required space is available
before starting the job.
If the requirements are not met, an alarm is generated. If the job is a command
job, the job will not be started; after a logarithmic-backoff type delay, another
attempt will be made to check the file system space and start the job. If the job is
a file watcher job, it will be started regardless of the lack of available space.
In the case of a file watcher definition, the file_system_name should identify the
location where the file is expected to arrive, as specified in the “File to Watch”
attribute, and the minimum file size should be the same as the “Minimum File
Size” attribute.
Where Applicable
Values
drive The drive on which the file space will be needed, and environment variables
defined in the job’s profile can be used in the path name.
GUI: Enter one or more file size pairs. The keyword chk_files is omitted.
file_system_ The full path name of the file system where the file space will be needed, and
environment variables exported in the profile can be used in the path name.
name
GUI: Enter one or more file_system_name size pairs. The keyword chk_files is
omitted.
Example
To specify that the job currently being created or updated should have 100 KB
of space available on the C: drive and 120 KB of space available on the D: drive,
enter:
chk_files: C: 100 D: 120
To specify that the job currently being created or updated should have 100 KB
of space available on the file system named roots and 120 KB of space available
on the file system named auxfs1, enter (using the full path name):
chk_files: /roots 100 /auxfs1 120
command
Job Attribute
GUI Path
JIL Syntax
command: command_name command_runtime_args
Description
The command attribute can be the name of any command, executable, UNIX
script, or batch file, and its arguments. Input and output redirection is provided
by other job attributes and cannot be part of a command. Global variables can
be used as part of the command name itself, or as part of the command’s
runtime arguments. (Use the sendevent command, or the Send Event Tool, to
set a global variable.)
where:
command_line Specifies the full command line. This command line must be in quotes.
These are additional points to keep in mind with regard to the command
attribute:
■ Redirection of standard input, output, and error files is not allowed. Job
attributes, such as std_in_file for standard input, can be used to provide the
necessary functionality.
When specifying drive letters in commands, the colon (:) must be escaped. That
is, C:\tmp and C\:\tmp are valid; and C:\tmp is not.
Therefore, if $PATH is assigned in that script, that path will be searched to find
the executable.
The full path name can be specified, in which case, variables exported from the
profile script can be used in the path name specification. If variable substitution
is used, enclose the variable in curly braces, like the following:
${PATH}
These are additional points to keep in mind with regard to the command
attribute:
■ Piping or redirection of standard input, output, and error files are not
allowed. Shell scripts can be invoked to execute piped commands and
attributes (such as std_in_file used for standard input) to provide the
necessary functionality.
■ You cannot use the background character ampersand (&) in the command
attribute. You can call a shell script to provide that functionality.
■ If you are running a C-Shell (csh) script, the system will attempt to source a
.cshrc file when it begins interpreting the file. Although this may be desired,
the system will also overwrite any variables defined in the profile script (the
default profile is /etc/auto.profile). If you do not wish to have the .cshrc file
sourced, you must invoke the csh script with the -f option. For example, this
should be the first line of the script:
#!/bin/csh -f
■ All commands are run under the Bourne shell (/bin/sh). Therefore, all
statements in the profile must use /bin/sh syntax, such as:
Variable=value; export Variable
Where Applicable
Values
command_ The Windows command can be the name of any command, batch file, or an
name application program that is to be run on the client machine when all the
necessary conditions are met.
The command name and any runtime arguments can be up to 255 characters
long. Global variables can be referenced anywhere in the command_name or in
its command_runtime_args. Global variables are referenced using one of the
following expressions:
$$global_name
or:
$${global_name}
Examples
5. Remove all files from the \tmp subdirectory under the directory specified in
the MY_BACKUPS global variable, you could enter:
command: del $$MY_BACKUPS\tmp\*.*
2. If the /bin directory is included in the search path, either in the /etc/
auto.profile or in the user-defined profile, the UNIX date command can be
specified to execute by entering:
command: date
or:
5. Remove all files from the /tmp subdirectory under the directory specified in
the MY_BACKUPS global variable, you could enter:
command: rm $${MY_BACKUPS}/tmp/*
condition
Job Attribute
GUI Path
JIL Syntax
condition: [(]condition[)][{AND | OR }[(] condition [)]]...
Description
When using the condition attribute, any number of job dependencies can be
specified. All dependencies must evaluate to true before the dependent job will
be run. Starting conditions can be one or more of the following types of
dependencies:
Jobs can conditionally start based on the status of another job running on a
different Unicenter AutoSys JM instance.
The syntax for defining job dependencies is the same regardless of whether the
job is being defined using JIL or the Job Editor; the only difference is that the
JIL statement will begin with the condition keyword, while the Job Editor
Dependencies field will only contain the language for the dependency itself.
The dependency specification can take one of three forms: one based on the
current status of other jobs, and one based on the exit codes of other jobs, and
one based on global variables.
The syntax for defining job dependencies is the same regardless of whether the
job is being defined using JIL or the GUI; the only difference is that the JIL
statement will begin with the condition keyword, while the GUI field will only
contain the language for the dependency itself. The dependency specification
can take one of three forms: one based on the current status of other jobs, and
one based on the UNIX exit codes of other jobs, and one based on global
variables.
where:
success
Indicates job_name’s status is SUCCESS.
failure
Indicates job_name’s status is FAILURE.
done
Indicates job_name’s status is SUCCESS, FAILURE, or TERMINATED.
terminated
Indicates job_name’s status is TERMINATED
notrunning
Indicates job_name’s status is anything except RUNNING.
job_name Is the job on which the job you are defining is dependent.
Note: If you issue a KILLJOB event for a job which is not *.exe (for example,
*.bat, *.cmd, or *.com), KILLJOB will kill only the initiated CMD.EXE process.
The Job Status will be set according to the return code of the killed CMD.EXE
process. This status can be any one of the following: SUCCESS, FAILURE, or
TERMINATED.
These statuses are internal Unicenter AutoSys JM settings, so their actual values
do not need to be known. The value of the SUCCESS status can be controlled by
the user by way of the Maximum Exit Code for SUCCESS field, on the Command
Info tab, which can be set for a specific job. If that attribute is specified, any job
that exits with an exit code less than or equal to the specified “Maximum Exit
Code for Success” (max_exit_success attribute) value will be treated as a success.
FAILURE means the job exited with an exit code higher than this value. The
default for normal job completion is “0.” All other status settings are internally
defined only. TERMINATED means the job was actually killed.
You may abbreviate the status condition identifiers with the first letter: s, f, d, t,
and n. These abbreviations can be uppercase or lowercase.
would be evaluated, and the results would be A and B or D and E, reading from
left to right.
As in the previous list, any job status can be used as part of the specification for
starting conditions. With this latitude, you can program branching paths to be
taken that will provide alternate actions for error conditions. The notrunning
operator is used to keep jobs from running at the same time as other jobs; that is,
running one is exclusive of the other.
Specify a cross-instance job dependency, enter the job name followed by a caret
(^) and the name of the other instance, as in the following example:
Note: In JIL, multiple lines of input up to 255 characters can be specified without
any continuation characters.
In addition to job status, you can base job dependencies on exit codes that
indicate completed tasks. In this way, you can implement even more specific
branching logic for recovering from job failures. For example, if a “broken”
communication line results in “JobA” failing with an exit code of 4, you can
specify that when this code occurs, you want the system to execute a batch file
(“JobB”), which redials the line.
In addition to job status, you can base job dependencies on UNIX exit codes
that indicate completed tasks. In this way, you can implement even more
specific branching logic for recovering from job failures. For example, if a
“broken” communication line results in “JobA” failing with an exit code of 4,
you can specify that when this code occurs, you want the system to execute a
shell script (“JobB”), which redials the line.
This is the syntax you would use to specify this type of job dependency:
exitcode (job_name) operator value
where:
job_name Specifies the name of the job upon which the “new” job is dependent.
You can also abbreviate the dependency specification exit code with the letter e
(uppercase or lowercase).
Job dependencies can also be based on global variables you set using the
sendevent command or the Send Event dialog. When using global variables this
way, the value of the variable must evaluate to TRUE for the job dependency to
be satisfied. Global variables are referenced using the following expression:
condition: VALUE(global_name) operator value
where:
global_name Specifies the name of the global variable already set in the database.
operator Specifies one of the following (spaces around the operator are optional):
value Specifies any numeric value or text string (no quotes or spaces).
You can also abbreviate the dependency specification VALUE (of a global
variable) with the letter v (uppercase or lowercase).
You can use any job status, exit code, or global variable as part of the
specification for starting conditions. With this latitude, you can program
branching paths to provide alternative actions for all types of error conditions.
For example, the conditions for jobs downstream from “JobA,” which has been
put “on ice” (with JOB_ON_ICE), as shown in the following table.
Where Applicable
Values
GUI: Enter the Dependencies, which can specify any combination of the
starting conditions described previously. The keyword condition is omitted.
GUI: Enter the conditions, which can specify any combination of the starting
conditions described previously. The keyword condition is omitted.
Examples
1. This is the job dependency specification for a job, which is to run if the job
named “DB_BACKUP” succeeds:
condition: success(DB_BACKUP)
2. If “JobC” should be started only when both “JobA” and “JobB” complete
successfully or when both “JobD” and “JobE” complete, regardless of
whether they failed, succeeded, or terminated, specify the following
dependency in the job definition for “JobC”:
condition: (success(JobA) AND success(JobB)) OR (done(JobD) AND done(JobE))
3. If “JobB” fails part of the way through processing, you may want to call a
routine named “Backout” that will back out of the changes. To do this,
specify the following job dependency in the job definition for “Backout”:
condition: failure(JobB)
5. The job dependency specification for the re-dial job for which the
prerequisite job exited with an exit code of 4:
condition: exitcode (JobA) = 4
6. The job dependency specification for a job, which is to run, only if the global
variable named “OK_TO_RUN” is greater than 2 would be entered as
follows:
condition: VALUE(OK_TO_RUN)>2
7. The job dependency specification for a job, which is to run only if the job
named “BACKUP” completes with a SUCCESS and the global variable
named “TODAY” has a value of Friday, would be entered as follows:
condition: success(BACKUP) AND VALUE(TODAY)=Friday
8. The job dependency specification for a job, which is to run, only if the job
named “DB_BACKUP” residing on another Unicenter AutoSys JM instance
named “PRD” succeeds, would be entered as follows:
condition: success(DB_BACKUP^PRD)
date_conditions
Job Attribute
GUI Path
JIL Syntax
date_conditions: toggle
Description
This attribute specifies whether or not there are date or time conditions for
starting this job. If it is set to “no,” the remainder of the date/time related
attributes will be ignored. If set to “yes,” the date can be specified using the
days_of_week attribute, or the specific dates can be specified by associating this
job with a custom calendar, created using the Graphical Calendar facility or the
autocal_asc command. Starting times can also be specified using the start_times
attribute to request specific times per day, or using the start_mins attribute to
request specific times per hour. (See each of these attribute’s reference pages for
further details.)
Where Applicable
Values
GUI: Check the Date/Time check box for Yes, or clear it for No.
GUI: Click the Yes or No option button; to change your selection, click the other
button.
The default value is 0 for no. If the default is used, all other date/time
dependencies are set to off, or disabled.
Example
To specify that starting date and time conditions are to be in effect, enter:
date_conditions: y
days_of_week
Job Attribute
GUI Path
JIL Syntax
days_of_week: {day [,day]... | all}
Description
Indicates the days of the week when the job will be run. One or more days can be
selected, or all days can be selected. This attribute and the run_calendar attribute
are mutually exclusive. Unicenter AutoSys JM will schedule the job to run on
every day of the week specified by this attribute, at the times specified in the
start_times or start_mins attribute, one of which must be specified if this
attribute is used.
Where Applicable
Values
■ mo (Monday)
■ tu (Tuesday)
■ we (Wednesday)
■ th (Thursday)
■ fr (Friday)
■ sa (Saturday)
■ su (Sunday)
GUI: Select the Run Days option button, then select one or more of the Monday
through Sunday toggle buttons by clicking them, or click the All button, to
select all days. If days have been selected and you decide you want to use a
calendar instead, click the Run Days option button to clear it.
GUI: Select one or more of the Monday through Sunday toggle buttons by
clicking them, or select the Every Day toggle button. If days have been selected
and you decide you want to use a calendar instead, clear the days toggle
buttons to avoid an error.
If start times are specified for a job and no dates or days have been specified
using other GUI fields, the definition is invalid.
Examples
2. Specify that the job should be run every day of the week, enter:
days_of_week: all
delete_box
JIL Subcommand
Function
Deletes a box, and all the jobs in it, from the database.
GUI Path
Description
The delete_box subcommand deletes the specified box and all the jobs in that
box. Jobs in the box, and the box itself that are already scheduled to run will still
be deleted and will not be run.
Values
Example
To delete a box named “Box1” and all jobs inside it, you would specify the
following subcommand in the JIL script:
delete_box: Box1
delete_job
JIL Subcommand
Function
GUI Path
JIL Syntax
delete_job: job_name
Description
The delete_job subcommand deletes the specified job from the database. Even if
the job is already scheduled to run, it will not be run. delete_job checks the
job_cond table and notifies you if dependent conditions for the deleted job exist.
This functionality only works when JIL is in job verification mode, which is the
default setting. If the specified job is a box, the box will be deleted. The jobs in
the box will have their box reference removed and will become stand-alone jobs.
If a box name is specified in the GUI, a delete_box on the box and all the jobs
inside of it will be performed. If a box name is specified with JIL using
delete_job, only the box is deleted, the contained jobs are not deleted.
Values
job_name Must be a job or box currently defined in the database. There is no default.
Example
To delete a job called “Job1”, you would specify the following subcommand in
the JIL script:
delete_job: Job1
description
Job Attribute
GUI Path
JIL Syntax
description: text
Description
Where Applicable
Values
GUI: Enter the text description, which can be any string of alphanumeric
characters, up to 255 characters. Spaces can be included. The keyword
description is omitted. You do not have to enclose the string in quotes; the GUI
does this for you automatically when the job definition is saved.
There is no default.
Example
To specify that the job is an incremental daily backup of the database, enter:
description: "incremental daily backup of the database"
exclude_calendar
Job Attribute
GUI Path
JIL Syntax
exclude_calendar: calendar_name
Description
Indicates the name of the custom calendar to be used for determining the days of
the week on which this job will not run. The calendar must have been previously
created using Graphical Calendar facility (or autocal_asc).
Where Applicable
Values
JIL: calendar_name must be the name of a custom calendar that has already been
created.
GUI: Select the defined calendar from the Exclude Calendar pop-up list.
GUI: Enter the name of a custom calendar that has already been created. The
keyword exclude_calendar is omitted.
Example
To specify that the job can be run on any day except those days specified in the
“holiday” calendar, which you have previously defined, enter:
exclude_calendar: holiday
heartbeat_interval
Job Attribute
GUI Path
JIL Syntax
heartbeat_interval: mins
Description
Specifies the frequency (in minutes) at which this job’s command is expected to
issue a heartbeat. Heartbeats are the way Unicenter AutoSys JM monitors a job’s
actual progress. It automates the common practice of outputting characters, such
as displaying asterisks, which are echoed across the screen as a process runs in
order to reflect its continued progress. The Remote Agent that starts the job will
listen for these regular heartbeats. If the job does not send a heartbeat in this
specified interval, a HEARTBEAT alarm is generated.
To send a heartbeat from a C program, call the routine found in the following
file:
%AutoSys%\code\testheart.c
You must configure the Event processor to check for heartbeats, and you can do
so using the Administrator Event processor screen.
To send a heartbeat from a C program, call the routine found in the following
file:
$AUTOSYS/code/heartbeat.c
To send a heartbeat from a Bourne shell script, execute the code found in the
following file:
$AUTOSYS/code/heartbeat.sh
You must configure the Event processor to check for heartbeats, and you can do
so in the configuration file ($AUTOUSER/ config.$AUTOSERV).
For more information, see the section Sending Heartbeats, in the chapter
“Administrator,” in the Unicenter AutoSys Job Management for Windows User
Guide, or the Unicenter AutoSys Job Management for UNIX User Guide.
Where Applicable
Values
JIL: mins specifies the number of minutes; any reasonable number is acceptable.
GUI: Enter the minutes to specify the number of minutes between heartbeats,
which the job should send; any reasonable number is acceptable. The keyword
heartbeat_interval is omitted.
GUI: Enter mins to specify the number of minutes between heartbeats, which
the job should send; any reasonable number is acceptable. The keyword
heartbeat_interval is omitted.
The default is “0,” indicating that heartbeats will not be listened for.
Example
To set the heartbeat to be expected every 2 minutes, modify your program to call
the heartbeat routine every 2 minutes or less by entering the following:
heartbeat_interval: 2
insert_job
JIL Subcommand
Function
Creates a new job of one of the following types: command job, box job, or file
watcher job.
GUI Path
Job Editor, File menu, Save or SaveAs option (based on the Job Type and Job
Name entered in the New Job dialog)
JIL Syntax
insert_job: job_name
Description
The insert_job subcommand adds a new command, box, or file watcher job
definition to the database. The insert_job: job_name command is followed by a
list of attribute:value statements, which are listed individually in this chapter.
There are a set of job attributes that are required for each job type.
■ insert_job: job_name
■ command: value
■ machine: value
■ insert_job: job_name
■ job_type: value
■ insert_job: job_name
■ job_type: value
■ machine: value
■ watch_file: value
Values
job_name The unique job identifier used throughout Unicenter AutoSys JM. It can be
from 1 to 30 alphanumeric characters, and is terminated with white space.
Embedded blanks and tabs are illegal. There is no default.
Examples
1. The following example creates a command job, specifying only the essential
job attributes. The job is called “time_stamp,” is to run on the real machine
“tibet,” and simply executes the time_stamp.bat batch file. To create this
definition, enter the following subcommand and job attributes in the JIL
script:
insert_job: time_stamp
machine: tibet
command: time_stamp.bat
2. The following example creates a Box, specifying only the essential job
attributes. The box is called “end_of_day”. To create this definition, enter the
following subcommand and job attribute in the JIL script:
insert_job: end_of_day
job_type: b
3. The following example creates a file watcher job, specifying only the
essential job attributes. The file watcher is called “EOD_batch_watch,” is to
run on the real machine “Tibet,” and is to watch for a file named
C:\myapps\EOD_batch.bat. To create this definition, enter the following
subcommand and job attributes in the JIL script:
insert_job: EOD_batch_watch
job_type: f
machine: tibet
watch_file: "C:\myapps\EOD_batch.bat"
job_load
Job Attribute
GUI Path
JIL Syntax
job_load: load_units
Description
Specifies the relative amount of processing power the job will consume. The
range of possible settings is arbitrary and user-defined. Machines can be
assigned “maximum job loads,” a measure of CPU load that is desirable to place
on a machine at any given time. Similarly, jobs can be assigned loads indicating
the relative amount of processing power they consume. This scheme allows for
machine loading to be controlled, and to prevent a machine from being
overloaded.
If a job is ready to run on a designated machine, but the current load on that
machine is too large to accept the new job’s load, the job will be queued for that
machine, to be run later when sufficient resources are available. However, for
this scheme to function properly, all jobs to be run on a controlled machine must
have job loads specified; otherwise, a job could be started on a machine without
the machine showing the additional load.
The default priority of a job is 0, which means that the job should run
immediately and ignore any available load units. Therefore, whenever you set a
job_load for a job, you should also set a priority of 1 or higher for the job_load to
take effect.
Note: You cannot use the priority or job_load attribute if you specify a user-
defined load balancing script in the machine attribute.
For more information, see the chapter “Load Balancing and Queuing Jobs,” in
the Unicenter AutoSys Job Management for Windows User Guide, or the chapter
“Load Balancing and Queuing Jobs,” in the Unicenter AutoSys Job Management
for UNIX User Guide.
Where Applicable
Values
JIL: load_units specifies the relative load of the job, and can be any arbitrary
value within the user-defined range of possible values (which are also arbitrary).
GUI: Enter the load units, which specify the relative load of the job. This
number can be any arbitrary value in the range of possible values the user has
defined (which are also arbitrary).
GUI: Enter load_units, which specifies the relative load of the job. This number
can be any arbitrary value in the range of possible values the user has defined
(which are also arbitrary).
Example
To set the job load for a job that typically uses 10% of the CPU, with a range of
possible load values from 1-100, enter:
job_load: 10
GUI Path
Job Editor, Open, New, Save, and Save As dialogs, Job Name
JIL Syntax
None.
Description
Specifies the name of the job using the GUI. When JIL is used, this attribute is
included with the JIL subcommand; for example insert_job: job_name. This
attribute must be unique in a single instance of Unicenter AutoSys JM, since it is
the primary identifier of the job. The name cannot be changed once the job has
been defined.
Where Applicable
Values
In the Job Editor dialogs, enter the job name. The job name can be up to 30
alphanumeric characters, including the underscore character ( _ ).
job_terminator
Job Attribute
GUI Path
Job Definition, Adv Features, If the Box FAILS should this job be Terminated?
JIL Syntax
job_terminator: toggle
Description
This attribute specifies whether the job should be terminated if the box it is in
fails or terminates. By using this attribute in combination with the If this job
fails, terminate the box setting, you can control how nested jobs react when a
job fails. This attribute only applies if the job is being placed in a box. The job is
terminated with a KILLJOB event.
Note: Windows does not support the concept of process groups. If the job that
was launched was an *.exe, KILLJOB will kill the process specified in the
command definition. If the job being run is not an *.exe (for example, *.bat,
*.cmd, or *.com), Unicenter AutoSys JM uses CMD.EXE to launch the job;
KILLJOB will kill only the CMD.EXE process. The Job Status will be set
according to the return code of the killed CMD.EXE process. This status can be
any one of the following: SUCCESS, FAILURE, or TERMINATED. Any processes
that were launched by user applications or batch (*.bat) files will not be killed.
This attribute specifies whether the job should be terminated if the box it is in
fails or terminates. By using this attribute in combination with the Terminate
the Box if the Job Fails attribute, you can control how nested jobs react when a
job fails. This attribute only applies if the job is being placed in a box. The job is
terminated with a KILLJOB event.
For more information, on sending KILLJOB see the section “Sendevent,” in the
chapter “Commands,” in this guide.
Where Applicable
Values
GUI: Check the check box to indicate yes, or clear it to indicate no.
GUI: Click the Yes or No option button; to change your selection, click the other
button.
Example
To specify that if the box containing the job currently being created or updated
fails, the job should be terminated, enter:
job_terminator: y
job_type
Job Attribute
GUI Path
Job Editor, File menu New option, which opens the New Job dialog, Job Type
JIL Syntax
job_type: type
Description
Specifies whether the job is a command job, file watcher job, or box job.
Where Applicable
Values
c (command)
f (file watcher)
b (box)
GUI: In the New Job dialog, select Command, Box, or File Watcher from the Job
Type pop-up list.
GUI: Click the appropriate Box, Command, or File Watcher option button; to
change your selection, click a different button.
Example
To set the job currently being created or updated to be a box job, enter:
job_type: b
machine
Job Attribute
GUI Path
JIL Syntax
Description
Specifies the client machine where the job will be run, under the control of the
Remote Agent. The owner of the job must have permission to access this
machine as well as permission to execute the specified command on this
machine. The machine can be a specific real machine, a set of real machines, or
a virtual machine. Real machines must be accessible over the network using the
TCP/IP protocol. Specifying the machine “localhost” tells Unicenter AutoSys
JM to run the job on the machine where the Event processor is currently
running.
Alternatively, you can specify a program that the event processor will execute at
runtime to determine which machine will be used. This program can be a
program or batch file that you write yourself. The event processor runs this
program and writes the name of the machine to its log file; this output will be
substituted as the name of the machine. The fully qualified program or batch file
name must be enclosed in back quotes.
Note: If you specify a load balancing program or batch file that you wrote
yourself, you cannot use the priority or job_load attribute.
Specifies the client machine where the job will be run, under the control of the
Remote Agent. The owner of the job must have permission to access this
machine as well as permission to execute the specified command on this
machine. The machine can be a specific real machine, as listed in the /etc/hosts
file on the server machine, a set of real machines, or a virtual machine.
Specifying the machine “localhost” tells Unicenter AutoSys JM to run the job on
the machine where the event processor is currently running.
Alternatively, you can specify a program that the event processor will execute at
runtime to determine which machine will be used. This program can be the
svload program provided by Unicenter AutoSys JM or it can be a program or
script that you write yourself. The event processor runs this program and writes
the name of the machine to standard output; this output will be substituted as
the name of the machine. The fully qualified program or script name must be
enclosed in back quotes.
Note: If you specify the svload program or a load balancing program or script
that you wrote yourself, you cannot use the priority or job_load attribute.
WARNING! If you have implemented the Shadow Event Processor feature, you
should never set the machine attribute to local host. Local host implies: “run on
the machine on which the event processor is currently running.” The job may
run normally on the Primary Event Processor machine, and yet fail on the
Shadow Event processor machine.
For more information, see the chapter “Load Balancing and Queuing Jobs,” in
the Unicenter AutoSys Job Management for Windows User Guide, or the
Unicenter AutoSys Job Management for UNIX User Guide.
Where Applicable
Note: For a file watcher, you must specify one real machine.
Values
JIL: machine_name can be any real machine, virtual machine, or set of real
machines. The name can be up to 80 characters.
GUI: Select a defined machine from the Machine pop-up list, or Add a machine
by clicking the Add button and entering a name in the New Machine Name
dialog. The new name can be up to 80 characters.
GUI: Enter the machine_name, which can be any real machine, virtual machine,
or set of real machines. The name can be up to 80 characters. Omit the keyword
machine.
Examples
1. Specify that the job be executed on either of the machines named “tibet” or
“socrates,” enter:
machine: tibet, socrates
max_exit_success
Job Attribute
GUI Path
Job Editor, Command Info tab, Maximum Exit Code for SUCCESS
JIL Syntax
max_exit_success: exit_code
Description
Specifies the maximum exit code with which the job can exit and still be
considered a success by Unicenter AutoSys JM. An exit code equal to or less than
this value will be considered a success. This attribute is used when a command
can exit with more than one exit code, indicating either “degrees of success” or
other conditions that cannot indicate a failure. It is useful when defining
complex branching logic based on real time processing.
Where Applicable
Values
GUI: Enter the maximum exit code, which can be any integer.
The default is “0,” which is the normal exit code for Windows executables.
GUI: Enter the exit_code, which can be any integer representing a UNIX exit
code. Omit the keyword max_exit_success.
The default is “0,” which is the normal exit code for UNIX executables.
Example
To set the job to be considered successful when exiting with any exit code of “2”
or less, enter:
max_exit_success: 2
max_run_alarm
Job Attribute
GUI Path
JIL Syntax
max_run_alarm: mins
Description
Specifies the maximum runtime (in minutes) that a job should require to finish
normally. This “reasonability” test can catch an error, such as the application
stuck in a loop or waiting on a system event that never occurs. If the job runs
longer than this time, an alarm is generated. Alarms are informational only.
You must have a monitor, the Alarm Sentry, or the Alarm Manager running to
track alarms in real time.
Specifies the maximum runtime (in minutes) that a job should require to finish
normally. This “reasonability” test can catch an error, such as the application
stuck in a loop or waiting on a system event that never occurs. If the job runs
longer than this time, an alarm is generated. Alarms are informational only.
You must have a monitor or the Alarm Manager running to track alarms in real
time.
Where Applicable
Values
JIL: mins can be any integer; it represents the maximum number of minutes the
job should ever require to finish normally.
GUI: Enter the number of Minutes, which can be any integer; it represents the
maximum number of minutes the job should ever require to finish normally.
GUI: Enter the mins, which can be any integer; it represents the maximum
number of minutes the job should ever require to finish normally. Omit the
keyword max_run_alarm.
Example
To set the job to be considered as running too long if it runs for more than an
hour and a half, enter:
max_run_alarm: 90
min_run_alarm
Job Attribute
GUI Path
JIL Syntax
min_run_alarm: mins
Description
Specifies the minimum runtime (in minutes) that a job should require to finish
normally. This “reasonability” test can catch an error, such as the input file
being truncated due to an error. If the job runs in less than this time, an alarm is
generated. Alarms are informational only. You must have a monitor, the Alarm
Sentry, or the Alarm Manager running to track alarms in real time.
Specifies the minimum runtime (in minutes) that a job should require to finish
normally. This “reasonability” test can catch an error, such as the input file
being truncated due to an error. If the job runs in less than this time, an alarm is
generated. Alarms are informational only. You must have a monitor or the
Alarm Manager running to track alarms in real time.
Where Applicable
Values
JIL: mins can be any integer representing the minimum number of minutes the
job should ever require to finish normally.
GUI: Enter the number of Minutes, which can be any integer; it represents the
minimum number of minutes the job should ever require to finish normally.
GUI: Enter the mins, which can be any integer; it represents the minimum
number of minutes the job should ever require to finish normally. Omit the
keyword min_run_alarm.
Example
To set the job to be considered as completing too quickly if it runs for less than
an hour and a half, enter:
min_run_alarm: 90
n_retrys
Job Attribute
GUI Path
Job Editor, Misc tab, Number of times to restart this job after a failure
Job Definition, Adv Features, Number of Times to Restart this Job after a
FAILURE
JIL Syntax
n_retrys: attempts
Description
Specifies how many times, if any, the job should be restarted after exiting with
a FAILURE status. If a job is TERMINATED, it will not restart. This attribute
applies to application failures, for example: Unicenter AutoSys JM is unable to
find a file or a command, or permissions are not properly set; it does not apply
to system or network failures, for example: machine unavailability, the socket-
connect timed out, the fork in the Remote Agent failed, or the file system space
resource check failed. Job restarts after system or network failures are
controlled by the setting in the Max Restart Try’s field on the Administrator
Event processor screen.
Note: The delay between restarts is determined by the settings in the Restart
Constant and Restart Factor fields on the Administrator Event processor screen,
and the delay is capped by the setting in the Max Restart Wait field.
Specifies how many times, if any, the job should be restarted after exiting with
a FAILURE status. If a job is TERMINATED, it will not restart. This attribute
applies to application failures, for example: Unicenter AutoSys JM is unable to
find a file or a command, or permissions are not properly set; it does not apply
to system or network failures, for example machine unavailability, the socket-
connect timed out, the fork in the Remote Agent failed, or the file system space
resource check failed. Job restarts after system or network failures are
controlled by the MaxRestartTrys parameter in the configuration file.
Where Applicable
Values
GUI: Enter number of attempts, which can be any integer between 1 and 20.
GUI: Enter attempts, which can be any integer between 1 and 20. Omit the
keyword n_retrys.
Example
This means that the job would start as scheduled, and, if it fails, it would restart
up to five additional times for a total of six attempts.
override_job
JIL Subcommand
GUI Path
Job Editor, Basic tab or File menu, Add One Time Override (or Add or Delete
Override)
Function
JIL Syntax
override_job: {job_name | job_name delete} attribute_keyword: {value | NULL}
Description
Note: The maximum number of job restarts after system or network failures is
specified in the Max Restart Try’s field on the Administrator Event processor
screen.
Note: The maximum number of job restarts after system or network failures is
specified in the MaxRestartTrys parameter in the configuration file.
These are the job attributes you can use for a job override:
machine start_times
max_run_alarm std_err_file
JIL will not accept an override if it results in an invalid job definition. For
example, if a job definition has one starting condition, start_times, JIL will not
allow you to set the start_times attribute to NULL because removing the start
condition makes the job definition invalid (no start time could be calculated).
All job override information is kept in a table named “overjob” in the database.
The override has a value of over_num assigned to it when you save the job
definition, and is kept in the job_status table until runtime. You reference this
over_num value when you want to know what overrides were applied after a job
run.
For example, when applying a job override, the event processor will specify the
override it is using, as shown following:
Note: You cannot edit a job override that has been specified using JIL. If you
specify an override for a job and one already exists, the new override replaces
the original one. However, the original overrides for example, their over_num
are still maintained in the overjob table in the database.
Values
job_name Must be a job or box currently defined in the database. There is no default.
NULL Used to delete or negate any currently existing value for the indicated
attribute_keyword.
Examples
1. To specify a one-time job override for the job named “job1” to change the
standard output file, enter the following subcommand and attribute in the
JIL script:
override_job: job1
std_out_file: C:\OUTPUT\SpecialRun.out
2. To specify a one-time job override for the job named “jobA” to delete its job
dependency condition and change the standard output file, enter the
following subcommand and attributes in the JIL script:
override_job: jobA
std_out_file: C:\OUTPUT\SpecialRun.out
1. To specify a one-time job override for the job named “job1” to change the
standard output file, enter the following subcommand and attribute in the
JIL script:
override_job: job1
std_out_file: /usr/out/run.special
2. To specify a one-time job override for the job named “jobA” to delete its job
dependency condition and change the standard output file, enter the
following subcommand and attributes in the JIL script:
override_job: jobA
std_out_file: /usr/out/run.special
owner
Job Attribute
GUI Path
JIL Syntax
owner: {user@host_or_domain | user}
Description
Specifies the owner of the job. This attribute is automatically set to the user who
invoked JIL or the GUI Control Panel to define the job. You can determine the
job owner by looking at the Owner field on the Job Editor Basic tab, or by
issuing the following command at an Instance Command Prompt:
autorep -J job_name -q
The owner cannot change this ownership designation. Only the Edit Superuser
can change the owner attribute. However, when defining the job the owner can
grant other users edit or execute permission on that job.
To run a job, the Remote Agent logs on to the machine first as the owner
(user@host_or_domain), then, if that does not work, the Remote Agent attempts
to log on to the machine as the user specified by the owner attribute at the host
specified by the machine attribute (user@host).
For either of these log on attempts to work, the Windows user IDs and
passwords must be entered into the database. In addition, if Remote Agent User
Authentication is enabled, it is performed on the second (user@host) log on
attempt. In this case, the proper Trusted Hosts or Trusted Users permissions are
also required.
Notes:
After the user is logged on to a machine, that user must also have all the
necessary Windows permissions to access the command to be run, as well as
any resources needed to run the command.
Specifies the owner of the job. The owner is the user who invoked jil or the GUI
Control Panel to define the job. This user will own all jobs defined during the
session, and will have edit permission on the jobs. The UNIX command
specified in that job will be run under the user ID of the owner. When a
command is started on the Remote Agent, the uid of the process is changed to
the owner of the job.
The default owner is defined as user@machine. Therefore, only the specific user
on the specific machine can edit the job. In order for the job to run, this
user@machine combination must have execute permission on the UNIX
command specified in the job, on the client machine for the job.
The owner cannot change this ownership designation. Only the Edit Superuser
can change the owner of a job. However, the owner can grant other users edit
permission, as well as execute permission, on the job. Execute permission
controls which users can issue sendevent commands on the job, such as
STARTJOB or KILLJOB. However, it does not affect under whose permissions
the job’s command is executed.
Note: If the rshd and rlogind are disabled on a client, but the /etc/ hosts.equiv
and the .rhosts files are configured correctly, users will not be able to rlogin or
rsh to the client machine, but they will be able to run jobs on it.
Where Applicable
Values
The default setting for user@host_or_domain is the user who initiated jil or the
GUI Control Panel to define the job at the host_or_domain that user was logged
on to. Only the Edit Superuser can modify this attribute.
JIL: user@host_or_domain can be any valid user with an account on the specified
host or domain, which must be a real, not a virtual machine. The user must have
an account on all machines where the job can be run, and the user must have a
valid password for that account in the database.
GUI: Enter user@host_or_domain, which can be any valid user with an account
on the specified machine, which must be a real, not a virtual machine. The user
must have an account on all machines where the job can be run, and the user
must have a valid password for that account in the database.
The Edit Superuser can change the owner of an individual job by using the
update_job JIL subcommand, or by using the Job Editor screens. To change a
large number of jobs, the Edit Superuser can invoke the autorep command to
dump multiple JIL job definitions to an output file, change the owner, and reload
the changed job definitions using the jil command. The following example shows
how to save all job definitions to a file:
autorep -J ALL -q > dump_file
The output of this command is formatted exactly as a JIL job definition script,
like:
insert_job: test_job
job_type: c
command: sleep 60
machine: juno
owner: jerry@jupiter
permission: wx
alarm_if_fail: 1
The owner field of each job definition is usually commented out, unless the Edit
Superuser runs the autorep command to generate the report. This is because
only the Edit Superuser can change the owner field. After generating this report,
the Edit Superuser can use a text editor to change the owner field and re load the
job definitions into the database using the JIL command, as follows:
jil < dump_file
The default setting for user@machine is the user who initiated JIL or the GUI
Control Panel to define the job at the machine that user was logged on to. Only
the Edit Superuser can modify this attribute.
JIL: user@machine can be any valid user with an account on the specified
machine, which must be a real, not a virtual machine. The user must have an
account on all machines where the job can be run.
GUI: Enter user@machine, which can be any valid user with an account on the
specified machine, which must be a real, not a virtual machine. The user must
have an account on all machines where the job can be run. Omit the keyword
owner.
The Edit Superuser can change the owner of an individual job by using the
update_job JIL subcommand, or by using the Job Definition screens. To change a
large number of jobs, the Edit Superuser can invoke the autorep command to
dump multiple JIL job definitions to an output file, change the owner, and reload
the changed job definitions using the JIL command. The following example
shows how to save all job definitions to a file:
autorep -J ALL -q > dump_file
The output of this command is formatted exactly as a JIL job definition script,
like:
insert_job: test_job
job_type: c
command: sleep 60
machine: juno
owner: jerry@jupiter
permission: gx,ge,wx
alarm_if_fail: 1
The owner field of each job definition is usually commented out, unless the Edit
Superuser runs the autorep command to generate the report. This is because
only the Edit Superuser can change the owner field. After generating this report,
the Edit Superuser can use a text editor to change the owner field and reload the
job definitions into the database using the JIL command, as follows:
jil < dump_file
Example
For the Edit Superuser to change the owner such that “chris” on any machine in
the network can edit the job, and the job’s command will run with the
permissions of “chris,” enter:
owner: chris
permission
Job Attribute
GUI Path
JIL Syntax
permission: permission [, permission]
Description
The permission scheme provides users with edit and execute permissions on a
per job basis. By default, only a job’s owner has edit and execute permission on
a job.
The permission scheme is based on the same permissions used in native UNIX.
It uses the user ID (uid), and group ID (gid) from the UNIX environment to
control who can edit job definitions and who can execute the actual command
specified in the job. (If you are defining jobs that are to run on different
operating systems, use the permissions applicable to the operating system of
the client machine.)
User Types
■ Owner
The user who created the job.
■ World
Any user.
Note: For Windows, the UNIX group permission attribute is not supported.
The default owner is the user who initiated JIL or the GUI Control Panel to
define the job. The owner will always have both edit and execute permission for
the job on the machine on which it was defined. Permission attributes can extend
edit and execute capability to other users and other machines.
Unicenter AutoSys JM uses the concept of three levels of users for any job.
These levels are:
■ Owner
The user who created the job.
■ Group
Any user who is in the same group as the owner.
■ World
Every user.
Permission Types
■ Edit
The user can edit, override, or delete the job definition itself.
■ Exec
The user can affect the running of the job, typically by issuing a sendevent
command. Events that affect the running of a job are:
■ STARTJOB
■ FORCE_STARTJOB
■ KILLJOB
■ CHANGE_STATUS
■ JOB_ON_HOLD, JOB_OFF_HOLD
■ JOB_ON_ICE, JOB_OFF_ICE
■ Machine
By default, all edit and execute permissions are valid only on the machine on
which the job was defined. Permission attributes can extend this permission
to other machines.
In UNIX, there are multiple levels of permissions associated with a job. Every
job has the following levels of permissions:
■ Edit
The user can edit, override, or delete the job definition itself.
■ Execute
The user can affect the running of the job, typically by issuing a sendevent
command. These are the events users can execute:
■ STARTJOB
■ FORCE_STARTJOB
■ KILLJOB
■ DELETEJOB
■ CHANGE_STATUS
■ JOB_ON_HOLD, JOB_OFF_HOLD
■ JOB_ON_ICE, JOB_OFF_ICE
■ SEND_SIGNAL
The default owner is the user who initiated JIL or the GUI to define the job. The
job owner has edit permission on the job, and the UNIX command specified in
the job is run under that user ID.
When a command is started on the machine specified in the job definition, the
uid of the process is changed to that of the owner of the job. This is commanded
with the setuid(uid) system call.
When a job is first created, the user ID is retrieved from the environment and
attached to the job. Then, the current value of the owner’s umask is used to
supply default permissions to the job. The umask “write” permission is used as
the default “edit” permission of the job, and the umask “execute” permission is
used as the default “execute” permission of the job.
Where Applicable
Values
When a job is first created, the user ID is retrieved from the environment and
attached to the job. Then the current value of the owner’s umask is used to
supply default permissions to the job. The umask “write” permission is used as
the default “edit” permission of the job, and the umask “execute” permission is
used as the default “execute” permission of the job.
JIL: These are the possible values for the permission attribute:
me Edit by any authorized users, regardless of the machine they are on (otherwise
they must be logged on to the machine specified in the owner field, for
example, user@host_or_domain).
wx World Execute
we World Edit
The owner of the job always has full edit and execute permissions.
If you are defining jobs and running them on different operating systems, keep
the following in mind:
■ When defining a job to run on a Windows machine, you can set group
permissions, but they will be ignored. Group permissions will be used if a
job is edited or executed on a UNIX machine.
■ When editing a job from a Windows machine, the group edit permission is
ignored. In this case, the user editing the job must be the owner of the job, or
World Edit permissions must be specified for the job.
Example
To set the job to be executed by any authorized user regardless of the machine
they are on, you would enter:
permission: mx
To set the job to allow anyone to execute it, but to allow only members of your
group to edit it, enter:
permission: ge, wx
priority
Job Attribute
GUI Path
JIL Syntax
priority: priority_level
Description
Specifies the queue priority of the job. Machines can be assigned “maximum job
loads,” a measure of CPU load desired to place on a machine at any given time.
Each job is assigned a load as well. If a job is ready to run and designated to run
on that machine, but the current load on that machine is too large to accept the
new job’s load, the job will be “queued” for that machine.
The queue priority establishes the relative priority of all jobs queued for a given
machine, the lower number indicating a higher priority. Scenarios can arise
where a CPU-intensive, high priority job cannot get enough resources on the
machine to run because smaller, lower-priority jobs continually grab the small
amounts of resource available. The priority “banding” scheme provides a
solution. Priorities have an associated implied “band,” 1-99 is band “0,” 100-199
is band “1,” and so forth. A band of higher priority jobs (for example; band 0)
completely blocks a band of lower priority jobs, for example: band 1, until all of
the high priority jobs have been run. Thus, the higher priority jobs (although
demanding) will not be delayed unnecessarily.
Although boxes cannot be queued, they can be assigned priorities. This permits
boxes in other boxes to be run according to their priority, rather than the order in
which they were defined, which is the default.
Note: You cannot use the priority or job_load attribute if you specify a user-
defined load balancing script in the machine attribute.
For more information, see the chapter “Load Balancing and Queuing Jobs,” in
the Unicenter AutoSys Job Management for Windows User Guide.
Where Applicable
Values
priority_level can be any integer 0 or larger. priority_level 0 indicates that the job
should always be run immediately, regardless of the current machine load. The
lower the priority_level number, the higher the priority; therefore, 1 is the
highest possible queued priority.
The default is 0, indicating the job will not be queued at all; instead it will run
immediately, regardless of the current machine load.
Note: If a job_load is specified for a job, but its priority is allowed to default to 0,
then the current load on the machine will be ignored, and the job will run
immediately.
JIL: Enter the priority keyword and priority_level number, which can be any
number that is 0 or larger.
GUI: Enter the priority level number, which can be any number that is 0 or
larger.
GUI: Enter the priority_level number, which can be any number that is 0 or
larger. Omit the keyword priority.
Examples
1. Set the job to always run, regardless of the current load on the client
machine, accept the default, which is 0.
2. Set the job to run with the highest priority, while not overriding the machine
load control mechanism, enter:
priority: 1
3. Set the job to run in the background when the machine load is low, enter:
priority: 100
profile
Job Attribute
GUI Path
JIL Syntax
profile: profile_name
profile: pathname
Description
Specifies a job profile that defines environment variables to be set before the
specified command is executed. If the profile attribute is not specified, the
profile named “default” is used; Unicenter AutoSys JM “sources” the default
profile before running jobs that do not have a profile explicitly assigned to
them. On Windows, the default profile is initially empty. You can leave the
default profile empty, or you can define the environment variables that you
want it to contain.
You can define the default and other job profiles using the Profiles Manager, to
specify the profile for a job, you can supply the name of a profile that is located
on the job’s client machine, or you can supply a path name that includes the
machine on which the profile resides, using the form:
\\computer_name\profile_name
For more information, see the section Basic Job Attributes, in the chapter “Jobs,”
in the Unicenter AutoSys Job Management for Windows User Guide.
System environment variables are the only other variables defined for the
command’s execution. Therefore, non-system environment variables must be
defined in either the default or a user-defined job profile. System environment
variables are set before profile variables. Therefore, you can use references to
system environment variables in job profiles.
Notes:
■ If a command normally runs at the MS-DOS Command Prompt (or from the
Instance Command Prompt window), but fails to run properly, the most
likely cause of failure is a difference between the Windows user-defined
environment variables and the environment specified in the job’s profile.
■ Either the specified profile or the default profile will be used; not both.
Therefore, if there are environment variables in the default profile that your
command needs, for example: the path to a command, make sure to set them
in your specified job profile.
Specifies the profile that is to be sourced by the Bourne shell before the
specified command is executed. If a profile attribute is specified, that profile is
searched for on the machine on which the command is to run. The Remote
Agent always spawns a process and starts the Bourne shell in that process,
passing it the name of the profile to be sourced. This profile typically includes
the definitions and exports of environment variables, which can be referenced
in the job’s command (especially if the command is a shell script).
It is very important that Korn shell and C shell statements are not included in the
profile file, since the Bourne shell that runs will not be able to process them. The
results will be, at best, unexpected. In particular, redirection of the stdin, stdout,
and stderr files will most likely fail.
The primary environment variable in the profile is the path. If a profile is not
specified, the default profile, /etc/auto.profile, will be used.
The only environment variable that absolutely must be set in the profile is the
$PATH variable, since it is used to locate the command specified in the job. For
Korn shell users, we recommend that any other environment variables required
to be set are either explicitly set in the shell script that is specified as the
command to be run, or that additional shell scripts be sourced in your main shell
script.
If you want the set permissions for stdout and stderr to -rw-r--r--, you must set
umask 022 in /etc/auto.profile, or, if you are using the profile attribute, set it in
the specified profile file. If you do not set this, the stdout and stderr files will
have world write permissions.
Notes:
■ If a command normally runs at the shell prompt, but fails to run properly,
the most likely cause of failure is a difference between the shell environment
and the environment specified in the profile file.
Where Applicable
Values
profile_name A job environment profile defined using the Profiles Manager, located in the
Unicenter AutoSys JM program group. If the profile attribute is omitted, the
profile named “default” is used.
JIL: Enter the name of the profile containing the environment variables to be set.
GUI: Enter the name of the profile containing the environment variables to be
set. When entering the job profile, you can specify both the machine name and
profile name, which allows you to run the job on one machine while using a Job
Profile defined on another machine.
pathname The full path name of the profile file to be sourced in order to establish the job’s
runtime environment. Variable substitution cannot be used.
The default is to source the Unicenter AutoSys JM-supplied profile named /etc/
auto.profile.
JIL: Enter the profile keyword and the full path name of the file to be sourced.
GUI: Enter the full pathname of the file to be sourced. Omit the keyword
profile.
Examples
To set the environment from a profile named “eng” (which was previously
defined in the Profiles Manager, located in the Unicenter AutoSys JM program
group), enter:
profile: eng
Set the environment from a profile named “eng” that was defined on the
machine “dev,” which is different from the machine on which the job will run,
enter the machine name and the profile name, like:
profile: \\dev\eng
To set the user’s profile called my_profile in their home directory called
/usr/home, enter:
profile: /usr/home/my_profile
run_calendar
Job Attribute
GUI Path
JIL Syntax
run_calendar: calendar_name
Description
Indicates the name of the custom calendar to be used when determining the days
of the week on which a job will run. This attribute is useful for complex date
specification, such as running a job on the last business day of the month. The
custom calendar will list the dates and the times when the job is to be run. The
calendar must have been previously created using the Graphical Calendar
Facility or the autocal_asc command. This attribute and the days_of_week
attribute are mutually exclusive.
Unicenter AutoSys JM will schedule the job to run on every day specified in this
calendar, at the times specified in the calendar (default calendar time is
midnight), or at the times specified in the start_times or start_mins attribute. The
start_times and start_mins attributes override any times set in a calendar.
Where Applicable
Values
JIL: calendar_name must be the name of a custom calendar that has already been
created.
GUI: Check the Date/Time Conditions check box, select the Run Calendar
option button, and then select a defined calendar from the Run Calendar pop-
up list. To create or modify a Calendar, click the Edit Calendar button, which
opens the Calendar Editor.
GUI: Enter the name of a custom calendar that has been previously created. The
keyword run_calendar is omitted. If you have entered a calendar name, then
decide to specify the dates or days using other fields in the dialog, clear this
field to avoid an error.
Example
To specify that the job should be run on the last business day of the month, as
specified in the previously created custom calendar named “last_business”,
enter:
run_calendar: last_business
run_window
Job Attribute
GUI Path
JIL Syntax
run_window: "time-time"
Description
Indicates the time span during which the job will be allowed to start. If this
attribute is specified, then when the job is eligible to run (based on its starting
conditions) Unicenter AutoSys JM will check if the current time falls in the
specified run window. If it does, the job will start. If it does not, the following
calculations are used to determine whether or not to run the job. The end of the
last run window and the beginning of the next run window are determined. If
the current time is closer to the beginning of the next run window, the job will be
scheduled to start when the next run window starts. If the current time is closer
to the end of the last run window, the job does not start and its status is changed
to INACTIVE.
Note: Jobs that are not in a box must have starting conditions in addition to the
run_window attribute in order for the job to be automatically started.
If the job is in a box, the job is changed to ACTIVATED state when the box starts
running. However, if the current time is not in the specified run window, the job
is changed to INACTIVE state.
■ If the current time is closer to the end of the run_window than the next
opening of the run_window, the status of the job is changed to INACTIVE. If
the job is in a box, the box can still run to completion.
■ If the current time is closer to the start of the next run_window, a future
STARTJOB event is issued for the next opening of the run_window.
The above calculations and actions are done so that a box can run to completion
when the run_window for a job inside the box has just closed. For example,
“jobA”, “jobB”, and “jobC” are in “box1” and “jobA” has a run_window of 02:00
to 04:00. If “boxA” starts at 04:05, “jobB” and “jobC” can run and “jobA” will
become INACTIVE, so that the box can complete that day. If “box1” instead
starts at 16:05, “jobA” will have a STARTJOB event set for 02:00 the next day,
and the box will continue running until the job starts the next day.
Where Applicable
Values
GUI: Enter the time range, using the format hh:mm-hh:mm where hh specifies
hours, in 24-hour format, and mm specifies minutes.
The range can overlap midnight as long as it is not more than 24 hours, as in the
following example.
Example
To specify that the job should be allowed to start only between 11:00 p.m. and
2:00 a.m., regardless of other conditions, enter:
run_window: "23:00-02:00"
start_mins
Job Attribute
GUI Path
JIL Syntax
start_mins: mins [, mins]...
Description
Indicates the number of minutes past the hour, every hour, on the specified days
or dates, when the job will be started. The days or dates must be specified using
one of the following attributes: days_of_week or run_calendar. This attribute
overrides any times set in a run calendar. The start_mins attribute and the
start_times attribute are mutually exclusive.
Where Applicable
Values
JIL: mins must be a number 0–59, representing the number of minutes past each
hour when the job will be run. The total number of characters must not exceed
255. Multiple lines can be used without specifying a continuation character.
GUI: Enter a number, 0–59, representing the number of minutes past each hour
when the job will be run. The total number of characters must not exceed 255.
You can also enter a number in the Every n Minutes field, then click Apply, this
puts the appropriate intervals in the Minutes after Each Hour field.
GUI: Enter a number, 0–59, representing the number of minutes past each hour
when the job will be run. The total number of characters must not exceed 255.
The keyword start_mins is omitted.
Example
To specify that the job be run at a quarter past and a quarter before each hour,
enter:
start_mins: 15, 45
start_times
Job Attribute
GUI Path
JIL Syntax
start_times: "time [, time]..."
Description
Indicates the times of day, in 24-hour format, on the specified days or dates,
when the job will be started. The days or dates must be specified using one of the
following attributes: days_of_week or run_calendar. This attribute overrides any
times set in a run calendar. The start_times attribute and the start_mins attribute
are mutually exclusive.
Note: If a job runs daily at the same time (example: 12:00) and you EDIT this job
definition and save this job at (11:59), the job will not run today but will run
tomorrow at (12:00).
When a start time job definition is written to the database within “one minute” of
the current runtime, the start time will be placed in the future, meaning
tomorrow. However, if the start time is two minutes or greater from the current
save time the job will run today.
Where Applicable
Values
JIL: time must be specified using the format “hh:mm” where hh specifies hours,
in 24-hour format, and mm specifies minutes.
Be sure to include the quotes, or an error will result. The total number of
characters must not exceed 255. Multiple lines can be used without specifying a
continuation character.
GUI: Enter the time using the format hh:mm where hh specifies hours, in 24-
hour format, and mm specifies minutes. You can enter a comma-separated list of
times.
The default is that no start time will be set. This is an error if days or dates are
specified for this job, and no time has been specified in the other field.
Example
To specify that the job be run at 10:00 a.m. and 2:00 p.m. on every specified day
or date, enter:
start_times: "10:00, 14:00"
std_err_file
Job Attribute
GUI Path
JIL Syntax
std_err_file: pathname
Description
Specifies the file to which the standard error file’s output should be redirected.
Any file for which the job owner has write permission on the client machine can
be specified as the standard error file.
By default, the file will be overwritten with new information. By placing the
following notation as the first characters in the std_err_file specification, you can
specify if the error file should be appended to or overwritten:
> Overwrite file
>> Append file
This setting overrides the instance-wide setting for the Append stdout/ stderr
field on the Administrator Event processor screen.
If you are running jobs across platforms, the Event processor of the issuing
instance controls the default behavior. For UNIX, the default is to append this
file, and for Windows the default is to overwrite this file.
Where Applicable
Values
pathname The path name to which all error output is to be redirected. The full path name
must be specified, although variables exported from the job profile or from the
global variables can be used in the path name specification. If a full path name
is not specified, the job owner’s home directory is assumed. If variable
substitution is used, we recommended that the variable be enclosed in curly
braces, such as in “${PATH}” for variables referenced in the job profile. The
expression $${global_name} should be used for global variables. The path name
must not exceed 80 characters.
The path name to which all error output is to be redirected. The full path name
must be specified, although variables exported from the profile script or from
the global variables can be used in the path name specification. If variable
substitution is used, we recommended that the variable be enclosed in curly
braces, such as in “${PATH}” for variables referenced in the profile file. The
expression $${global_name} should be used for global variables. The path name
must not exceed 80 characters.
When using JIL, if you are including a drive letter with the path name, it must
be escaped; for example "C:\tmp" and C\:\tmp are valid; C:\tmp is not. When
using the Job Editor, do not use quotes.
JIL: Enter the std_err_file keyword and the full path name for the standard error
file.
GUI: Enter the full path name for the standard error file. Omit the keyword
std_err_file.
Examples
4. You can create a unique identifier by appending the process ID to the file
name, using %AUTOPID% as shown in the following example:
std_err_file: "C:\tmp\my_file.%AUTOPID%"
1. To set the file /tmp/test.err to receive standard error file output for the job,
enter:
std_err_file: /tmp/test.err
3. Set the file /tmp/today’s_date.err to receive standard error file output for
the job, set a global variable named “Today” (using sendevent or the Send
Event dialog) to be today’s date, then enter:
std_err_file: /tmp/$${Today}.err
4. You can create a unique identifier by appending the process ID to the file
name, using $$ as shown in the following example:
std_err_file: /tmp/my_file.$$
If you want to embed the process ID in the middle of the file name, you must
follow the $$ with a dot, slash, or space (otherwise Unicenter AutoSys JM
will try to interpret the string following the $$ as a global variable).
Therefore, the following examples are valid:
std_err_file: /tmp/my_file.$$.err
std_err_file: /tmp/my_file.$${}err
Note: In the final example shown previously, the curly braces must be used
to separate the $$ from the string err. Otherwise, Unicenter AutoSys JM
would try to interpret err as a global variable. If unable to find global
variable err, Unicenter AutoSys JM would drop that part of the file name,
creating a file named my_file. (because $$err would be null).
std_in_file
Job Attribute
GUI Path
JIL Syntax
std_in_file: pathname
Description
Specifies the file to which the standard input file for the job should be redirected.
Any file for which the job owner has read permission on the client machine can
be specified as the standard input file.
Where Applicable
Values
pathname The path name to which all standard input is to be redirected. The full path
name must be specified, although variables exported from the job profile or
from the global variables can be used in the path name specification. If a full
path name is not specified, the job owner’s home directory is assumed. If
variable substitution is used, the variable should be enclosed in curly braces,
such as in “${PATH}” for variables referenced in the job profile. The expression
$${global_name} should be used for global variables. The path name must not
exceed 80 characters.
When using JIL, if you are including a drive letter with the path name, it must be
escaped for example "C:\tmp" and C\:\tmp are valid; C:\tmp is not. When
using the Job Editor, do not use quotes.
The path name to which all standard input is to be redirected. The full path
name must be specified, although variables exported from the profile script or
from the global variables can be used in the path name specification. If variable
substitution is used, the variable should be enclosed in curly braces, such as in
“${PATH}” for variables referenced in the profile file. The expression
$${global_name} should be used for global variables. The path name must not
exceed 80 characters.
JIL: Enter the std_in_file keyword and the full path name of the standard input
file.
GUI: Enter the full path name for the standard input file. Omit the keyword
std_in_file.
GUI: Enter the full path name for the standard input file. Omit the keyword
std_in_file.
Examples
1. Set the file named "C:\tmp\TEST.IN" to be read as the standard input file,
enter:
std_in_file: "C:\tmp\TEST.IN"
1. Set the file named /tmp/test.in to be read as the standard input file, enter:
std_in_file: /tmp/test.in
std_out_file
Job Attribute
GUI Path
JIL Syntax
std_out_file: pathname
Description
Specifies the file to which the standard output file should be redirected. Any file
for which the job owner has write permission on the client machine can be
specified as the standard out file. By default, the file will be overwritten with
new information. By placing the following notation as the first characters in the
std_out_file specification, you can specify if the error file should be appended to
or overwritten:
> Overwrite file
>> Append file
This setting overrides the instance-wide setting for the Append stdout/ stderr
field on the Administrator Event processor screen. It also overrides the
machine-specific setting for the AutoMachWideAppend environment variable
that you can set on the Administrator System Information screen.
If you are running jobs across platforms, the event processor of the issuing
instance controls the default behavior. For UNIX, the default is to append this
file, and for Windows the default is to overwrite this file.
Where Applicable
Values
pathname The path name to which all standard output is to be redirected. The full path
name must be specified, although variables exported from the job profile or
from the global variables can be used in the path name specification. If a full
path name is not specified, the job owner’s home directory is assumed. If
variable substitution is used, the variable should be enclosed in curly braces,
such as in “${PATH}” for variables referenced in the job profile. The expression
$${global_name} should be used for global variables. The pathname must not
exceed 80 characters.
When using JIL, if you are including a drive letter with the path name, it must be
escaped for example "C:\tmp" and C\:\tmp are valid; C:\tmp is not. When
using the Job Editor, do not use quotes.
pathname The path name to which all standard output is to be redirected. The full path
name must be specified, although variables exported from the profile script or
from the global variables can be used in the path name specification. If variable
substitution is used, the variable should be enclosed in curly braces, such as in
“${PATH}” for variables referenced in the profile file. The expression
$${global_name} should be used for global variables. The path name must not
exceed 80 characters.
JIL: Enter the std_out_file keyword and the path name of the standard out file.
GUI: Enter the full path and name for the standard out file. Omit the keyword
std_out_file.
GUI: Enter the full path name for the standard out file. Omit the keyword
std_out_file.
Examples
1. Set the file named "C:\tmp\TEST.OUT" to receive standard output for the
job, enter:
std_out_file: "C:\tmp\TEST.OUT"
1. Set the file named /tmp/test.out to receive standard output for the job,
enter:
std_out_file: /tmp/test.out
3. Set the file named /tmp/today’s_date.out to receive standard output for the
job, set a global variable named “Today” (using sendevent or the Send Event
dialog) to be today’s date, then enter:
std_out_file: /tmp/$${Today}.out
4. You can create a unique identifier by appending the process ID to the file
name, using $$ as shown in the following example:
std_out_file: /tmp/my_file.$$
If you want to embed the process ID in the middle of the file name, you must
follow the $$ with a dot, slash, or space (otherwise Unicenter AutoSys JM will
try to interpret the string following the $$ as a global variable). Therefore, the
following examples are valid:
std_out_file: /tmp/my_file.$$.mary
std_out_file: /tmp/my_file.$${}mary
Note: In the example shown here, the curly braces must be used to separate the
$$ from the string “mary.” Otherwise Unicenter AutoSys JM would try to
interpret mary as a global variable. If unable to find global variable mary,
Unicenter AutoSys JM would drop that part of the file name, creating a file
named my_file. (because $$mary would be null).
term_run_time
Job Attribute
GUI Path
Job Definition, Adv Features, Terminate this job Mins after starting
JIL Syntax
term_run_time: mins
Description
Specifies the maximum runtime (in minutes) that a job should require to finish
normally. If the job runs longer than this time, it will be automatically
terminated by Unicenter AutoSys JM.
Note: Windows does not support the concept of process groups. If the job that
was launched was an *.exe, KILLJOB will kill the process specified in the
command definition. If the job being run is not an*.exe, for example: *.bat,
*.cmd, or *.com, Unicenter AutoSys JM uses CMD.EXE to launch the job;
KILLJOB will kill only the CMD.EXE process. The Job Status will be set
according to the return code of the killed CMD.EXE process. This status can be
any one of the following: SUCCESS, FAILURE, or TERMINATED. Any
processes that were launched by user applications or batch (*.bat) files will not
be killed.
Where Applicable
Values
JIL: mins can be any integer, representing the maximum number of minutes the
job should ever require to finish normally.
GUI: Enter the number of minutes, which can be any integer; representing the
maximum number of minutes the job should ever require to finish normally.
Omit the keyword term_run_time.
GUI: Enter the mins, which can be any integer; representing the maximum
number of minutes the job should ever require to finish normally. Omit the
keyword term_run_time.
The default is “0,” indicating the job should be allowed to run forever.
Example
timezone
Job Attribute
GUI Path
JIL Syntax
timezone: zone
Description
Allows you to schedule a job based on a chosen time zone. When the timezone
attribute is specified in a job definition, the time settings in that job are based on
the zone time zone. For example, if you define a start time of 01:00 for a job
running on a machine in Denver, and set timezone to San Francisco (which is in
the Pacific time zone, one hour earlier than Denver), the job will start at 2:00 a.m.
in Denver.
Jobs with time-based starting conditions that do not specify a time zone will
have their start event scheduled based on the time zone under which the Event
processor is running.
Where Applicable
Values
Windows time zones are located in the Date/Time applet in the Control Panel.
The majority of entries in the Time Zone pull-down menu of the Date/Time
applet are cities, any one of which can be specified by the timezone attribute.
For example, if you want a job to run in the time zone Windows NT refers to as
“Bogota, Lima,” you could specify either “Bogota” or “Lima.” Omit spaces and
periods when specifying this attribute; for example, use “MountainTime”
instead of “Mountain Time,” and “SolomonIs” instead of “Solomon Is.”
Note: Some regions may change to daylight saving time at different days and
times than the time zone in which the server machine is running. Any jobs
scheduled to start in such a time zone will run one hour earlier (or later) until the
time zone in the job definition and the time zone where the server is running are
both in the same time scheme (either daylight saving time or standard time).
This is a sample of the timezone table (to display all the entries in the table, use
the autotimezone -l command):
Note: Some regions may change to daylight saving time at different days and
times than the time zone in which the server machine is running. Any jobs
scheduled to start in such a time zone will run one hour earlier (or later) until the
time zone in the job definition and the time zone where the server is running are
both in the same time scheme (either daylight saving time or standard time).
Example
To set the time zone for a job definition to Chicago time, enter:
timezone: Chicago
To set the time zone for a job definition to Pacific time, enter:
timezone: US/Pacific
If you specify a time zone that includes a colon, you must quote the time zone
name if you are using JIL, like:
timezone: "IST-5:30"
If you do not quote a time zone specification that contains a colon, JIL will
interpret the colon as a delimiter, producing unexpected results. However, if you
are using the Job Editor, you do not need to escape the time zone specification.
update_job
JIL Subcommand
Function
Updates an existing job of one of the following types: command job, box job, or
file watcher job.
GUI Path
Job Definition, Job Name, Enter New or Modify Existing Attributes, Save
JIL Syntax
update_job: job_name
Description
Any attributes in the existing definition that are not explicitly replaced by
specifying the attribute in the update_job input will retain their original settings.
If many attributes need to be “unset,” it would be more efficient to delete and re-
insert the new or updated job definitions.
Values
job_name The unique job identifier used to define the original job to Unicenter AutoSys
JM. There is no default value.
Example
watch_file
Job Attribute
GUI Path
Job Editor: for File Watcher Job, Basic tab, File to watch
JIL Syntax
watch_file: pathname
Description
Specifies the full path name of the file for which this file watcher job should
watch. System environment variables, job profile environment variables, and
global variables can be used in the path name specification.
Specifies the file for which this file watcher job should watch. The name of the
file to watch for must be a legal UNIX file name, and it must identify the full
path name of the file. Variables exported from the profile script or global
variables can be used in the path name specification.
This attribute is used in combination with the “watch file minimum file size”
and “watch interval” attributes to determine when a file is considered to have
“arrived.” Unicenter AutoSys JM does not actually consider a file complete until
the minimum file size is reached, and the watch interval has detected a “steady
state” for example: the file size has not changed between checked intervals.
In those cases where the user has control over the application generating the file,
we recommend that the following “fail-safe” scenario be used. Since the
generating application could crash, or a communication link could be
interrupted after having written the minimum size file, Unicenter AutoSys JM
would evaluate that the file was complete, when it actually would not be
complete.
You may use wildcards in the path name. Unicenter AutoSys JM will 'lock on' to
the first file it finds that matches the path. In other words, it will continue to
watch that file even if other files show up that match the path.
On Windows, the asterisk (*) and question mark (?) wildcard characters are
valid. The asterisk substitutes for zero or more characters, while the question
mark substitutes for exactly one character. There is an exception to this: at the
end of a file name '?' will substitute for zero or 1 characters.
Where Applicable
Values
pathname The full path name of the file for which to watch. Variables exported from the
job profile can be used in the path name specification. If variable substitution is
used, we recommend that the variable be enclosed in curly braces, such as in
“${PATH}” for variables referenced in the job profile. The expression
$${global_name} should be used for global variables. The path name must not
exceed 80 characters.
When using JIL, if you are including a drive letter with the path name, it must be
escaped (for example "C:\tmp" and C\:\tmp are valid; C:\tmp is not). When
using the Job Editor, do not use quotes.
GUI: Enter the full path name and name of the file for which to watch.
pathname The full path name of the file for which to watch. Variables exported from the
profile script can be used in the path name specification. If variable substitution
is used, we recommend that the variable be enclosed in curly braces, such as in
“${PATH}” for variables referenced in the profile file. The expression
$${global_name} should be used for global variables. The path name must not
exceed 80 characters.
JIL: Enter the watch_file keyword and the full path name of the file for which to
watch.
GUI: Enter the full path name and name of the file for which to watch. Omit the
keyword watch_file.
Examples
1. Set the file watcher to watch for a file named “C:\tmp\BATCH.IN,” enter:
watch_file: "C:\tmp\BATCH.IN"
2. Set the file watcher to watch for a file whose name has been assigned to a
global variable named “file_1,” enter:
watch_file: $${file_1}
3. Set the file watcher to watch for a file named /tmp/batch.input, enter:
watch_file: "c:\reports\August??.out"
4. Set the file watcher to watch a file in the temp directory that begins with
"pay", enter
watch_file: "c:\temp\pay*"
1. Set the file watcher to watch for a file named /tmp/batch.input, enter:
watch_file: /tmp/batch.input
2. Set the file watcher to watch for a file whose name has been assigned to a
global variable named “file_1,” enter:
watch_file: $${file_1}
3. Set the file watcher to watch for a file of the form /usr/reports/August
XX.out enter:
watch_file: /usr/reports/August??.out
4. Set the file watcher to watch a file in the /tmp directory that begins with
"pay", enter:
watch_file: /tmp/pay*
watch_file_min_size
Job Attribute
GUI Path
Job Editor: for File Watcher Job, Basic tab, Minimum file size (in bytes)
JIL Syntax
watch_file_min_size: bytes
Description
Specifies the watch file minimum size (in bytes), which determines when enough
data has been written to the file to consider it complete. Unicenter AutoSys JM
does not consider a file complete until both the minimum file size is reached, and
the watch interval has detected a “steady state” for example: the file size has not
changed between checked intervals. A reasonable file size should be specified in
order to ensure that a nearly empty file does not appear to be complete, while a
size that is smaller than usual does not prevent the file from being considered
complete.
In those cases where the user has control over the application generating the file,
we recommend that the following “fail-safe” scenario be used. Since the
generating application could crash, or a communication link could be
interrupted after having written the minimum size file, Unicenter AutoSys JM
would think the file was complete, when it actually would not be.
Where Applicable
Values
JIL: bytes can be any integer; representing the minimum number of bytes in the
file before it is considered complete.
GUI: Enter the size in bytes, which can be any integer. This number represents
the minimum number of bytes in the file before it is considered complete.
GUI: Enter the bytes, which can be any integer. This number represents the
minimum number of bytes in the file before it is considered complete. Omit the
keyword watch_file_min_size.
The default is “0,” meaning the mere presence of the file is enough to consider
the file complete.
Example
To set the file to be considered complete when it reaches 10 KB (assuming the file
has reached “steady state” as well), enter:
watch_file_min_size: 10000
watch_interval
Job Attribute
GUI Path
Job Editor: for File Watcher Job, Basic tab, Time Interval (secs) to determine
steady state
Job Definition, Adv Features, Time Interval (secs) to Determine Steady State
JIL Syntax
watch_interval: seconds
Description
Specifies the interval (in seconds) at which the file watcher job will check for the
existence and size of the watched-for file. A “steady state” is said to have been
reached when the file has not grown during the specified time interval. When
the “steady state” has been reached and the file is at least as large as the
minimum file size specified in watch_file_min_size, the file is considered
complete. A reasonable interval should be specified to ensure that the file does
not appear to be at “steady state” when it really is not.
In those cases where the user has control over the application generating the file,
we recommend that the following “fail-safe” scenario be used. Since the
generating application could crash, or a communication link could be
interrupted after having written the minimum size file, Unicenter AutoSys JM
would think the file was complete, when it actually would not be.
Where Applicable
Values
JIL: seconds can be any integer, representing the time interval between checks of
the file existence and file size.
GUI: Enter the number of seconds, which represents the time interval between
checks of the file existence and file size.
GUI: Enter the seconds, which can be any integer; representing the time
interval between checks of the file existence and file size. Omit the keyword
watch_interval.
Example
To set the file to be checked for a steady state every two minutes, enter:
watch_interval: 12
JIL Subcommands
Certain JIL subcommands are used to define the machines upon which AutoSys
operates.
Machine Attributes
Several attributes, are used to define and describe AutoSys machines. Machine
attributes are defined using JIL statements, which are input to the jil command.
Note: AutoSys machines can only be defined and described using JIL
statements.
delete_machine
JIL Subcommand
Function
JIL Syntax
delete_machine: machine_name
Description
If a real machine was defined separately, for example: (not as part of a virtual
machine,) delete_machine will delete it from the virtual machine; however, the
real machine definition will still exist.
Values
machine_name Must be a real or virtual machine currently defined in the AutoSys database.
There is no default.
Examples
1. To delete a real machine named “socrates,” you would issue the following
JIL subcommand:
delete_machine: socrates
3. To delete the entire virtual machine named “ferrari,” you would issue the
following JIL subcommand:
delete_machine: ferrari
Note: Example 3 shown previously deletes only the virtual machine “ferrari.” It
does not however delete any real component machines that were defined
separately.
factor
Machine Attribute
JIL Syntax
factor: real_number
Description
Where Applicable
Values
real_number Any real number within a user-selected range of values. The examples
following show the ranges as 0.0-1.0; however, any reasonable convention can
be chosen. The default value is 1.0.
Examples
1. Set the factor for a very high-performance real machine, when a scale of 0.0-
1.0 is in use, you would enter:
factor: 1.0
2. Set the factor for a relatively low-performance real machine, when a scale of
0.0-1.0 is in use, you would enter something similar to the following:
factor: 0.4
If a job that is ready to start has the virtual machine “italia” specified in its
machine attribute, the Event Processor would perform the necessary
calculations to determine which machine on which to run the job, and reflect
these calculations in its output log as shown following:
EVENT: STARTJOB JOB: test_mach
Checking Machine usages using RSTATD
:<ferrari=78*[1.00]=78> <alfa_romeo=80*[.80]=64>
<fiat=2*[.30]=0.6>
[ferrari connected]
EVENT: CHANGE_STATUS STATUS: STARTING JOB:
test_mach
That is, “ferrari” had more relative CPU cycles available. If max_load
attributes had been specified for the real machines shown previously, the
following scenario would occur.
insert_machine
JIL Subcommand
Function
JIL Syntax
insert_machine: machine_name
Description
■ Real machine
■ Virtual machine
■ NSM
■ AutoSys Connect
The machine type can be specified as either r for real, v for virtual, n for
Windows, t for NSM or a Universal Job Management Agent, and c for AutoSys
Connect. The component real machines in a virtual machine definition must be
all of the same type, for example, all UNIX machines or all Windows machines
(not a mix).
When more than one machine is specified with the job’s machine attribute,
AutoSys must choose on which machine to run the job. In the simplest case, this
is done by querying each machine’s available CPU cycles and multiplying it by
the factor attribute to calculate the “relative available CPU cycles.” The machine
with the largest value will run the job.
Any machine accessible through the TCP/IP protocol can be specified in the
machine attribute of a job; it need not be explicitly defined using the
insert_machine command. However, any undefined machine will have a
default factor of “1.0” and no max_load, meaning that there will be no limit on
the job load assigned to it.
Any machine defined in the /etc/hosts file on the machine running the Event
Processor can be specified in the machine attribute of a job; it need not be
explicitly defined using the insert_machine command. However, any
undefined machine will have a default factor of “1.0” and no max_load,
meaning that there will be no limit on the job load assigned to it.
For more information, see the Unicenter AutoSys Job Management for Windows
User Guide, and the Unicenter AutoSys Job Management for UNIX User Guide.
Values
machine_name The unique name of the machine to be defined. It can be from 1-30
alphanumeric characters, and is terminated with white space; embedded blanks
and tabs are illegal.
Examples
1. Define a real UNIX machine named “socrates,” you would specify the
following JIL subcommand:
insert_machine: socrates
type: r
2. Define a Windows machine named “plato,” you would specify the following
JIL subcommand:
insert_machine: plato
type: n
3. Define a real UNIX machine named “aristotle” with a factor of 1.5 and
capable of handling up to 100 load units, you would specify the following
JIL subcommand and attributes:
insert_machine: aristotle
type: r
max_load: 100
factor: 1.5
4. Define a virtual UNIX machine named “virtual_a” to include two real UNIX
machines, named “socrates” and “tibet,” without specifying factors or loads,
you would specify the following JIL subcommand and attributes:
insert_machine: virtual_a
type: v
machine: socrates
machine: tibet
Note: In the previously shown definitions of virtual machines, the real machines
have no max_load and factor attributes. If the real machines were not previously
defined individually, they will be considered identical in terms of factor and
load limits. As a result, a job specifying the virtual machine name will be
scheduled on whichever of these real machines has the rawest CPU percentage
available. Also, if the real machines are defined again outside of a virtual
machine, the stand-alone real machine can have different values for max_load
and factor. In this case, a job specifying the virtual machine versus a job
specifying the stand-alone real machines will be handled differently.
6. Define a virtual UNIX machine named “virtual_c,” to include two real UNIX
machines named “ferrari” with a factor of 5.0 and a max_load of 400, and
“vw” with a factor of .2 and a max_load of 15, you would specify the
following JIL subcommand and attributes:
insert_machine: virtual_c
type: v
machine: ferrari max_load: 400 factor: 5.0
machine: vw max_load: 15 factor: .2
When a job is to be started on the virtual machine, AutoSys will first determine
which of its component real machines has sufficient available load units to run
the job. If both do, AutoSys queries each machine for its available CPU cycles,
multiplies it by that machine’s factor, and chooses the machine with the largest
value.
Note: In Example 6, the two real machines, when specified in a job definition by
way of the virtual machine, vary considerably in capacity from a scheduling
point of view. However, when these machines are explicitly specified by name in
a job definition, the factor and max_load attributes defined here have no bearing;
they only have these values when specified by the virtual machine name.
7. First define two real UNIX machines individually named “socrates” and
“tibet,” then define a virtual machine named “VIRTUAL_D” to include these
real machines, you would specify the following JIL subcommand and
attributes:
insert_machine: socrates
type: r max_load: 100 factor: 1.0
insert_machine: tibet
type: r max_load: 200 factor 1.0
insert_machine: VIRTUAL_D
type: v
machine: socrates
machine: tibet
8. First define two Windows machines individually named “elm” and “maple,”
then define a virtual machine named “trees” to include these real machines,
you would specify the following JIL subcommand and attributes:
insert_machine: elm
type: n max_load: 100 factor: 1.0
insert_machine: maple
type: n max_load: 200 factor 1.0
insert_machine: trees
type: n
machine: elm
max_load: 50 factor: .1
machine: maple
max_load: 100 factor: 1.0
Note: In Example 8, the max load and factor units for both the real machines are
different in the virtual machine.
1. Define a real machine named “socrates,” you would specify the following
JIL subcommand:
insert_machine: socrates
type: r
2. Define a real machine named “aristotle” with a factor of 1.5 and capable of
handling up to 100 load units, you would specify the following JIL
subcommand and attributes:
insert_machine: aristotle
type: r
max_load: 100
factor: 1.5
Note: In the previously shown definitions of virtual machines, the real machines
have no max_load and factor attributes. If the real machines were not previously
defined individually, they will be considered identical in terms of factor and
load limits. As a result, a job specifying the virtual machine name will be
scheduled on whichever of these real machines has the rawest CPU percentage
available. Also, if the real machines are defined again outside of a virtual
machine, the stand-alone real machine can have different values for max_load
and factor. In this case, a job specifying the virtual machine versus a job
specifying the stand-alone real machines will be handled differently.
When a job is to be started on the virtual machine, AutoSys will first determine
which of its component real machines has sufficient available load units to run
the job. If both do, AutoSys queries each machine for its available CPU cycles,
multiplies it by that machine’s factor, and chooses the machine with the largest
value.
Note: In Example 4, the two real machines, when specified in a job definition by
way of the virtual machine, vary considerably in capacity from a scheduling
point of view. However, when these machines are explicitly specified by name in
a job definition, the factor and max_load attributes defined here have no bearing;
they only have these values when specified by the virtual machine name.
5. First define two real machines individually named “socrates” and “tibet,”
then define a virtual machine named “virtual_d” to include these real
machines, you would specify the following JIL subcommand and attributes:
insert_machine: socrates
type: r max_load: 100 factor: 1.0
insert_machine: tibet
type: r max_load: 200 factor 1.0
insert_machine: virtual_d
type: v
machine: socrates
machine: tibet
Note: In example 5, the max load and factor units for both the real machines are
different in the virtual machine.
machine
Machine Attribute
JIL Syntax
machine: machine_name
Description
Note: This machine attribute differs from the machine attribute used in the job
definition subcommands; in the job definitions, this attribute assigns the job to
one or more real or virtual machines. However, in a machine definition, it makes
a real machine a component of a virtual machine.
Where Applicable
Machine definition
Values
machine_name The unique name of the real machine to be placed in the virtual machine
definition. It can be from 1-30 alphanumeric characters, and is terminated with
white space; embedded blanks and tabs are illegal. There is no default.
Examples
Note: In Example 1, the two real machines do not have their max_load and
factor attributes set. If these two real machines were not previously defined, they
will be considered identical in terms of factor and load limits. As a result, a new
job that specifies the virtual machine name will be scheduled on the real machine
with the rawest CPU percentage available. If these machines are defined again
outside of a virtual machine, the stand-alone real machine can have different
values for max_load and factor. In this case, a job specifying the virtual machine
versus a job specifying the stand-alone real machines will be handled differently.
Note: In Example 2, these two real machines, when specified using the virtual
machine in a job, are considered to vary considerably in capacity from a
scheduling point of view. However, when these machines are explicitly specified
by their real names in a job definition, the factor and max_load defined here
have no bearing; they only have these values when specified by the virtual
machine name.
Note: In Example 1, the two real machines do not have their max_load and
factor attributes set. If these two real machines were not previously defined, they
will be considered identical in terms of factor and load limits. As a result, a new
job that specifies the virtual machine name will be scheduled on the real machine
with the rawest CPU percentage available. If these machines are defined again
outside of a virtual machine, the stand-alone real machine can have different
values for max_load and factor. In this case, a job specifying the virtual machine
versus a job specifying the stand-alone real machines will be handled differently.
Note: In Example 2, these two real machines, when specified using the virtual
machine in a job, are considered to vary considerably in capacity from a
scheduling point of view. However, when these machines are explicitly specified
by their real names in a job definition, the factor and max_load defined here
have no bearing; they only have these values when specified by the virtual
machine name.
max_load
Machine Attribute
JIL Syntax
max_load: load_units
Description
Indicates the maximum load (in load units), which a machine can reasonably
handle. Load units are arbitrary values, the range of which is user-defined; the
examples following use 1-100, for simplicity.
Note: If job_load is not set, a job will run without checking for load units. If a
priority is not set, the priority will default to 0 and the job_load will be ignored.
If more than one machine was set in the job’s machine attribute, the other
machines will be checked for available load units. If none of the machines
presently has the necessary load units available, the job will be “queued” on all
of the specified machines, and will run on the first one with the necessary load
units available (due to the completion of another job).
Note: The job_load attribute has nothing to do with the priority, or ordering, of
jobs in a queue. In addition, the job_load attribute controls what machine the job
will be run on only when it exceeds the max_load of a machine, thus
eliminating that machine.
For more information, see the chapter “JIL/GUI Job Definitions,” in the
Unicenter AutoSys Job Management for Windows User Guide, and the
Unicenter AutoSys Job Management for UNIX User Guide.
Where Applicable
Values
load_units Any real number within a user-selected range of values. The examples
following show the ranges as 1–100, but any reasonable convention can be
chosen. Zero and negative numbers cannot be used. There is no default;
therefore, if no max_load value is set, the load on the machine will not be
limited in any way.
Examples
1. Set the max_load for a very high-performance real machine, when a scale of
1–100 is in use, enter:
max_load: 100
type
Machine Attribute
JIL Syntax
type: {r | v | n | t | c }
Description
Specifies the type of machine being defined. r specifies a real UNIX machine; v
specifies a virtual UNIX machine; n specifies a Windows machine (real or
virtual); t specifies a NSM or a Universal Job Management Agent machine, and c
specifies AutoSys Connect.
Where Applicable
Machine definition
Values
r, v, or n, t, or c.
JIL Subcommands
Certain JIL subcommands can be used for monitoring and generating reports on
AutoSys jobs. When using the AutoSys Monitor/Browser Editor, the same thing
is accomplished by using the corresponding fields and buttons in the various
dialogs.
after_time
Report Attribute
GUI Path
JIL Syntax
after_time: date_time
Description
Specifies the date and time for the start of the reporting period, which the report
being defined should cover. Only events that occurred after this date and time
will be reported on.
Where Applicable
Report definition
Values
You must include the quotes, or an error will result due to the colon in the time.
GUI: Enter the date and time, using the format MM/DD/[YY]YY hh:mm where
MM is the month, DD is the day, [YY]YY is the year, hh is the hour in 24-hour
format, and mm is the minutes.
You can omit the quotes, since colons are not reserved characters when entered
using the Monitor/Browser Editor. The keyword after_time is omitted.
GUI: Enter the date_time, using the format MM/DD/[YY]YY hh:mm where
MM is the month, DD is the day, [YY]YY is the year, hh is the hour in 24-hour
format, and mm is the minutes.
The default, if the curren attribute is set to “no” is 12:00 midnight on the
specified day. If the date is omitted, it defaults to the current day. If the currun
attribute is set to “yes,” the after_time attribute is ignored.
Note: If you enter a two-digit year, AutoSys saves the setting to the database as
a four-digit year. If you enter 79 or less, AutoSys prepends 20, and, if you enter
80 or greater, AutoSys prepends 19.
Example
alarm
Monitor/Report Attribute
GUI Path
Monitor/Browser, Alarms
JIL Syntax
alarm: toggle
Description
Where Applicable
Monitor definition
Report definition
Values
GUI: Check the check box to indicate yes; to change your selection, clear the
check box. The default value is 0 for no.
GUI: Click the button in to indicate yes; to change your selection, click the
button again to indicate no. The default value is 0 for no.
Example
alarm_verif
Monitor Attribute
GUI Path
JIL Syntax
alarm_verif: toggle
Description
Specifies whether alarms should continue to notify the operations staff until
there is a response. When the monitor is running, the verification feature
prompts the user in the window running the monitor for their initials and a
comment. This information is timestamped and recorded in the database, along
with the alarm event. It provides an accounting of the events that were
responded to, and when that occurred.
Where Applicable
Monitor definition
Values
GUI: Check the check box to indicate yes; to change your selection, clear the
check box.
GUI: Click the button to indicate yes; to change your selection, click the button
again to indicate no.
Example
alarm_verif: y
all_events
Monitor/Report Attribute
GUI Path
JIL Syntax
all_events: toggle
Description
Specifies whether all events should be tracked for the monitor or report being
defined. This attribute specifies whether any event filtering is in effect. If it is set
to “yes,” the other event filtering attributes are ignored, and all events,
regardless of source, will be reported for the selected jobs. This includes job
status events, alarms, and manually generated events, such as starting a job.
If set to “no,” the other event selection attributes, including the alarm attribute,
are used to select the events to be tracked.
Notes:
If you wish to monitor all events for all jobs, you should display the event
processor log time in real time, using the following command instead of running
a monitor:
autosyslog -e
You should do this because running a monitor adds another connection to the
database and establishes another process, which is continually polling the
database. This will have a significant impact on system performance.
Furthermore, the information logged by the event processor contains more
diagnostic information than a monitor does.
Where Applicable
Monitor definition
Report definition
Values
GUI: Select the check box to indicate yes; to change your selection, deselect the
check box.
GUI: Click the button to indicate yes; to change your selection, click the button
again to indicate no.
Example
Set the monitor or report to track all events, whether they are AutoSys or
manually-generated job status changes, enter:
all_events: y
all_status
Monitor/Report Attribute
GUI Path
JIL Syntax
all_status: toggle
Description
Specifies whether all job status events should be tracked by the monitor or report
being defined. Job status events occur whenever a job’s status changes. If this
attribute is set to “yes,” all of the individual job status events, which have their
own attributes, as well as a few AutoSys-internal job status events, will be
tracked.
Alarms can be tracked in addition to job status events. If the all_events attribute
is set to “yes,” the all_status attribute is ignored.
Where Applicable
Monitor definition
Report definition
Values
GUI: Check the check box to indicate yes; to change your selection, clear the
check box.
GUI: Click the button to indicate yes; to change your selection, click the button
again to indicate no.
Example
Set the monitor or report to track all job status events, enter:
all_status: y
currun
Report Attribute
GUI Path
JIL Syntax
currun: toggle
Description
Specifies whether only the events in the current or most recent execution of the
specified jobs will be reported. (Jobs are specified using the job_name attribute,
or in the Job Selection Criteria area of the Monitor/ Browser Editor.)
Using this attribute is useful for getting a sense of what is happening currently.
For example, you could select the job status restart event using the Restart
checkbox in the Monitor/Browser Editor, or you could specify the restart
attribute with JIL. Then, you would turn off Job Filtering, by selecting all jobs,
and set the currun attribute to yes to see all of the jobs that have been
automatically restarted by AutoSys in their current or latest run.
Specifies whether only the events in the current or most recent execution of the
specified jobs will be reported. (Jobs are specified using the job_name attribute,
or in the Job Name field of the GUI, in combination with the job_filter attribute
or the Job Filter field in the GUI.)
Using this attribute is useful for getting a sense of what is happening currently.
For example, you could select the job status restart event using the Restart
checkbox in the GUI, or you could specify the restart attribute with JIL. Then,
you would turn off Job Filtering, by selecting all jobs, and set the currun attribute
to yes to see all of the jobs that have been automatically restarted by AutoSys in
their current or latest run.
Where Applicable
Report definition
Values
GUI: Clear the Current Run Only check box to indicate no; Click the check box
to indicate yes.
GUI: Toggle the button off to indicate no; to change your selection, click the
button again to indicate yes.
Example
Set the monitor or report to report only on events in the current or most recent
run of the specified jobs, enter:
currun: y
delete_monbro
JIL Subcommand
GUI Path
Monitor/Browser, Delete
Function
JIL Syntax
delete_monbro: monbro_name
Description
Values
There is no default.
Example
Delete the monitor called “track_alarm,” specify the following JIL subcommand:
delete_monbro: track_alarm
failure
Monitor/Report Attribute
GUI Path
Monitor/Browser, Failure
JIL Syntax
failure: toggle
Description
Specifies whether the job status event generated when a job changes to the
failure state should be tracked by the monitor or report being defined. If either of
the all_events or all_status attributes are set to “yes,” the failure attribute is
ignored. Alarms can be tracked in addition to job status events.
Where Applicable
Monitor definition
Report definition
Values
GUI: Check the check box to indicate yes; to change your selection, clear the
check box.
GUI: Click the button to indicate yes; to change your selection, click the button
again to indicate no.
Example
Set the monitor or report to track jobs changing to the failure state, enter:
failure: y
insert_monbro
JIL Subcommand
Function
JIL Syntax
insert_monbro: monbro_name
Description
In order to use a monitor or report, it must first be defined, then it must be run;
defining it alone has no effect. In order to define a monitor or report, several
attributes must also be specified. These attributes are discussed individually in
this chapter.
For all monitors and reports, the following specifications are required:
- RUNNING
- SUCCESS
- FAILURE
- TERMINATED
- STARTING
- RESTART
■ Alarm attribute
■ For all reports, the time criteria may also need to be specified. For example,
the currun attribute, which specifies that the current or latest run of each job
is to be considered, will be used by default if no other selection is made.
For more information, see the chapter “Monitoring and Reporting Jobs,” in the
Unicenter AutoSys Job Management for Windows User Guide, and the
Unicenter AutoSys Job Management for UNIX User Guide.
Values
monbro_name The unique name of the monitor or report to be defined. It can be from 1-30
alphanumeric characters and is terminated with white space; embedded blanks
and tabs are illegal. There is no default.
Examples
1. Define a report named “success_report” that will browse all jobs for success
in the “current” or most recent execution of the job, specify the following JIL
subcommand and attributes:
insert_monbro: success_report
mode: b /* "browser" can also be specified */
success: y
job_filter: a /* the default */
currun: y /* the default */
2. Define a monitor named “alarm_monitor” that will watch for alarms on all
jobs and sound an audible alarm, specify the following JIL subcommand and
attributes:
insert_monbro: alarm_monitor
mode: m /* "monitor" can also be specified */
alarm: y
job_filter: a /* the default */
sound: y
job_filter
Monitor/Report Attribute
GUI Path
JIL Syntax
job_filter: type
Description
Specifies which jobs are to be monitored or reported on, for the monitor or report
being defined. The events to be tracked are determined by the combination of the
various event filters and the job filter. The job filter can be set to one of three
settings: track all jobs (no filtering), track a single box with the jobs it contains, or
track a single job.
If either of the latter two settings are selected, the name of the job to be tracked
is required. This name can be specified using the job_name attribute or the Job
Name field in the Monitor/Browser Editor Save or Save As dialogs.
If either of the latter two settings are selected, the name of the job to be tracked
is required. This name can be specified using the job_name attribute or the Job
Name field in the GUI.
Where Applicable
Monitor definition
Report definition
Values
j Single job.
GUI: Select one of the following option buttons: All Jobs, Jobs in Box named, or
Single Job named. To change your selection, select a different option button.
GUI: Select one of the following option buttons: ALL Jobs, Box with Its Jobs, or
Single Job. To change your selection, select a different option button.
Example
Set the monitor or report to only track events in the box specified in the
job_name attribute, enter:
job_filter: b
job_name
Monitor/Report Attribute
GUI Path
JIL Syntax
job_name: name
Description
Specifies the box or job for which events are to be monitored or reported on, for
the monitor or report being defined. The events to be tracked are determined by
the combination of the various event filters, the job filter, and the job name. The
job_name attribute is required if the job_filter attribute is set to a single job or to
a box and its jobs; otherwise, it is ignored.
Where Applicable
Monitor definition
Report definition
Values
There is no default.
Example
Set the monitor or report to only track events in the box called “EOD_Box,”
enter:
job_name: EOD_Box
mode
Monitor/Report Attribute
GUI Path
Monitor/Browser, Mode
JIL Syntax
mode: type
Description
Where Applicable
Monitor definition
Report definition
Values
In the Monitor/Browser Editor, the default setting is Monitor, and in JIL there is
no default.
GUI: Click the appropriate Monitor or Browser option button; to change your
selection, click the other button.
There is no default.
Example
GUI Path
Monitor/Browser, Name
JIL Syntax
None.
Description
Specifies the name of the monitor or report being defined, by way of the
Monitor/Browser Editor. When JIL is used, this attribute is included with the
JIL subcommand, for example: insert_monbro: monbro_name. This attribute
must be unique for monitors and reports within an instance of AutoSys, since it
is the primary identifier of the monitor or report. The name cannot be changed
once the monitor or report has been defined, although the monitor or report can
be deleted and redefined.
Specifies the name of the monitor or report being defined, by way of the GUI.
When JIL is used, this attribute is included with the JIL subcommand, for
example: insert_monbro: monbro_name. This attribute must be unique for
monitors and reports within an instance of AutoSys, since it is the primary
identifier of the monitor or report. The name cannot be changed once the
monitor or report has been defined, although the monitor or report can be
deleted and redefined.
Where Applicable
Values
GUI: Enter the new monitor or report name in the Save or Save As dialog. The
name can be up to 30 alphanumeric characters, including the underscore (_)
character. Embedded blanks and tabs are illegal.
GUI: Enter the monitor or report name. The name can be up to 30 alphanumeric
characters, including the underscore (_) character. Embedded blanks and tabs
are illegal.
restart
Monitor/Report Attribute
GUI Path
Monitor/Browser, ReStart
JIL Syntax
restart: toggle
Description
Specifies whether the job status event generated when a job changes to the
restart state should be tracked by the monitor or report being defined. If either of
the all_events or all_status attributes are set to “yes,” the restart attribute is
ignored. Alarms can be tracked in addition to job status events.
Where Applicable
Monitor definition
Report definition
Values
GUI: Check the check box to indicate yes; to change your selection, clear the
check box.
GUI: Click the button to indicate yes; to change your selection, click the button
again to indicate no.
Example
Set the monitor or report to track jobs changing to the restart state, enter:
restart: y
running
Monitor/Report Attribute
GUI Path
Monitor/Browser, Running
JIL Syntax
running: toggle
Description
Specifies whether the job status event generated when a job changes to the
running state should be tracked by the monitor or report being defined.
If either of the all_events or all_status attributes are set to “yes,” the running
attribute is ignored. Alarms can be tracked in addition to job status events.
Where Applicable
Monitor definition
Report definition
Values
GUI: Check the check box to indicate yes; to change your selection, clear the
check box.
GUI: Click the button to indicate yes; to change your selection, click the button
again to indicate no.
Example
Set the monitor or report to track jobs changing to the running state, enter:
running: y
sound
Monitor Attribute
GUI Path
Monitor/Browser, Sound
JIL Syntax
sound: toggle
Description
Specifies whether the appropriate sound clip for the specified events should be
played when a tracked event is seen by the monitor being defined.
If the workstation running the monitor has sound capabilities, AutoSys will use
them to announce the events as they occur. If there is no sound capability, this
attribute is ignored. The announced message is pieced together from pre-
recorded sound clips.
Note: You should use sound for monitoring AutoSys, especially alarms. It frees
you from needing to examine output files to see if there are any problems. Some
users have plugged their machine into the P.A. system, or other external
amplifiers.
For more information, see the chapter “AutoSys Administrator,” in the Unicenter
AutoSys Job Management for Windows User Guide, or the chapter “AutoSys
Commands,” in this guide.
Where Applicable
Monitor definition
Values
GUI: Check the check box to indicate yes; to change your selection, clear the
check box.
GUI: Click the button to indicate yes; to change your selection, click the button
again to indicate no.
Example
Set the monitor to play the appropriate sound clip for a specified event, enter:
sound: y
starting
Monitor/Report Attribute
GUI Path
Monitor/Browser, Starting
JIL Syntax
starting: toggle
Description
Specifies whether the job status event generated when a job changes to the
starting state should be tracked by the monitor or report being defined.
If either of the all_events or all_status attributes are set to “yes,” the starting
attribute is ignored. Alarms can be tracked in addition to job status events.
Where Applicable
Monitor definition
Report definition
Values
GUI: Check the check box to indicate yes; to change your selection, clear the
check box.
GUI: Click the button to indicate yes; to change your selection, click the button
again to indicate no.
Example
Set the monitor or report to track jobs changing to the starting state, enter:
starting: y
success
Monitor/Report Attribute
GUI Path
Monitor/Browser, Success
JIL Syntax
success: toggle
Description
Specifies whether the job status event generated when a job changes to the
success state should be tracked by the monitor or report being defined.
If either of the all_events or all_status attributes are set to “yes,” the success
attribute is ignored. Alarms can be tracked in addition to job status events.
Where Applicable
Monitor definition
Report definition
Values
GUI: Check the check box to indicate yes; to change your selection, clear the
check box.
GUI: Click the button to indicate yes; to change your selection, click the button
again to indicate no.
Example
Set the monitor or report to track jobs changing to the success state, enter:
success: y
terminated
Monitor/Report Attribute
GUI Path
Monitor/Browser, Terminated
JIL Syntax
terminated: toggle
Description
Specifies whether the job status event generated when a job changes to the
terminated state should be tracked by the monitor or report being defined.
If either of the all_events or all_status attributes are set to “yes,” the terminated
attribute is ignored. Alarms can be tracked in addition to job status events.
Where Applicable
Monitor definition
Report definition
Values
GUI: Check the check box to indicate yes; to change your selection, clear the
check box.
GUI: Click the button to indicate yes; to change your selection, click the button
again to indicate no.
Example
Set the monitor or report to track jobs changing to the terminated state, enter:
terminated: y
update_monbro
JIL Subcommand
GUI Path
Monitor/Browser, Save
Function
JIL Syntax
update_monbro: monbro_name
Description
Any attributes in the existing definition which are not explicitly replaced by
specifying the attribute in the update_monbro input will retain their original
settings. If many attributes need to be “unset,” use the alternative method of
deleting and redefining the monitor or report definition, because it would be
more efficient.
For more information, see the chapter “Monitoring and Reporting Jobs,” in the
Unicenter AutoSys Job Management for Windows User Guide, and the
Unicenter AutoSys Job Management for UNIX User Guide.
Values
monbro_name The unique name of the monitor or report to be modified. There is no default.
Example
update_monbro: alarm_monitor
terminated: y
System States
A
Events
The following is the list of events that Unicenter AutoSys JM processes. Some of
these events are generated internally, while some only occur when sent
manually using the sendevent command. In effect, manual events are runtime
commands for the event processor. In the listing following, each event’s internal
code assignment is provided next to the event in parenthesis. This code number
is used for viewing the event in the database event table.
ALARM (106)
CHANGE_PRIORITY (120)
Changes the priority of a job. If the job is in the QUE_WAIT state, it changes it
immediately, and possibly starts the job. If the job is not yet in the QUE_WAIT
state, it changes the priority for the next run of the job only. A permanent change
of priority can be done by editing the job definition.
CHANGE_STATUS (101)
Changes the value of the status for a specific job. When the event processor
processes this event, it initiates any actions that are dependent upon this status
of this job. The values of status are listed later in this appendix.
CHECK_HEARTBEAT (116)
Instructs the event processor to check all jobs that have specified a heartbeat
interval to see if any are missing. If so, a MISSING_HEARTBEAT alarm will be
sent. If the event processor is configured to do so, it will perform this check
automatically.
CHK_BOX_TERM (118)
An internally generated event that instructs the event processor to check if a box
job has run for more than its Maximum Runtime (max_run_time) value.
CHK_MAX_ALARM (114)
CHK_RUN_WINDOW (122)
A future event set to run at the end of a job’s run window, to see if the job has
run or not.
COMMENT (117)
For information purposes only. This event can be associated with a job and as a
result, is displayed on reports (autorep). It is a method for generating comments
at runtime and have them be associated with a specific run of a job.
DELETEJOB (119)
Tells AutoSys to delete this job. If the job is a box, it deletes everything within the
box.
EXTERNAL_DEPENDENCY (127)
FORCE_STARTJOB (108)
Event to start a job, regardless of any conditions on this job. This event is never
generated, and should be used only in the event of system problems. Using this
event, it is possible to start the same job twice, and as a result, have two instances
of the job running at the same time. For this reason, we recommend that this
command be used only with extreme caution.
For example: You scheduled Job-1 to run every Monday at 3:00 A.M, however,
on Sunday you placed this job ON_HOLD. If you FORCE_START Job-1 on
Wednesday at 2:00 P.M., Job-1 will run to completion (either success or failure),
and then run again as scheduled on Monday at 3:00 A.M.
HEARTBEAT (115)
The event sent from the Remote Agent posting a heartbeat for a given job. This
event is internally generated.
JOB_ON_ICE (110)
Event that instructs the event processor to place a job ON_ICE. If the job is in the
STARTING or RUNNING state, it will not place the job ON_ICE. This event is
manually generated.
JOB_OFF_ICE (111)
Event that instructs the event processor to take a job OFF_ICE. If the job is in a
RUNNING box, it will attempt to start it, conditions permitting. This event is
manually generated.
JOB_ON_HOLD (112)
Event that instructs the event processor to place a job ON_HOLD. If the job is in
the STARTING or RUNNING state, it will not place the job ON_HOLD. This
event is manually generated.
JOB_OFF_HOLD (113)
Event to take the job OFF_HOLD. The starting of the job will continue as it was
before it was placed ON_HOLD. This method takes a job OFF_HOLD when
using the AutoHold feature.
KILLJOB (105)
Instructs the event processor to kill a specific job. If the specified job is a box, it
will change the box status to TERMINATED, and, if so configured, kill the jobs
within it. This event is manually generated.
Notes:
Windows does not support the concept of process groups. If the job that was
launched was a *.exe, KILLJOB will kill the process specified in the command
definition. If the job being run is not a *.exe, for example, *.bat, *.cmd, or *.com,
AutoSys uses CMD.EXE to launch the job; KILLJOB will kill only the CMD.EXE
process. The Job Status will be set according to the return code of the killed
CMD.EXE process. This status can be any one of the following: SUCCESS,
FAILURE, or TERMINATED. Any processes that were launched by user
applications or batch (*.bat) files will not be killed.
REFRESH_BROKER (129)
An internally generated event by the Event Processor when the Broker starts up.
It triggers all external dependencies to be sent by the event processor to the
Broker.
RESEND_EXTERNAL_STATUS (128)
SET_GLOBAL (125)
Sets a global variable. This event is sent with a high priority so that the event
processor will process the variable before it is referenced by any jobs at runtime.
SEND_SIGNAL(126)
STARTJOB (107)
Event to start a job, if and only if the starting conditions are satisfied, and if it is
not already running. STARTJOB is the recommended way to start a job
manually.
STOP_DEMON (109)
Status
Every job has a status, or current state, associated with it; these are described in
this section. Unicenter AutoSys JM moves jobs through these states as it
processes the events. Also provided are the internal codes for status, for use
when accessing the job_status table in the database.
ACTIVATED (9)
Top-level box that this job is in is now in the RUNNING state. This status does
not have an event associated with it. It is an internal state only.
FAILURE (5)
For command jobs, the command exited with an exit code greater than the
maximum success value specified for this job. If a box, it means that the failure
conditions for the box evaluated to true.
INACTIVE (8)
Job is inactive; it has no status, by(or in) itself. For example, a newly created job,
which has not run yet is inactive.
ON_HOLD (11)
Job is on hold and will not be run until it receives the JOB_OFF_HOLD event.
ON_ICE (7)
Job is removed from all conditions and logic, but is still defined. Operationally, it
is like deactivating the job.
QUE_WAIT (12)
The job can logically start, has a nonzero priority, and the machines on which it
can start do not have enough available load units. When the required load units
become available, Unicenter AutoSys JM will start the job. To remove a job from
QUE_WAIT, use:
sendevent -E CHANGE_PRIORITY -J job_name -q 0
RESTART (10)
Job was unable to start due to hardware or application problems, and has been
scheduled to restart.
RUNNING (1)
Job is running. If the job is a box, this means that the jobs within it may be started
(other conditions permitting). If it is a command or file watcher job, it means that
the process is actually running on the remote machine.
STARTING (3)
Event Processor has initiated the start procedure with the Remote Agent. The job
is in the process of “coming up.” This status is only for command and file
watcher jobs, not box jobs.
SUCCESS (4)
Job exited and is considered to be successful, as determined by the exit code for a
command job, and the success conditions for a box job.
TERMINATED (6)
Alarms
The following is a list of the alarms that may be generated.
AUTO_PING (526)
CHASE (514)
The chase command has found a problem with a job that is supposedly running.
The job and the problem are listed.
DATABASE_COMM (516)
The Remote Agent had trouble sending an event to the database. The job
probably ran successfully. Inspect the Remote Agent Log file to determine what
happened.
DB_PROBLEM (523)
There is a problem with one of the databases, such as a lack of free space. This
alarm can trigger a user-specified notification procedure.
DB_ROLLOVER (519)
DUPLICATE_EVENT (524)
Duplicate events have been received in the Event Server. Typically, this means
that two event processors are up and running, although duplicate events can
also be caused by Event Server configuration errors.
EP_HIGH_AVAIL (522)
Can mean that the Third Machine for resolving contentions between two event
processors cannot be reached, that the event processor is shutting down, or that
there are other event processor take over problems. This alarm can trigger a user-
specified notification procedure.
EP_ROLLOVER (520)
The Shadow event processor is taking over processing. This alarm can trigger a
user-specified notification procedure.
EP_SHUTDOWN (521)
The event processor is shutting down. This may be due to a normal shutdown
(SEND_EVENT triggered by sendevent -E STOP_DEMON), or due to an error
condition. This alarm can trigger a user-specified notification procedure.
EVENT_HDLR_ERROR (507)
The event processor had an error while processing an event. The job associated
with that event should be inspected to see if manual intervention is required.
EVENT_QUE_ERROR (508)
EXTERN_DEPS_ERROR (529)
The Broker is unable to send external dependencies to the remote node. The
alarm text message identifies the falling remote node.
FORKFAIL (501)
The Remote Agent was unable to start the user command because it was unable
to get a process slot on the UNIX machine. When this happens, Unicenter
AutoSys JM will automatically attempt a RESTART. This alarm can occur only
when a job is running on a UNIX machine.
INSTANCE_UNAVAILABLE (525)
When different instances communicate with each other, this alarm is generated
when the Event Server of the receiving instance cannot be reached. The Event
Server is probably down.
JOBFAILURE (503)
A job has failed or was terminated. Its status is now FAILURE or TERMINATED.
JOBNOT_ONICEHOLD (509)
MAX_RETRYS (505)
MAXRUNALARM (510)
The job has been running for a time greater than that defined in the Maximum
Runtime alarm (max_run_alarm) field in the Job Editor for that job. The job may
continue to run; this event generates a warning alarm.
MINRUNALARM (502)
The job has completed running in less time than that defined in the Minimum
Runtime alarm (min_run_alarm) field Job Editor for that job.
MISSING_HEARTBEAT (513)
A job has not sent a HEARTBEAT within the interval specified for that job. The
operator should inspect the job to see why.
MULTIPLE_EP_SHUTDOWN (530)
RESOURCE (512)
A resource, such as file space, needed for this job was not available. Specific
information about the problem is in the comment associated with this alarm. If
Unicenter AutoSys JM encounters a resource problem, it will attempt to restart
the job after a suitable delay.
STARTJOBFAIL (506)
Unicenter AutoSys JM was unable to start the job. This is generally due to
communication problems with the remote machine. Unicenter AutoSys JM will
attempt to restart the job.
VERSION_MISMATCH (518)
Generated by the Remote Agent when the calling routine, for example: Event
Processor, chase, clean_files, autoping, and so forth, is at a different version
number than the Remote Agent. Inspect the Remote Agent Log file for the exact
version mismatch. The proper Remote Agent version should be installed.
Exit Codes
When you use the autosyslog -J command to display the Remote Agent log file
for a specified job, you may see an entry containing one of the following exit
codes. If the exit code contains two numbers in parentheses, for example: (0 1),
the first number is the UNIX signal, and the second number is the exit code. If a
job is killed or terminated, the exit code remains at zero, which is what it was set
to when the job started.
Because Unicenter AutoSys JM uses a relational database, you can query the
database to supply custom reports and information. All of the DDL (Data
Definition Language) for the database is in the following directory:
$AUTOSYS/dbobj
The table definitions are in file named table_name.tbl, and the view definitions
are in the view_name.view file.
alarmode
This table stores configuration information, such as autotrack level and remote
authentication level, used by the event processor.
WARNING! Do not change this table or you may crash the installation.
alarm
This table stores all the alarms. Each alarm has a unique eoid (event object ID),
which is the reference to the event that created the alarm.
audit_info
This table stores most of the autotrack utility information. You can archive this
table by using the -l option with the archive_events command. The audit_msg
table contains additional information.
audit_msg
This table stores additional autotrack utility information. You can archive this
table by using the -l option with the archive_events command. The audit_info
and audit_msg tables combined contain all of the autotrack utility information.
avg_job_runs
Each job has a row in this table, with the field named joid (job object ID) being
the unique key. Each row of the table contains a job’s calculated average
runtime, based on the data in the job_runs table. In addition, each row contains a
field named num_runs, which indicates how many runs were used to calculate
the average runtime.
calendar
The calendar table contains a list of the dates for each calendar. Multiple
calendars may be defined, and they are referenced by unique names.
chase
This table stores chase utility information. Information remains in the chase table
only temporarily.
cred
This table stores in encrypted format the Windows user passwords entered
through the autosys_secure utility.
WARNING! You can change the information in this table only by using utilities.
If you use SQL commands to make any changes, jobs may fail.
event
Each event is a row in the event table. When an event is processed, it is moved
through the different processing states by changing the field que_status. Each
event has an identifier called its eoid, which is unique across all instances. This
ensures that events can never be lost, confused, or overwritten when you run
multiple instances. This table can be archived using the -n option with the
archive_events command.
WARNING! You can change the information in this table only by using utilities.
If you use SQL commands to make any changes, your jobs and events will not
run.
event0
This table stores unprocessed events for the event processor. Each unprocessed
event has a unique eoid. The information remains in the event0 table
temporarily.
event2
This table stores duplicate events, which each have a unique eoid. Under normal
conditions the event2 table is empty.
eventvu
This view of the event table presents the information in that table in a more
readable form. Most notably, all the events, alarms, and statuses are displayed in
an easily interpreted textual format.
ext_job
This table stores the status of external job dependencies. If jobs on one instance
have dependencies on jobs that run on another instance, this table specifies the
status of the referenced jobs that are running on the other instance.
glob
Each global variable is a row in the glob table, with the field named glo_name
being the unique key.
intcodes
This table stores all the numeric codes—alarm, event, and status codes—used in
the other tables. These other tables reference the intcodes table.
job
Each job is a row in the job table, with the field named joid (job object ID) being
the unique key. Most of the parameters for all the job definitions are contained in
this table. The job2 table contains the remaining parameters.
WARNING! You can change the information in this table only by using utilities.
If you use SQL commands to make any changes, your jobs and events will not
run.
job2
This table is an extension of the job table. The parameters for the job definitions
that are not in the job table are contained in this table. The job and job2 tables
combined contain all of the parameters for all of the job definitions.
job_cond
job_runs
Each job run is a row in this table, with the fields named joid (job object ID),
run_num (run number), and ntry (number of tries to run the job) being the
unique keys. Each row of the table contains a job’s start time, end time, runtime
(in seconds), completion status, and exit code. The Event Processor updates this
table. The table can be archived using the archive_events command with the -j
option.
job_status
The current run information for every job is stored in this table. It is also
identified by the key field named joid. Information such as the current status,
run number, last start time, last end time, and exit code are also in this table.
jobst
This view contains the information from both the job and job_status tables.
keymaster
This table stores all of the license keys and the information associated with them.
last_Eoid_counter
This table stores the number of the last event; the last Eoid used by the event
processor.
machine
This table stores the machine definitions entered through JIL by using the
insert_machine command.
monbro
Each monitor or report (browser) definition is a row in this table. All monitors
and reports are contained in this table.
msg_ack
This table is used when the Verification Required for Alarms feature is set for a
monitor. This table contains the alarm ID that is responded to (eoid), who
responded to the alarm, what time it was first reported, what time it was
acknowledged, and a short comment from the operator.
next_oid
This table stores all of the oid (other ID) counters except the eoid used by the
event processor (stored in the last_Eoid_counter table).
next_run_num
overjob
This table stores the attributes for job overrides and the run number for which
the overrides were applied. The indexes to this table are joid and over_num,
where joid is the unique job ID and over_num is the number of the override for
that job. The value of over_num is assigned at the time an override is defined,
and it is stored in the job_status table until runtime.
req_job
This table stores the jobs on one instance that are referenced in the starting
dependencies of jobs running on another instance.
restart
This table stores jobs that are in RESTART state. The information remains in the
restart table temporarily.
timezones
This table stores time zone information. If you create your own time zones with
the autotimezone utility, that information is also stored in the timezones table.
wait_que
This table stores information about jobs in the QUE_WAIT state. The information
remains in the wait_que table temporarily.
Event Codes
Event codes are used in the event table. The following table contains the numeric
codes and associated event types.
For descriptions of the events, see the appendix “System States,” in this guide.
103 CHK_N_START
105 KILLJOB
106 ALARM
108 FORCE_STARTJOB
109 STOP_DEMON
110 JOB_ON_ICE
111 JOB_OFF_ICE
112 JOB_ON_HOLD
113 JOB_OFF_HOLD
114 CHK_MAX_ALARM
115 HEARTBEAT
116 CHECK_HEARTBEAT
117 COMMENT
118 CHK_BOX_TERM
119 DELETEJOB
120 CHANGE_PRIORITY
121 QUE_RECOVERY
122 CHK_RUN_WINDOW
125 SET_GLOBAL
126 SEND_SIGNAL
127 EXTERNAL_DEPENDENCY
128 RESEND_EXTERNAL_STATUS
129 REFRESH_BROKER
For descriptions of the events, see the appendix “System States,” in this guide.
3 STARTING
4 SUCCESS
5 FAILURE
6 TERMINATED
7 ON_ICE
8 INACTIVE
9 ACTIVATED
10 RESTART
11 ON_HOLD
12 QUE_WAIT
1 processing
2 processed
3 processed w/errors
4 unsent event
Alarm Codes
Alarm codes are used in the alarm and event tables. The following table contains
the numeric codes and associated alarm types.
502 MINRUNALARM
503 JOBFAILURE
505 MAX_RETRYS
506 STARTJOBFAIL
507 EVENT_HDLR_ERROR
508 EVENT_QUE_ERROR
509 JOBNOT_ONICEHOLD
510 MAXRUNALARM
512 RESOURCE
513 MISSING_HEARTBEAT
514 CHASE
516 DATABASE_COMM
518 VERSION_MISMATCH
519 DB_ROLLOVER
520 EP_ROLLOVER
521 EP_SHUTDOWN
522 EP_HIGH_AVAIL
523 DB_PROBLEM
524 DUPLICATE_EVENT
525 INSTANCE_UNAVAILABLE
526 AUTO_PING
For descriptions of the alarms, see the appendix “System States,” in this guide.
44 acknowledged
45 closed
API
C
Unicenter AutoSys JM provides a C Programming Language API that enables
you to integrate events and alarms into your processing environment. This API
is comprised of two functions: get_auto_event, which gives you direct
programmatic access to all events in the system and autoheartbeat, which
generates heartbeats. With autoheartbeat, you can modify a program to run
under Unicenter AutoSys JM control that will send “heartbeats” to indicate the
program is still running. This enables Unicenter AutoSys JM to monitor the
execution of the program and notify you if the application becomes inactive.
This chapter describes how to integrate events and alarms into the user’s
processing environment by way of the application program API.
API C–1
Accessing Events from the Database
■ autosys_api.h
■ libauto.a
■ test_api
■ autosys_api.lib
■ testheart.c
■ test_api.c
All the files you need to access events in the database, including an example
file, are located in the $AUTOSYS/code directory, and are listed following:
■ autosys_api.h
■ libauto.a
■ test_api
■ test_api.c
■ test_api.m (makefile)
■ heartbeat.c
■ heartbeat.sh
The API reads the event information directly from the database. As a result, if
the event processor is lost due to hardware problems, the events will still be
available to the API. Furthermore, you can control the API so that it will attempt
to reconnect to the database if the database is unavailable.
get_auto_event()
get_auto_event()
get_auto_event ( )
Name
Prototype
int get_auto_event(struct event_api *, int);
Synopsis
#include <autosys_api.h>
int get_auto_event(event, polling_freq)
struct event_api *event;
int polling_freq;
Description
get_auto_event() loads the structure pointed to by * with the full event entry. The
events are returned in the order in which they are posted to the database. Events
can be reported to the API before they are processed by the event processor.
The event_api structure is defined in the header file autosys_api.h, like the
following:
struct event_api
{
oid joid;
char roid[EOIDLEN+1];
char job_name[NAMELEN+1];
char box_name[NAMELEN+1];
char eventtxt[NAMELEN+1];
char statustxt[NAMELEN+1];
char alarmtxt[NAMELEN+1];
char event_time[DATETIMELEN+1];
int exit_code;
int run_num;
int ntry;
char machine[NAMELEN+1];
char comment[256];
};
API C–3
Accessing Events from the Database
Sample
get_auto_event(&event, POLL_FREQ)
If a field is not used for a given event, it will be defined as a NULL terminated
string. The only field guaranteed to be present is eventtxt.
The value POLL_FREQ instructs the API how often to inspect the database for a
new event.
Return Values
Sending Heartbeats
A function call can be embedded in an application program that executes under
AutoSys control to periodically send a message to the Event processor signaling
that the application is still processing normally. If the Event processor does not
receive a message within the time interval specified in the HeartBeat Interval
field on the Administrator Event Processor screen, an error condition is
detected, and then the condition can be handled appropriately. This is the
function, which is located in the autosys_api.h file:
autoheartbeat()
API C–5
Sending Heartbeats
autoheartbeat ( )
Name
Prototype
int autoheartbeat(void)
Synopsis
int autoheartbeat()
Description
autoheartbeat() sets an event for the Remote Agent, which sends it on to the
event processor.
For more information, see the chapter “Administrator,” in the Unicenter AutoSys
Job Management for Windows User Guide, or the chapter “Configuring,” in the
Unicenter AutoSys Job Management for UNIX User Guide.
Return Values
A archive_events, 2-4
asrcs_config, 2-8
Accessing Events from the Database, C-2 hosts, 2-11
port number, 2-10
Alarm Codes, B-10
rcs directories, 2-12
Alarm State Codes, B-11 running, 2-9
alarm_if_fail, 3-3 auto_delete, 3-5
Alarms, A-8 auto_hold, 3-7
AUTO_PING (526), A-8
autocal, 2-13
CHASE (514), A-8
DATABASE_COMM (516), A-8 autocal_asc, 2-15
DB_PROBLEM (523), A-8
autocons, 2-18
DB_ROLLOVER (519), A-8
DUPLICATE_EVENT (524), A-8 autoeac_test, 2-20
EP_HIGH_AVAIL (522), A-9
autoflags, 2-23
EP_ROLLOVER (520), A-9
EP_SHUTDOWN (521), A-9 autoping, 2-25
EVENT_HDLR_ERROR (507), A-9 autorep, 2-28
EVENT_QUE_ERROR (508), A-9
EXTERN_DEPS_ERROR (529), A-9 autosc, 2-39
FORKFAIL (501), A-10 autostatus, 2-40
INSTANCE_UNAVAILABLE (525), A-10
JOBFAILURE (503), A-10 AutoSys
JOBNOT_ONICEHOLD (509), A-10 Database Numeric Codes, B-7
MAX_RETRYS (505), A-11 Event Codes, B-7
MAXRUNALARM (510), A-11 Exit Codes, A-13
MINRUNALARM (502), A-11 Tables and Views
MISSING_HEARTBEAT (513), A-11 glob, B-4
MULTIPLE_EP_SHUTDOWN (530), A-11 Tables and Views, B-1
alamode, B-2
Index–1
alarm, B-2 restart, B-7
audit_info, B-2 Tables and Views
audit_msg, B-2 timezones, B-7
avg_job_runs, B-2 Tables and Views
calendar, B-2 wait_que, B-7
chase, B-3
AutoSys
cred, B-3
Functional Listing of Commands, 2-2
event, B-3
event0, B-3 autosys_secure, 2-46
event2, B-3
autosyslog, 2-43
eventvu, B-4
ext_job, B-4 autotimezone, 2-69
Tables and Views autotrack, 2-75
intcodes, B-4
Tables and Views avg_runtime, 3-9
job, B-4
Tables and Views
job2, B-4 B
Tables and Views
job_cond, B-5 box_failure, 3-10
Tables and Views
box_name, 3-12
job_runs, B-5
Tables and Views box_success, 3-14
job_status, B-5
box_terminator, 3-16
Tables and Views
jobst, B-5
Tables and Views
C
keymaster, B-5
Tables and Views
last_Eoid_counter, B-5 chase, 2-82
Tables and Views chk_auto_up, 2-86
machine, B-6
Tables and Views chk_cond (SP), 2-90
monbro, B-6 chk_files, 3-18
Tables and Views
clean_files, 2-92
msg_ack, B-6
Tables and Views command, 3-21
next_oid, B-6
condition, 3-27
Tables and Views
next_run_num, B-6 cron2jil, 2-94
Tables and Views
overjob, B-6
Tables and Views
req_job, B-6
Tables and Views
days_of_week, 3-37
dbstatistics, 2-96 F
delete_box, 3-39
factor, 4-4
delete_job, 3-40
delete_machine, 4-2
description, 3-41
G
E GUI
job_name, 3-49
Index–3
job_name, 3-49 Attributes
job_name, 5-19
job_terminator, 3-50
Attributes
job_type, 3-52 mode, 5-20
Attributes
monbro_name, 5-22
L Attributes
restart, 5-24
load_job, 3-47 Attributes
running, 5-25
Attributes
M sound, 5-26
Attributes
starting, 5-28
machine, 3-54, 4-12 Attributes
max_exit_success, 3-57 success, 5-29
Attributes
max_load, 4-15
terminated, 5-30
max_run_alarm, 3-59 Attributes
update_monbro, 5-31
min_run_alarm, 3-61
JIL
monbro, 2-113 Sub-commands, 5-1
Monitor/Report
Attributes, 5-1
Attributes
N
after-time, 5-2
Attributes n_retrys, 3-63
alarm, 5-4
Attributes
alarm_verif, 5-5 O
Attributes
all_events, 5-7
override_job, 3-64
Attributes
all_status, 5-9 owner, 3-67
Attributes
currun, 5-11
Attributes P
delete_monbro, 5-13
Attributes permission, 3-72
failure, 5-14
Attributes priority, 3-77
insert_monbro, 5-15 profile, 3-79
Attributes
job_filter, 5-17
record_sounds, 2-116
type, 4-17
S
sendevent, 2-118 U
sendevent (SP), 2-130
update_job, 3-106
Sending Heartbeats, C-5
start_mins, 3-88
W
start_times, 3-90
Status, A-6
watch_file, 3-107
ACTIVATED (9), A-6
FAILURE (5), A-6 watch_file_min_size, 3-110
INACTIVE(8), A-6 watch_interval, 3-112
ON_HOLD (11), A-6
ON_ICE (7), A-6
QUE_WAIT (12), A-7 X
RESTART (10), A-7
RUNNING (1), A-7
STARTING (3), A-7 xql, 2-133
Index–5