Batch Services

Batch Services
User's Guide
Version 6.1
October 2011
DPDS3-PE-200051C-UPDATED
Copyright
Copyright 1994-2011 Intergraph Corporation. All Rights Reserved.
Including software, file formats, and audiovisual displays; may be used pursuant to applicable software license agreement;
contains confidential and proprietary information of Intergraph and/or third parties which is protected by copyright law, trade
secret law, and international treaty, and may not be provided or otherwise made available without proper authorization from
Intergraph Corporation.
U.S. Government Restricted Rights Legend

Use, duplication, or disclosure by the government is subject to restrictions as set forth below. For civilian agencies: This was
developed at private expense and is "restricted computer software" submitted with restricted rights in accordance with
subparagraphs (a) through (d) of the Commercial Computer Software - Restricted Rights clause at 52.227-19 of the Federal
Acquisition Regulations ("FAR") and its successors, and is unpublished and all rights are reserved under the copyright laws of
the United States. For units of the Department of Defense ("DoD"): This is "commercial computer software" as defined at DFARS
252.227-7014 and the rights of the Government are as specified at DFARS 227.7202-3.
Unpublished - rights reserved under the copyright laws of the United States.
Intergraph Corporation
P.O. Box 240000
Huntsville, AL 35813
Terms of Use
Use of this software product is subject to the End User License Agreement ("EULA") delivered with this software product unless
the licensee has a valid signed license for this software product with Intergraph Corporation. If the licensee has a valid si gned
license for this software product with Intergraph Corporation, the valid signed license shall take precedence and govern the use
of this software product. Subject to the terms contained within the applicable license agreement, Intergraph Corporation gives
licensee permission to print a reasonable number of copies of the documentation as defined in the applicable license agreement
and delivered with the software product for licensee's internal, non-commercial use. The documentation may not be printed for
resale or redistribution.
Warranties and Liabilities

All warranties given by Intergraph Corporation about equipment or software are set forth in the EULA provided with the software
or applicable license for the software product signed by Intergraph Corporation, and nothing stated in, or implied by, this
document or its contents shall be considered or deemed a modification or amendment of such warranties. Intergraph believes
the information in this publication is accurate as of its publication date.
The information and the software discussed in this document are subject to change without notice and are subject to applicable
technical product descriptions. Intergraph Corporation is not responsible for any error that may appear in this document.
The software discussed in this document is furnished under a license and may be used or copied only in accordance with the
terms of this license. No responsibility is assumed by Intergraph for the use or reliability of software on equipment that is not
supplied by Intergraph or its affiliated companies. THE USER OF THE SOFTWARE IS EXPECTED TO MAKE THE FINAL
EVALUATION AS TO THE USEFULNESS OF THE SOFTWARE IN HIS OWN ENVIRONMENT.
Intergraph is not responsible for the accuracy of delivered data including, but not limited to, catalog, reference and symbol data.
Users should verify for themselves that the data is accurate and suitable for their project work.
Trademarks
Intergraph, the Intergraph logo, PDS, SmartPlant, FrameWorks, I-Convert, I-Export, I-Sketch, SmartMarine, IntelliShip, INtools,
ISOGEN, MARIAN, SmartSketch, SPOOLGEN, SupportManager, and SupportModeler are trademarks or registered trademarks
of Intergraph Corporation or its subsidiaries in the United States and other countries. Microsoft and Windows are registered
trademarks of Microsoft Corporation. Oracle, JD Edwards, PeopleSoft, and Retek are registered trademarks of Oracle
Corporation and/or its affiliates. MicroStation is a registered trademark of Bentley Systems Inc, all rights reserved. Other brands
and product names are trademarks of their respective owners.
Contents
What's New in Batch Services............................................................................................................... 9
Batch Services Overview..................................................................................................................... 11
Getting Started ..................................................................................................................................... 13
Accessing Other Nodes ................................................................................................................... 13
Account Mapping Overview ............................................................................................................. 14
Batch Client API Set ........................................................................................................................ 14
Batch Service Privileges .................................................................................................................. 14
Batch Service Security ..................................................................................................................... 15
Batch User Interfaces ...................................................................................................................... 15
File Staging ..................................................................................................................................... 15
File Staging Example................................................................................................................. 16
Named Jobs .................................................................................................................................... 17
Naming Restrictions......................................................................................................................... 18
Working with Batch Services .............................................................................................................. 19
Working with Queues....................................................................................................................... 21
Connecting to a Queue.............................................................................................................. 21
Creating a Queue ...................................................................................................................... 21
Deleting a Queue ...................................................................................................................... 22
Displaying Queue Status ........................................................................................................... 22
Enabling/Disabling a Queue ...................................................................................................... 23
Handling Queue Security ........................................................................................................... 24
Modifying Queue Parameters .................................................................................................... 25
Starting/Stopping a Queue......................................................................................................... 26
Stopping all Running Jobs ......................................................................................................... 27
Working with Batch Queues ............................................................................................................. 27
Adding and Deleting Batch Queue Shell Lists ............................................................................ 27
Setting the Default Shell ............................................................................................................ 28
Working with Pipe Queues ............................................................................................................... 29
Adding and Deleting Pipe Queue Destinations ........................................................................... 29
Setting the Default Queue ......................................................................................................... 30
Working with Batch Jobs.................................................................................................................. 31
Deleting a Batch Job ................................................................................................................. 31
Deleting/Aborting all Jobs in a Queue ........................................................................................ 32
File Staging: Staging Files In ..................................................................................................... 32
File Staging: Staging Files Out................................................................................................... 33
Getting job status information .................................................................................................... 33
Handling Batch Job Output Files................................................................................................ 34
Modifying a Batch Job after Submission .................................................................................... 36
Moving a Batch Job ................................................................................................................... 37
Pausing/Holding a Batch Job ..................................................................................................... 37
Releasing a Batch Job............................................................................................................... 38
Restarting a Batch Job .............................................................................................................. 38
Saving and Restoring Named Batch Jobs .................................................................................. 39
Submitting a Batch Job.............................................................................................................. 40
Batch Services User's Guide
Contents
Using Recurring Jobs ................................................................................................................ 40
Working with Batch Servers ............................................................................................................. 41
Accessing a Remote Server ...................................................................................................... 42
Configuring the Batch Server ..................................................................................................... 42
Granting Jobs Access to the Desktop ........................................................................................ 43
Removing the Batch Service ...................................................................................................... 43
Setting Batch Server Logging Level (Debug Level) .................................................................... 44
Setting Server Managers and Operators .................................................................................... 44
Configuring SMTP Mail .............................................................................................................. 45
Shutting Down the Batch Server ................................................................................................ 47
Starting the Batch Server ........................................................................................................... 47
Using a Default Mail Address..................................................................................................... 47
Working with Account Mapping ........................................................................................................ 48
Mapping to Other Computers..................................................................................................... 48
Working with Batch Manager Display ............................................................................................... 49
Displaying Batch Manager Help ................................................................................................. 49
Managing the Batch Manager Display........................................................................................ 50
Batch Manager Interface...................................................................................................................... 51
Overview ......................................................................................................................................... 51
Batch Manager Interface .................................................................................................................. 52
Toolbar ...................................................................................................................................... 52
Job Menu .................................................................................................................................. 52
Queue Menu ............................................................................................................................. 52
Server Menu.............................................................................................................................. 52
View Menu ................................................................................................................................ 52
Help Menu................................................................................................................................. 53
Server View ............................................................................................................................... 53
Queue View............................................................................................................................... 53
Status Bar ................................................................................................................................. 54
Input Methods.................................................................................................................................. 54
Job Menu ........................................................................................................................................ 55
Exit command (Job Menu) ......................................................................................................... 55
Properties command (Job Menu) ............................................................................................... 55
Delete command (Job Menu)..................................................................................................... 59
Operator Hold and Release commands (Job Menu)................................................................... 59
User Hold and Release commands (Job Menu) ......................................................................... 60
Run Now (Job Menu)................................................................................................................. 60
Move command (Job Menu) ...................................................................................................... 60
Submit command (Job Menu) .................................................................................................... 60
Queue Menu.................................................................................................................................... 64
Connect to command (Queue Menu) ......................................................................................... 65
Create command (Queue Menu) ............................................................................................... 65
Delete command (Queue Menu) ................................................................................................ 68
Properties command (Queue Menu) .......................................................................................... 68
Start command (Queue Menu)................................................................................................... 71
Stop command (Queue Menu) ................................................................................................... 71
Enable command (Queue Menu) ............................................................................................... 71
Disable command (Queue Menu) .............................................................................................. 71
Abort command (Queue Menu).................................................................................................. 72
Purge command (Queue Menu)................................................................................................. 72
Server Menu .................................................................................................................................... 72
Connect To Command (Server Menu) ....................................................................................... 72
Contents
Account Mapping Command (Server Menu) .............................................................................. 73
Properties Command (Server Menu) ......................................................................................... 74
View Menu....................................................................................................................................... 75
Toolbar command (View Menu) ................................................................................................. 75
Status Bar command (View Menu)............................................................................................. 75
Refresh command (View Menu)................................................................................................. 76
Help Menu ....................................................................................................................................... 76
Contents command (Help Menu) ............................................................................................... 76
Context Sensitive Help Button ................................................................................................... 76
Using Help command (Help Menu) ............................................................................................ 76
About Batch command (Help Menu) .......................................................................................... 76
Script Browser ................................................................................................................................. 76
Script Examples............................................................................................................................... 77
Batch Client API ................................................................................................................................... 79
API Description ................................................................................................................................ 79
Batch Client API interface ................................................................................................................ 80
Batch API Structures ....................................................................................................................... 81
BATCH_QUEUE_INFO_1 ......................................................................................................... 81
BATCH_QUEUE_INFO_2 ......................................................................................................... 82
BATCH_JOB_INFO_1 ............................................................................................................... 85
BATCH_JOB_INFO_2 ............................................................................................................... 86
BATCH_RECURRENCE_INFO ................................................................................................. 90
BATCH_SERVER_INFO ........................................................................................................... 92
Batch API Function Calls ................................................................................................................. 93
BatchAbortJob........................................................................................................................... 94
BatchAbortQueue ...................................................................................................................... 95
BatchCreateQueue.................................................................................................................... 96
BatchDeleteJob ......................................................................................................................... 98
BatchDeleteQueue .................................................................................................................... 99
Example Program ...................................................................................................................... 99
BatchDisableQueue................................................................................................................. 100
BatchEnableQueue ................................................................................................................. 101
BatchEnumerateJobs .............................................................................................................. 102
BatchEnumerateQueues ......................................................................................................... 103
BatchGetJobInfo...................................................................................................................... 104
BatchGetQueueInfo ................................................................................................................. 105
BatchGetServerInfo ................................................................................................................. 107
BatchJobHold .......................................................................................................................... 108
BatchJobRelease .................................................................................................................... 109
BatchMoveJob ........................................................................................................................ 110
BatchPurgeQueue ................................................................................................................... 112
BatchServerShutdown ............................................................................................................. 113
BatchSetJobInfo ...................................................................................................................... 114
BatchSetQueueInfo ................................................................................................................. 116
BatchSetServerInfo ................................................................................................................. 119
BatchStartQueue..................................................................................................................... 121
BatchStopQueue ..................................................................................................................... 122
QueueBatchJob....................................................................................................................... 123
API Error Codes ............................................................................................................................ 127
Batch Specific Error Conditions ............................................................................................... 127
Win32 Error Codes .................................................................................................................. 129
Required Calling Privileges ...................................................................................................... 129
Contents
Command Line Interface ................................................................................................................... 131
Name Syntax ................................................................................................................................. 131
Queue ..................................................................................................................................... 131
Dest-name .............................................................................................................................. 132
Group ...................................................................................................................................... 132
Server ..................................................................................................................................... 132
User ........................................................................................................................................ 132
Shell-name .............................................................................................................................. 132
Runlimit ................................................................................................................................... 133
Job-id ...................................................................................................................................... 133
Priority-value ........................................................................................................................... 133
Nice-value ............................................................................................................................... 133
Debug Level ............................................................................................................................ 133
Shell-path ................................................................................................................................ 134
date-time parameter ................................................................................................................ 134
Submitting Jobs ............................................................................................................................. 135
qsub: An Overview .................................................................................................................. 135
qsub Interface ......................................................................................................................... 135
Deleting or Aborting Batch Jobs ..................................................................................................... 138
qdel: An Overview ................................................................................................................... 138
qdel Interface .......................................................................................................................... 138
Obtaining Job and Queue Status ................................................................................................... 139
qstat: An Overview .................................................................................................................. 139
qstat Interface ......................................................................................................................... 139
Managing Batch Services .............................................................................................................. 140
qmgr: An Overview .................................................................................................................. 140
qmgr Interface ......................................................................................................................... 140
setpasswd.exe Utility ......................................................................................................................... 151
Troubleshooting................................................................................................................................. 153
Customer Support.......................................................................................................................... 153
Telephone Support .................................................................................................................. 154
Web Site ................................................................................................................................. 154
Intergraph Directory ................................................................................................................. 154
Basics of Batch Services ............................................................................................................... 154
Understanding batch queues and pipe queues ........................................................................ 154
Understanding queue states and job states ............................................................................. 154
Job Status Notification ................................................................................................................... 155
Receiving mail notification ....................................................................................................... 155
Obtaining information about failures ......................................................................................... 155
File Staging ................................................................................................................................... 155
Sending and Receiving Files ................................................................................................... 155
Security ......................................................................................................................................... 156
Submitting jobs to remote nodes.............................................................................................. 156
Resource Usage ............................................................................................................................ 156
Controlling queue usage .......................................................................................................... 156
Aborting running jobs............................................................................................................... 156
Frequently Asked Questions .......................................................................................................... 157
Setting up a shell ..................................................................................................................... 157
Power failures ......................................................................................................................... 157
SMTP mail .............................................................................................................................. 157
Contents
Glossary ............................................................................................................................................. 159
Index ................................................................................................................................................... 165
Contents
What's New in Batch Services

Version 6.1
Batch Services has a new Installshield based setup. For more information, see Installing
Intergraph Batch Services in the Batch Services Quick Start Guide.
Version 6.0
Starting from Batch Services Version 06.00.00.08, the user password length is 32
characters.
You must install Version 06.00.00.08 or later on ALL computers prior to changing
or setting a user password. If you attempt to set the password remotely from a computer
running an earlier version of Batch Services, you will corrupt your registry. If this happens,
you will have to remove and reset all your Batch Services passwords on all computers.
Intergraph Batch Services now supports long file names, spaces in folder paths, and
Internationalization. (P1 PB:87374)
If you plan to use Intergraph Batch Services with Plant Design System (PDS), do not
install Intergraph Batch Services to a folder path that contains spaces, such as c:\Program
Files\Batch. While Intergraph Batch Services does support spaces in folder paths, PDS
does not.
After a job has been submitted and before its execution starts, you can modify recurring job
frequency controls. For more information, see Job Properties Dialog Box (on page 55). (P1
PB:113275)
A new Jobs > Run Now command is available to immediately run recurring scheduled jobs.
For more information, see Run Now (Job Menu) (on page 60). (P1 PB:95620)
Answers to several common questions regarding SMTP email have been added to the
Troubleshooting section. For more information, see SMTP Mail (on page 157). (P4
PB:114128)
What's New in Batch Services
10
SECTION 1
Batch Services Overview

Intergraph Batch Services for Windows is a system service that provides tools for the
management and execution of non-interactive tasks. The batch system is fully networked, and
provides connectivity to other batch servers.
The batch system is useful to both system administrators and users. Delayed execution of tasks
allows maintenance- and compute-intensive tasks, such as backups or compilation of large
programs, to be scheduled for times when the system is not in use. The batch system also
allows several client computers to use a multiprocessor server as a "compute engine" for CPU
intensive tasks. A large task can be spread out among several systems available on the
network.
The Batch Server service requires System Account privileges on the system. Use the
Services icon in the Control Panel to configure the Batch Server service.
The complete batch system consists of several pieces, including a batch Server, pipe and batch
queues, and an API set, as shown in the following diagram:
11
Batch Services Overview
12
SECTION 2
Getting Started
After the batch system is installed and running, you should create a batch queue on the local
system using the instructions provided in this help document. After the queue is created,
configured, enabled and started, batch jobs can be submitted using either the Batch Manager
Interface (on page 51) or the qsub (see "qsub: An Overview" on page 135) command line utility.
In order to perform work with the batch system, the user (or application) submits a Batch Job.
Users can also specify how often the job should be run, the environment of the job, its priority,
starting time, description, where the output should be placed, auxiliary files, and many other job
attributes. When a job is successfully submitted, it is assigned a unique job-id. The job-id can be
used to reference the job. No two jobs will have the same job-id.
In This Section
Accessing Other Nodes .............................................................. 13
Account Mapping Overview......................................................... 14
Batch Client API Set ................................................................... 14
Batch Service Privileges ............................................................. 14
Batch Service Security ................................................................ 15
Batch User Interfaces ................................................................. 15
File Staging ................................................................................ 15
Named Jobs ............................................................................... 17
Naming Restrictions .................................................................... 18
Accessing Other Nodes

Remote Windows batch server computers may be accessed directly by using the appropriate
syntax, provided that the user has appropriate privileges on the remote computer. Any user can
perform any non-privileged operation on a remote batch server computer. Jobs may be
submitted directly to remote Windows queues, or by using a pipe queue with a remote
destination.
Access to remote batch servers is determined by the mapping of accounts on the remote server.
Not all operations are supported to remote servers. You may not submit jobs directly to a remote
server; you must use a pipe queue to transfer the job to a batch server.
13
Getting Started
Account Mapping Overview

Account mapping information is entered and modified using Batch Manager (see "Overview" on
page 51). An account mapping entry comprises two parts: the user information to match (the
"from" user), and whom that user maps to (the "to" user).
Batch Services requires an account name and password to use when running jobs. The process
of determining the account name to use is called "account mapping". To perform account
mapping, the server tries to match the job owner with an account mapping entry using the
following order:
1. The server first tries to find an exact match, matching the job owner's domain or computer
name and user name with the "from" user in the account mapping entries.
2. If the server cannot find an exact match, the server then searches the account mapping
entries using the job owner's domain or computer name, with "*" (meaning any user) as the
user name.
3. If no match is found, the server then searches the account mapping entries using "*"
(meaning any domain or computer) as the domain name, with the job owner's user name.
4. Finally, if a match still hasn't been found, a search is done using "*" as the domain name
and "*" as the user name.
For more information, see Mapping to Other Computers (on page 48).
Batch Client API Set

For applications, the batch system provides a full Batch Client API (on page 79) set, which
allows a program to submit, control and manage batch jobs. A header file and link-libraries are
included for building applications. Dynamic-Link Libraries (DLL's) are supplied for the API set to
reduce the size of application programs and allow smooth upgrading.
Batch Service Privileges

Every batch system user has a privilege level. The batch system recognizes the following
privilege classes:
Non-privileged Users -- Can submit requests to queues for which the user has been granted
access. Unprivileged users cannot effect queue control, or change the batch system
configuration. Most users should be in this category.
Operators -- Can access commands that directly affect queue management (such as starting
and stopping queues and deleting requests). Operators cannot change the batch system
configuration (by creating or deleting a queue, and so forth).
Managers -- Have all available batch service privileges. Only managers can assign manager
and operator privileges, create queues, or set default parameters. By default, the Administrators
group is included in the manager list, and may not be removed.
Assigning and Removing Privileges

Only a user with manager privileges or a user who is a member of the Administrators group can
use qmgr or Batch Manager to assign privileges to other batch system users.
14
Getting Started
Batch Service Security

The batch server provides Windows-compatible security, which can be configured by the system
administrator. Control of jobs, queues and configuration of the batch server is restricted to a
specific list of operators and managers. Access to queues may be restricted to a specific set of
users and groups.
Batch User Interfaces

Two user interfaces into the batch system are provided:
An intuitive, easy to use Batch Manager Interface (on page 51) program supplies a graphical
user interface (GUI) for doing interactive tasks with the batch server.
A set of command line utilities is provided for use with scripts, or less interactive tasks.
These utilities provide the following capabilities:
submitting jobs (qsub: An Overview (on page 135))

obtaining job status (qstat: An Overview (on page 139))
deleting jobs (qdel: An Overview (on page 138))
managing jobs and queues (qmgr: An Overview (on page 140))
File Staging
File staging is the movement of files to or from the execution computer before and after the job
runs. There are two types of staging: staging in, and staging out.
Staging in means copying a file before a batch job is run to the system where the job will
execute.
Staging out means copying a file after a batch job is run from the system on which the job
executed.
If a destination filename is not specified, the source filename and the destination filename are
assumed to be the same. Incomplete pathnames for local source filenames are expanded using
the current working directory (if submitted from a Windows client). Pathnames for Windows must
be specified with backslashes (\).
File Staging Example (on page 16)
15
Getting Started
File Staging Example

The following shows examples of file staging.
Inbound Staging
The first entry batch1.ppt=\\remote\c:\pviews\demo1.ppt is an example of a file, demo1.ppt,
being sent from the directory c:\pviews on remote computer \\remote and sent to the execution
computer. batch1.ppt will be the name of the file on the execution computer.
In the second entry pptview.exe=\\local\c:\powerpnt\pptview.exe, the file pptview.exe is being
moved from the computer \\local to the directory where the batch job will execute.
16
Getting Started
Outbound Staging
In the first entry in the Stage Out Files listbox, \\local\c:\logs\finish.log=finish.log, the file
finish.log will be moved to the directory c:\logs on the execution computer, \\local, after the batch
job has been processed.
In the second entry, \\remote\c:\logs\finish.log=finish.log, the file finish.log will be moved to the
directory c:\logs on computer \\remote after the batch job has been processed.
In the third entry, c:\mylogs\finish.log=finish.log, the file finish.log will be moved to directory
c:\mylogs on the local computer after the batch job has been processed. This example shows
another method of staging local files after processing.
Named Jobs
Named jobs are batch jobs that have been saved to a file. They have a default extension of
NJOB (for "named job"). For example, the job myjob will be saved as MYJOB.NJOB.
See Saving and restoring named batch jobs (on page 39) for more information on named jobs.
Method 1: Using the Job Submit dialog

Select Job > Submit, or click Submit Job
on the toolbar. You can save new jobs or recall
previously saved jobs using the Job Submit (on page 60) dialog in Batch Manager. Job Submit
provides command buttons to allow access to named jobs:
Open -- Opens a specified named job. This command displays a dialog that allows you to
browse for named jobs. By default, only files with the .NJOB extension are shown. You can also
display all files in the current directory. Select the named job to load the stored information about
the job into the Job Submit dialog box.
Save/ Save As -- Saves all job information that has been entered in the Job Submit dialog box.
If you try to save a named job to an existing file, Batch Manager prompts you before proceeding.
You can choose a different filename, or replace information in the existing file with information
currently displayed on the Job Submit dialog box.
Method 2: Using the Named Job File

Select the named job file (.NJOB extension), drag it into the Batch Manager window, and drop it.
The Job Submit (on page 60) dialog displays with information specified for the named job.
You can also start Batch Manager from the command line with the name of a named job
file by keying in batchmgr myjob.NJOB, where myjob is the name of the job file, or
double-clicking on the job file in Windows Explorer. Note that you cannot use this method if
Batch Manager is already running.
17
Getting Started
Naming Restrictions
A set of valid characters has been chosen for queue names and shell names. The character set
consists of all alphanumeric (both upper and lower case) and punctuation characters, with the
following exceptions:
1. The punctuation characters @ \ ( ) = and , are invalid. These characters already have
special meaning for the qmgr interface.
2. The punctuation characters - and / are invalid for the first character of a queue or shell
name. In most cases, the command line utilities expect these characters to signal the start
of an option.
18
SECTION 3
Working with Batch Services

This section provides a task-oriented framework for accessing help information. Each task
provides links to help on using the command line, the Batch Manager interface, and the Batch
Services API Interface.
Using batch services, you can perform the following tasks. Tasks are grouped according to
function.
Queues
Connecting to a queue (on page 21)
Creating a queue (on page 21)
Deleting a queue (on page 22)
Displaying queue status (on page 22)
Enabling/Disabling a queue (on page 23)
Handling queue security (on page 24)
Modifying queue parameters (on page 25)
Starting/Stopping a queue (on page 26)
Stopping all running jobs (on page 27)
Batch Queues
Adding and deleting batch queue shell lists (on page 27)
Setting the default shell (on page 28)
Pipe Queues
Adding and deleting pipe queue destinations (on page 29)
Setting the default queue (on page 30)
Batch Jobs
Deleting a batch job (on page 31)
Deleting/aborting all jobs in a queue (on page 32)
File staging: staging files in (on page 32)
File staging: staging files out (on page 33)
Getting job status information (on page 33)
Handling batch job output files (on page 34)
Modifying a batch job after submission (on page 36)
Moving a batch job (on page 37)
Pausing/holding a batch job (on page 37)
Releasing a batch job (on page 38)
Restarting a batch job (on page 38)
Saving and restoring named batch jobs (on page 39)
19

Submitting a batch job (on page 40)
Using recurring jobs (on page 40)
Batch Servers
Accessing a remote server (on page 42)
Configuring the batch server (on page 42)
Granting jobs access to the desktop (on page 43)
Removing the batch service (on page 43)
Setting batch server logging level (debug level) (on page 44)
Setting server managers and operators (on page 44)
Configuring SMTP mail (on page 45)
Shutting down the batch server (on page 47)
Starting the batch server (on page 47)
Using a default mail address (on page 47)
Account Mapping
If you do not understand how accounts are mapped, refer to Account Mapping Overview
(on page 14) before using the mapping procedures. For more information, you will also need to
review Mapping to Other Computers (on page 48).
Batch Manager Display

Displaying Batch Manager help (on page 49)
Managing the Batch Manager display (on page 50)
In This Section
Working with Queues .................................................................. 21
Working with Batch Queues ........................................................ 27
Working with Pipe Queues .......................................................... 29
Working with Batch Jobs ............................................................. 31
Working with Batch Servers ........................................................ 41
Working with Account Mapping ................................................... 48
Working with Batch Manager Display .......................................... 49
20
Working with Queues

Topics
Connecting to a Queue................................................................ 21
Creating a Queue ........................................................................ 21
Deleting a Queue ........................................................................ 22
Displaying Queue Status ............................................................. 22
Enabling/Disabling a Queue ........................................................ 23
Handling Queue Security............................................................. 24
Modifying Queue Parameters ...................................................... 25
Starting/Stopping a Queue .......................................................... 26
Stopping all Running Jobs ........................................................... 27
Connecting to a Queue
Connecting to a queue allows you to view all the jobs within a queue. Before you can display or
modify a remote queue in the Batch Manager user interface, you must connect to it. No
privileges are required to connect to a queue.
To connect to a queue:
1. Select Queue > Connect to.
The Connect to Queue (on page 65) dialog box displays.
2. Key in the queue (on page 131) to which you want to connect. You may also select from a
drop-down list of the most recently selected queues.
3. Click OK.
You can also connect to a queue by double-clicking on it from within a server view (on
page 53).
Creating a Queue
Only users with manager privileges on the server where the queue is being created are allowed
to create queues.
Using Batch Manager:

1. Select Queue > Create or click Create Queue
on the toolbar.
The Create Queue (on page 65) dialog box displays.
2. Key in a name for the queue.
3. Select the type of queue from the Queue Type toggle box.
4. Complete information on the Create Queue dialog as appropriate.
5. Click OK.
Using the command line:

1. Start qmgr (see "qmgr: An Overview" on page 140).
2. Use the Create pipe_queue (on page 142) command to create a pipe queue. Use the
Create batch_queue (on page 142) command to create a batch queue.
21

Using the Batch API:
Use the BatchCreateQueue (on page 96) function.
Deleting a Queue
A batch or pipe queue cannot be deleted if the queue is started or if there are jobs in the queue.
Only users with manager privileges on the server where the queue is located are allowed to
remove queues.

1. Select the queue to be deleted.
2. Stop the queue Queue > Stop, or by clicking Queue Stop
3. Abort all running jobs in the queue using Queue > Abort.
4. Delete any jobs in the queue using Queue > Purge.
on the toolbar.
5. Disable the queue using Queue > Disable, or by clicking Disable Queue
toolbar.
6. Delete the queue using Queue > Delete, or by click Delete Queue
on the
on the toolbar.
Batch Manager requests confirmation before deleting any queues.

1.
2.
3.
4.
5.
6.
Start qmgr.
Stop the queue using the stop queue (on page 149) command.
Abort all running jobs in the queue using the abort queue (on page 141) command.
Delete all jobs in the queue using the purge queue (on page 145) command.
Disable the queue using the disable queue (on page 144) command.
Delete the queue using the delete queue (on page 143) command.

1. Stop the queue using the BatchStopQueue (on page 122) function.
2. Abort all running jobs using the BatchAbortQueue (on page 95) function.
3. Use the BatchPurgeQueue (on page 112) function to delete any jobs remaining in the
queue.
4. Disable the queue using the BatchDisableQueue (on page 100) function.
5. Delete the queue using the BatchDeleteQueue (on page 99) function.
Displaying Queue Status

A queue has two types of status: inflow and outflow, corresponding to the two states of the
queue. The inflow state is either enabled or disabled. An enabled queue will accept new jobs
that are submitted or transferred to it; a disabled queue will not. The outflow state is either
stopped, started, or stopping. A stopped queue will not run the jobs it contains. A queue must be
started in order to run jobs.
An "enabled/stopped queue" is a queue that will accept jobs but not run them.
Displaying a queue's status requires no special privileges.
22

1. Select Server > Connect to.
2. Key in the server (on page 132) name. You can also select a server from the dropdown list,
which contains recently-selected servers.
3. Click OK.
Batch Manager displays the server in a server view (on page 53).
A way to display status for a specific queue is to select Queue > Connect to.

1. Use the qstat command.
OR
Start qmgr, and proceed to step 2.
2. Use the show queue (on page 149) or show long queue (on page 148) commands to display
information about a specific queue. If no queue name is given, this command displays all
queues on the local server.

Use the BatchGetQueueInfo (on page 105) function.
Enabling/Disabling a Queue
These commands control the inflow state of the queue. The inflow state is either enabled or
disabled. An enabled queue will accept new jobs that are submitted or transferred to it; a
disabled queue will not.
You must have at least operator privileges on the server where the queue resides in order to
enable or disable a queue.

1. Select the queue from the Server view (on page 53).
2. Select Queue > Enable or Queue > Disable to control whether or not jobs may be
submitted to the selected queue. You can also click Enable Queue
or Disable Queue
on the toolbar.

1. Start qmgr.
2. Use the enable queue (on page 144) command to enable the queue. Use the disable queue
(on page 144) command to disable the queue.

Use the BatchDisableQueue (on page 100) function to disable a queue. Use the
BatchEnableQueue (on page 101) function to enable a queue.
23
Handling Queue Security

Queue security is managed through the restricting and granting of access to the queue. To have
access to a queue means that the user is able to submit jobs to it. By default, access to a queue
is unrestricted when it is created; both local and remote users are able to submit jobs to it. You
cannot create restricted queues from the command line.
However, you can create queues with access restrictions using Batch Manager. You can modify
access restrictions using both the command line and Batch Manager.
Manager privileges are required on the server where the queue is located to modify the access
restrictions.
If you are creating a queue using Batch Manager:

1. Select Queue > Create, or click Create Queue
on the toolbar.
2. Select the Security tab on the Create Queue (on page 65) dialog box.
3. Select Restricted Access to restrict the queue to specified users (see "User" on page 132)
and groups (see "Group" on page 132).
4. Add users and groups to the Authorized Users and Groups box.
5. Click OK when the Create Queue dialog is complete.
If you are modifying an existing queue using Batch Manager:

1. Select the queue you want to modify.
2. Select Queue > Properties.
Batch Manager displays the Queue Properties Dialog Box (on page 68).
3. Select the Security tab.
4. Change the access on this dialog as appropriate.
5. Click OK when the Queue Properties dialog is complete.
If you want to restrict access to a queue using the Command Line:

1. Start qmgr.
2. Use the set no access (see "Set no_access" on page 147) command to completely restrict
the queue. Requests already in the queue will be allowed to remain there.
3. Use the add users (on page 142) command to add users to the access list. Use the add
groups (on page 141) command to add groups to the access list.
If you want to remove specific users and groups from the access list, use the delete
users (on page 144) and delete groups (on page 143) commands.
If you want to un-restrict access to a queue using the Command Line:

1. Start qmgr.
2. Use the set unrestricted access (see "Set unrestricted_access" on page 148) command to
allow all users access to the queue.

1. Use the BatchGetQueueInfo (on page 105) function to obtain the current
BATCH_QUEUE_INFO_2 (on page 82) structure.
2. Modify the pSD field.
24

3. Use the BatchSetQueueInfo (on page 116) function to set the new
BATCH_QUEUE_INFO_2 (on page 82) structure.
Modifying Queue Parameters

You can modify the following queue attributes:
1. queue priority
2. default job priority
3. run priority limit
4. run limit
5. size limit
6. description of the queue
7. access list
8. shell list/default shell (batch queue only)
9. destination list (pipe queue only)
You must have manager privileges on the server on which the queue resides to modify the
queue.

1. Select Queue > Properties to display and modify information about an existing queue.
2. Modify queue properties as necessary on the tabs.
3. Click OK.
Using the Command Line:

1. Start qmgr.
2. Use the following commands as appropriate:
add/delete destination
Adds/removes destinations for a pipe queue. For more information,
see Add destination (on page 141) or Delete destination (on page
142).
add/delete groups
Adds/removes groups from the access list for the queue. For more
information, see Add groups (on page 141) or Delete groups (on
page 143).
add/delete shell name
Adds/removes shell names for a batch queue. For more information,

see Add shell-name (see "Add shell_name" on page 142) or Delete
shell-name (see "Delete shell_name" on page 143).
add/delete users
Adds/removes users from the access list for the queue. For more
information, see Add users (see "Delete users" on page 144) or
Delete users (on page 144).
set [no] default batch

request priority
Sets or removes the priority used to schedule jobs that do not specify
a priority at submission. For more information, see Set default batch
request priority (on page 146) or Set no default batch request queue
(on page 147).
set [no] default shell
Sets or removes the default shell, used when jobs submitted to a

batch queue do not specify a shell to use at submission. For more
information, see Set default shell (on page 146) or Set no default
25

shell (on page 147).
set destination
Sets a destination for a pipe queue, discarding all previous

destinations. For more information, see Set destination (on page
146).
set nice_value_limit
Sets the limit for specifying the priority of the job when it is run. For
more information, see Set nice_value_limit (on page 147).
set no access
Removes access to the queue from all users. For more information,
see Set no_access (on page 147).
set per-process permfile

limit
Sets the maximum total file sizes used by a request. This value is not
used under Windows. For more information, see Set per_process
permfile_limit (on page 147).
set priority
Specifies the default scheduling priority of the request. The priority is

used for scheduling the order of job execution within the queue. For
more information, see Set priority (on page 148).
set runlimit
Limits the number of jobs that are allowed to run in the queue
simultaneously. The default runlimit is 1. For more information, see
Set runlimit (on page 148).
set shell name
Removes any shells from the named queue's list and replaces them
with the specified list of shells. For more information, see Set
shell_name (on page 148).
set unrestricted access
Resets the queue to allow all users to access it. For more
information, see Set unrestricted_access (on page 148).

1. Use the BatchGetQueueInfo (on page 105) to obtain the BATCH_QUEUE_INFO_2 (on
page 82) structure for the queue.
2. Edit the BATCH_QUEUE_INFO_2 (on page 82) structure as desired for the queue.
3. Use the BatchSetQueueInfo (on page 116) function with the edited structure to set the new
queue parameters.
Starting/Stopping a Queue
These commands control the outflow state of the queue. The outflow state is either started or
stopped. A stopped queue will not run the jobs it contains. A queue must be started in order to
run jobs.
You must have at least operator privileges on the server where the queue resides in order to
start or stop a queue.

1. Select the queue to from the Server view (on page 53).
2. Select Queue > Start or Queue > Stop, or click Start Queue
toolbar.
or Stop Queue
on the

1. Start qmgr.
26

2. Use the start queue (on page 149) command to enable the queue. Use the stop queue (on
page 149) command to disable the queue.

Use the BatchStartQueue (on page 121) function to start the queue. Use the BatchStopQueue
(on page 122) function to stop the queue.
Stopping all Running Jobs

You must have at least operator privileges to stop all running jobs in a queue.

1. Select the queue from the Server view (on page 53).
2. Select Queue > Abort.
Batch Manager stops any running jobs in the queue.
3. Batch Manager prompts you whether or not you want to attempt to restart jobs. Whether or
not a job is restarted is dependent on whether the "restartable" flag is set for the job.

1. Start qmgr.
2. Key in the abort queue (on page 141) command.
Jobs are not restarted.

Use the BatchAbortQueue (on page 95) function.
Working with Batch Queues

Topics
Adding and Deleting Batch Queue Shell Lists .............................. 27
Setting the Default Shell .............................................................. 28
Adding and Deleting Batch Queue Shell Lists

A batch queue can have a list of shells associated with it. These shells are programs that are
able to run specific types of scripts. For example, CMD.EXE can run *.BAT scripts. Associating
a list of shells with a queue in effect states that the queue can run only scripts that utilize the
shells in the list.
You must have manager privileges to change the shell list for a queue.

1. Batch Manager provides two methods for adding/deleting shell names for a batch queue:
a. If you are creating a new batch queue, select Queue > Create, and then select the
Shells tab.
You must select Batch from the Queue Type box before you can access the
Shells tab.
27

b. If you are modifying an existing batch queue, select Queue > Properties, and then
select the Shells tab from the Queue Properties Dialog Box (on page 68).
2. If you are adding shell names, key the new shell name into the Shell Configuration box.
-ORIf you are removing shell names, select the shell name to be removed from the Shell List
box.
3. Select Add to add the shell name to the Shell List box.
-ORSelect Remove to remove the shell name from the Shell List box.
4. Click OK.

1. Start qmgr.
2. Use the add shell_name (on page 142) command to add the shell name. Use the delete
shell_name (on page 143) command to delete the shell name.
You can also use the set shell_name (on page 148) command to remove any shells from the
named queue's shell list, and replace them with a specified list of shells.

1. Use the BatchGetQueueInfo (on page 105) function to obtain the BATCH_QUEUE_INFO_2
(on page 82) structure.
2. Edit the v.batch.shell_list structure to add or remove the shell.
3. Use the BatchSetQueueInfo (on page 116) function with the BATCH_QUEUE_INFO_2 (on
page 82) structure to set the new shell names.
Setting the Default Shell

You can assign a default shell to each batch queue. The default shell is used in cases where the
user does not specify a shell when submitting a job to the batch queue.
Manager privileges are required to set the default shell for a batch queue.

1. Select the batch queue.
2. Select Queue > Properties.
3. Select the Shells tab.
4. Select a shell from the Shell List box, and click Set Default.
5. Click OK.

1. Start qmgr.
2. Use the set default shell (on page 146) command to set the default queue for the server.

1. Use the BatchGetQueueInfo (on page 105) to obtain the BATCH_QUEUE_INFO_2 (on
page 82) structure for the queue.
28

2. Edit the BATCH_QUEUE_INFO_2.v.batch.defaultshell (see "BATCH_QUEUE_INFO_2" on
page 82) value as desired for the queue.
3. Use the BatchSetQueueInfo (on page 116) function with the edited structure to set the new
default shell.
Working with Pipe Queues

Topics
Adding and Deleting Pipe Queue Destinations ............................. 29
Setting the Default Queue ........................................................... 30
Adding and Deleting Pipe Queue Destinations

Destinations are used with pipe queues. Pipe queues are normally used to create a connection
to a remote batch queue. A pipe queue interprets a batch job request, and pipes it to the first
available queue in its destination list that will accept the request. The destination list may contain
any queue type.
If there are no destinations in a pipe queue's destination list, the pipe queue behaves as
if it is STOPPED, even though the outflow state is STARTED.
You must have manager privileges to change the destination list for a queue.

1. Batch Manager provides two methods for adding/deleting destinations for a pipe queue:
a. If you are creating a new pipe queue, select Queue > Create, and the select the
Destination tab.
You must select Pipe from the Queue Type box before you can access the
Destination tab.
b. If you are modifying an existing pipe queue, select Queue > Properties, and then select
the Destination tab from the Queue Properties Dialog Box (on page 68).
2. If you are adding destinations, key the new destination queue into the Destination edit box.
If you are removing destinations, select the destination to be removed from the List box,
which displays the current list of destination queues.
3. Select Add to add the destination to the List box. Select Remove to remove the destination
from the List box.
4. Click OK.

1. Start qmgr.
2. Use the add destination (on page 141) command to add the destination. Use the delete
destination (on page 142) command to delete the destination.
You can also use the set destination (on page 146) command to set the destination for the
specified pipe queue to the specified destination (or several destinations). All previous
destinations are discarded.
29

1. Use the BatchGetQueueInfo (on page 105) function to obtain the BATCH_QUEUE_INFO_2
(on page 82) structure.
2. Edit the v.pipe.dest_list structure to add or remove the destination.
3. Use the BatchSetQueueInfo (on page 116) function with the BATCH_QUEUE_INFO_2 (on
page 82) structure to set the new destination names.
Setting the Default Queue

The default queue on a server is the queue to which batch jobs are submitted when the user
does not explicitly request a queue. The default queue cannot be a remote queue; it must exist
on the server.
Manager privileges are required to set a default queue.

1. Select the server.
2. Select Server > Properties.
The Server Properties Dialog Box (on page 74) displays.
3. Key a queue name into the Default Queue box, or select a queue from the dropdown list.
4. Click OK.

1. Start qmgr.
2. Use the set default batch_request queue (on page 146) command to set the default queue
for the server.

1. Use the BatchGetServerInfo (on page 107) function to obtain the current
BATCH_SERVER_INFO (on page 92) structure.
2. Modify the BATCH_SERVER_INFO defaultqueue field.
3. Use the BatchSetServerInfo (on page 119) function with the modified
BATCH_SERVER_INFO (on page 92) structure to set the default queue.
30
Working with Batch Jobs

Topics
Deleting a Batch Job ................................................................... 31
Deleting/Aborting all Jobs in a Queue .......................................... 32
File Staging: Staging Files In ....................................................... 32
File Staging: Staging Files Out .................................................... 33
Getting job status information ...................................................... 33
Handling Batch Job Output Files.................................................. 34
Modifying a Batch Job after Submission ...................................... 36
Moving a Batch Job ..................................................................... 37
Pausing/Holding a Batch Job ....................................................... 37
Releasing a Batch Job................................................................. 38
Restarting a Batch Job ................................................................ 38
Saving and Restoring Named Batch Jobs .................................... 39
Submitting a Batch Job................................................................ 40
Using Recurring Jobs .................................................................. 40
Deleting a Batch Job

These commands allow you to delete batch jobs that are not running, or abort running jobs.
Only the job owner or a user with at least operator privileges on the server where the job is
located may delete a batch job.

1. Highlight the job that you want to delete.
2. Select Job > Delete, or click Delete Job
on the toolbar.
3. Batch Manager deletes the currently selected job. If the job is running, Batch Manager
provides the option of restarting the job (the ability to restart the job is dependent on the
restartable flag). If the job is not running, the job deletion is confirmed.

1. Obtain the job-ID using the qstat command.
2. Use the qdel command to delete the job if it is not running. If the job is running, use the -k
option with qdel.

Use the BatchAbortJob (on page 94) function to delete a running job. Use the BatchDeleteJob
(on page 98) function to delete a job that is not running.
31
Deleting/Aborting all Jobs in a Queue

Jobs can be deleted from a queue one at a time, or they can be deleted all at once.
You must have at least operator privileges to delete/abort all jobs in a queue.

1. Select the queue to be deleted.
2. Stop the queue using Queue > Stop, or click Stop Queuet
on the toolbar.
3. Select Queue > Abort to stop all running jobs in the queue.
Batch Manager prompts you whether or not you want to attempt to restart the jobs.
4. Select Queue > Purge to remove any jobs that are neither running in the queue, nor being
transferred to another queue.

1. Start qmgr.
2. Stop the queue using the stop queue (on page 149) command.
3. Stop all running jobs in the queue using the abort queue (on page 141) command. Jobs are
not restarted.
4. Delete jobs in the queue that are neither running nor being transferred to another queue
using the purge queue (on page 145) command.

1. Stop the queue using the BatchStopQueue (on page 122) function.
2. Use the BatchAbortQueue (on page 95) function to stop all running jobs in the queue.
3. Use the BatchPurgeQueue (on page 112) function to delete any jobs in the queue that are
neither running nor being transferred to another queue.
File Staging: Staging Files In

File staging (on page 15) information can only be modified at job submission. Staging files in is
the act of copying files from one location to another before the execution of a batch job begins.
No special privileges are required to perform this task, other than permission to access the
file(s) for staging.

1. During job submission, select the File Staging tab from the Job Submit dialog box.
2. Complete the Inbound Staging fields as appropriate for the job.
3. Submit the job by clicking OK.

Use the qsub command with the -si option.

Complete the BATCH_JOB_INFO_2 (on page 86) in files array before passing the structure to
the QueueBatchJob (on page 123) function.
32
File Staging: Staging Files Out

File staging (on page 15) information can only be modified at job submission. Staging files out is
the act of copying files from one location to another after the execution of a batch job ends.
No special privileges are required to perform this task, other than permission to access the
file(s) for staging.

1. During job submission, select the File Staging tab from the Job Submit dialog box.
2. Complete the Outbound Staging fields as appropriate for the job.
3. Submit the job by clicking OK.

Use the qsub command with the -so option.

Complete the BATCH_JOB_INFO_2 (on page 86) outfiles array before passing the structure to
the QueueBatchJob (on page 123) function.
Getting job status information

No special privileges are required to obtain the status of a job.

1. Connect to the queue in which the job resides.
2. Double-click on the selected job, or select Job > Properties.
Batch Manager displays the Job Properties Dialog Box (on page 55).
3. Use information on the Job Properties tabs to check job status.

1. Start qmgr.
the status of jobs in the specified queue.
You can also use the qstat command to display job status.

Use the BatchGetJobInfo (on page 104) function.
33
Handling Batch Job Output Files

Output from a batch job can take many forms:
1. stderr/stdout
2. Outbound Staging (files generated by the job that you want to copy to other directories or
computers)
3. Notification messages (error and informational messages generated in running the job)
No privileges are required (other than access to the files) to request, generate, or receive batch
job output files. However, information that affects the handling of batch job output can only be
specified at job submission.

1. During job submission, select the Output tab from the Job Submit dialog to specify options
for stderr and stdout.
2. Select the File Staging tab to control outbound file staging.
3. Select the Notification tab to control notification options.
4. Submit the job when the Job Submit dialog is complete by clicking OK.

Flags on the qsub command affect job output as follows:
stdout
stderr
Outbound
Staging
34
-eo
Writes stderr to stdout
-ko
Location
-jy
-N
Name
-o
Location and name
-r
Name
-ro
Spooling options
-eo
-e
Name
-jy
-ke
Location
-N
Name
-r
Name
-re
Spooling options
-so
Specifies file staging list.

Notification
Reoccurrence
-M
Specifies an address or list of addresses other than the

default.
-mu
Specifies a single address.
-me
Send mail at job end.
-mb
Send mail at job beginning.
-ma
Send mail on job abort.
-mn
Send no mail
-O desc
Specifies a reoccurring job. Desc is a descriptor of the

form FffIiiMmmWwwYyy
The descriptor is defined in more detail in the following
table.
The reoccurrence descriptor:

Meaning
Flag (F)
value Hex
Interval (I) value

decimal
Month Interval (M)

value decimal
Week (W) mask Hex
Year (Y) value

decimal
Hourly frequency
01
01 to 99(hours)
00
00 to 7f (day of week mask)
00
Daily frequency
02
01 to 31 (days)
00
00
00
Weekly frequency
04
01 to 05 (week)
00
00
Specific Monthly
frequency
28
00
00 to 12 (month)
00 to 1f (day of month 1 to
31 decimal)
00
Determined Monthly
frequency
48
01 to 05 (ordinal)
00
00 to 7f (days)
00
Specific Yearly
frequency
30
00
00
00 to 1f (day of month 1 to
31 decimal)
00 to 12 (month of
year)
Determined Yearly
frequency
50
01 to 05 (ordinal)
00
00 to 12 (month of
year)
Examples:
qsub -q \\gene\myqueue -O f01i01m00w3ey00
"c:\users\default\myscript.bat<tab>/help"
will cause the script file "myscript.bat" to execute every hour starting at the current time on
Monday through Friday. The "<tab>" represents the tab character, and is used to separate
arguments from the script name.
1. Edit the BATCH_JOB_INFO_2 (on page 86) structure:
Element
Affects
Specifies
stdout
Pathname to stdout.
stderr
stderr
Pathname to stderr.
flags (BATCH_JOB_FLAG_<value>):
stdout
Retain stdout on execution

host.
KEEP_STDERR
35

Element
Affects
Specifies
stderr
Retain stderr on execution

host
NOSPOOL_STDOUT
stdout
Write stdout directly instead of NOSPOOL_STDERR

spooling it.
stderr
Write stderr directly instead of COMBINED_OUTPUT

spooling it.
stderr/stdout
Combine stderr and stdout.
outfiles array
Outbound
Staging
File staging list.
mailaddress
Notification
SMTP mail address or

computer name (for event
logging).
2. Use the QueueBatchJob (on page 123)

function with the edited structure to submit
the job.
Modifying a Batch Job after Submission

Batch jobs can be modified after they are submitted, but before they begin execution. These job
properties can be changed after a job has been submitted: scheduling priority (on page 162), job
name, execution priority (on page 160), and whether or not the job is restartable.
You must either own the job or have at least operator privileges on the server where the job is
currently located in order to modify the job properties.

1. Select the job to be modified.
2. Select Job > Properties.
3. Change the information on the dialogs as needed.
4. Click OK.

1. Start qmgr.
2. Use the modify request (on page 144) command to change the job properties.

1. Use the BatchGetJobInfo (on page 104) function to obtain the BATCH_JOB_INFO_2
structure for the job.
2. Modify the appropriate field.
3. Use the BatchSetJobInfo (on page 114) function to modify job attributes.
36
Moving a Batch Job

A batch job can be moved between queues on the same server.
The user moving the job must have at least operator privileges on the server where the queues
reside.

1. Select the job to be moved.
2. Select Job > Move.
Batch Manager displays the Move Job Dialog Box (on page 60).
3. Key in the queue to which you want the job moved.
4. Click OK to move the job.

1. Start qmgr.
2. Use the move request (on page 145) command to move the job.

Use the BatchMoveJob (on page 110) function.
Pausing/Holding a Batch Job

When a job is being held, the job will remain in the queue until it is deleted or released. It will not
run while the hold is in place. There are two types of holds: user holds and administrative holds.
A User Hold is a hold placed on a job by the user. An Administrative Hold can be placed on a
job after it is submitted to a queue, but before the job has begun execution. Only a user with
operator or manager privileges can do this on the server.

1. Select the job.
2. Select Job > User Hold or Job > Operator Hold, or click Job Hold
on the toolbar.

1. If you are setting a user hold on the job, you must set it at job submission using the qsub
command, or use Batch Manager to set it later.
2. If you are setting an administrative hold, use the hold (on page 144) command from qmgr.

Use the BatchJobHold (on page 108) function.
37
Releasing a Batch Job

run while the hold is in place. A user hold can be released either by the submitting user, or by a
user with at least operator privileges on the server. Only a user with at least operator privileges
can release an Administrative hold.

1. Select the job.
2. Select Job > User Release or Job > Operator Release, or click Release Job
toolbar.
on the

1. Start qmgr.
2. Use the Release (on page 145) command to release the hold. You must have at least
operator privileges to release both administrative and user holds. If you are releasing only
an administrative hold, use the Unhold (on page 149) command.

1. Use the BatchGetJobInfo (on page 104) function to return a BATCH_JOB_INFO_2 (on page
86) structure.
2. Check the BATCH_JOB_INFO_2 (on page 86).hold field for the type of hold.
3. Use the BatchJobRelease (on page 109) function to release the hold.
Restarting a Batch Job

By default, when a batch job is submitted, it is flagged as "restartable." This means that if for
some reason the job does not execute on the first attempt (for example, the queue is aborted),
the job will be resubmitted to the queue and will re-execute.

1. Select the job.
2. Select Job > Properties.
3. Select the General tab. If the Restartable flag is checked, the job is restartable. As long as
the job has not started executing, you may change this value by clicking the Restartable
box.
4. Click OK.

By default, jobs are restartable when submitted, unless you specify the -nr option when qsub is
used to submit the job.

1. Use the BatchGetJobInfo (on page 104) function to obtain the BATCH_JOB_INFO_2 (on
page 86) structure for the job.
38

2. To set the restartable flag, set the BATCH_JOB_INFO_2.restartable value to 1. To turn off
the restartable flag, set the value to 0.
3. Use the BatchSetJobInfo (on page 114) function with the BATCH_JOB_INFO_2 (on page
86) structure to change the restartable value.
Saving and Restoring Named Batch Jobs

A batch job can be saved to a file for later recall, modification, and submission. This is especially
useful if you want to set up certain job parameters to be used again and again.
For example, you might have a certain set of people you want to notify whenever a backup runs.
You could create a named job that contains the name of your backup script, the queue in which
it should run, and the notification list (see "Configuring SMTP Mail" on page 45) and save it as
BACKUP.NJOB. To run a backup job, you would then open the named job using the Job Submit
(on page 60) dialog, make any necessary changes (perhaps the start time of the job), and then
submit the job. Using this method, you do not have to re-enter the job's parameters each time
you want to run the job.
After you have created a named job, you can access it in a variety of ways. Any of the following
methods open the named job and fill in the Job Submit dialog with all of its parameters:
1. Click Open on the Job Submit dialog box, browse for the named job, and click OK.
2. Drag the named job file from Windows Explorer into the Batch Manager window.
3. Enter the command batchmgr named_job.NJOB at the command prompt, where
named_job is the name of the job file.
4. Double-click on the named job file in Windows Explorer.
The last two methods will not work if Batch Manager is already active since only one
Batch Manager session at a time is allowed.
To create a named job:

1. Select Job > Submit.
The Job Submit dialog displays.
2. Enter the job parameters that you want to save as a named job.
3. Click Save As to name and save your job.
To recall and submit a previously saved named job:

The Job Submit dialog displays.
2. Click Open to browse for previously saved named jobs.
3. Choose the named job you want to recall, and click OK.
Batch Manager loads the saved job parameters into the Job Submit dialog and displays the
name of the job in the title of the Job Submit dialog box.
4. You can submit the job exactly as it was stored in the named job file, or you can make
modifications. If you want to save changes you make, click Save to overwrite the existing
named job, or click Save As to choose a new name for the modified job.
5. Click Submit to submit the job.
39
Submitting a Batch Job

A batch job can be submitted using the command line, Batch Manager, or at the API level. As
long as the user is allowed to submit jobs to the queue (either the default queue, or a queue of
the submitter's choosing), the user may submit the job.
Batch Manager Method 1. Using the Submit Command

1. Select Job > Submit, or click Submit Job
on the toolbar.
2. Complete the Job Submit (on page 60) dialog as appropriate.
3. Click OK to submit the job.
Batch Manager Method 2. Submitting a Named Job

Batch Manager provides several methods for accessing and submitting a named job:
Select the named job file (.NJOB extension), drag it into the Batch Manager window, and
drop it. The Submit Job dialog displays with information specified for the named job.
Select Job > Submit, or click Submit Job

. Click Open to browse for the named job.
Start Batch Manager from the command line with the name of a named job file by keying in
batchmgr myjob.NJOB, where myjob is the name of the job file, or double-clicking on the
job file in Windows Explorer. Note that you cannot use this method if Batch Manager is
already running.
You can also drag a script file into the Batch Manager window to display the Job Submit (on
page 60) dialog with the file name field completed. If the script file is dropped into a queue
view, the queue name field will also be completed.
See Saving and Restoring Named Batch Jobs (on page 39) for more information.

Use the qsub command.

Use the QueueBatchJob (on page 123) function.
Using Recurring Jobs

Recurring jobs are batch jobs that are scheduled to run more than once at a regular interval. If
you have a task that recurs on a regular basis, such as a nightly backup, you can schedule it as
a recurring job. You only schedule a recurring job once, and then Batch Services automatically
runs all future occurrences of the job for you.

1. Select Job > Submit, or click Submit Job
on the toolbar.
2. Complete the Job Submit (on page 60) dialog as appropriate. Use the Scheduling tab to
select the interval for your job (hourly, daily, weekly, monthly, or yearly) and to supply
additional scheduling information.
The job will continue to run on its scheduled interval until you delete the job.
40

As an example, we will schedule a system backup to run every Monday and Thursday at 7:00
PM, starting on the first of February 2011. To do this, take the following steps:
1. Open Batch Manager, and select the queue to which you want to submit the recurring job.
3. Browse for and select the backup script that you want to run.
4. Select the Scheduling tab.
5. Select weekly job frequency by choosing the Weekly radio button. When the Weekly radio
button is selected, additional controls, which allow us to indicate more specific information
for weekly recurring jobs, will appear.
6. Select a weekly frequency of every 1 week.
7. Select the Monday and Thursday checkboxes, making sure that no other checkboxes are
selected.
8. Set the effective date to February 1, 2011.
9. Set the start time to 19:00 (7:00 PM). The Next Occurrence field will note that the first
occurrence of the backup job will be run on Monday, February 1, 2011 at 7:00PM.
The job will appear in the selected queue with a status of RECURRING.

You cannot submit recurring jobs via the command line interface.

Use the QueueBatchJob (on page 123) function being sure to complete the flags field and the
recurrence fields with your recurring job information.
Working with Batch Servers

Topics
Accessing a Remote Server ........................................................ 42
Configuring the Batch Server ....................................................... 42
Granting Jobs Access to the Desktop .......................................... 43
Removing the Batch Service........................................................ 43
Setting Batch Server Logging Level (Debug Level) ...................... 44
Setting Server Managers and Operators ...................................... 44
Configuring SMTP Mail................................................................ 45
Shutting Down the Batch Server .................................................. 47
Starting the Batch Server............................................................. 47
Using a Default Mail Address....................................................... 47
41
Accessing a Remote Server

Accessing a server generally means displaying the queues on that server.

1. Choose Server > Connect to.
2. Key in the server name. You can also select a server from the dropdown list, which contains
recently selected servers.
3. Click OK.
Batch Manager displays the server in a server view (on page 53).

1. Start qmgr.
information about a specific queue. If no queue name is given, this command displays all
queues on the server.
You can also use the qstat command to display information about a specific queue. If no
queue name is given, this command displays all queues on the local server.

Use the BatchGetQueueInfo (on page 105), BatchEnumerateQueues (on page 103), and
BatchGetServerInfo (on page 107) functions.
Configuring the Batch Server

Complete the following steps to ensure that the Batch Server service is configured to have
System Account privileges on the system:
The Batch Services product is delivered with the correct configuration. Intergraph
recommends leaving the product as configured.
1. Select Control Panel > Administrative Tools > Services.
2. Select the "Intergraph Batch Server" service.
3. Select Startup.
4. Select Automatic as the Startup Type, and select System Account from the Log On As
box.
5. Click OK. Refer to your Windows system documentation for more information on using the
Control Panel.
42
Granting Jobs Access to the Desktop

If required, batch jobs can have access to the desktop. If jobs are allowed to have access to the
desktop, a window that is iconified and non-active displays on the screen while a job is running.
These windows will only be seen when a user is logged in.
Windows Vista, Windows 7, and Windows 2008 Server do not allow jobs access to the
desktop.
Granting jobs access to the desktop depends on your site's security requirements. If jobs are
granted access to the desktop, a logged in user will be able to interact with batch jobs that are
running, even if the batch job is running as a different user. If security is not a concern, sites
where batch jobs may require some user input should configure Batch Services to allow jobs to
have access to the desktop. Sites where security is a main concern should configure Batch
Services not to allow jobs to have access to the desktop. When you install Batch Services
software, you are given the option of whether or not jobs may have access to the desktop. After
installation, if you want to change the way Batch Services is currently configured, do the
following:
1. Open Control Panel > Administrative Tools > Services.
2. Right-click on Intergraph Batch Server in the list, and then click Properties.
3. Select the Log On tab.
4. The Allow service to interact with desktop checkbox determines whether or not jobs may
access the desktop. If you want jobs to have access to the desktop, make sure the
checkbox is selected. If you do not want jobs to access the desktop, make sure the
checkbox is cleared.
5. Click Apply to reconfigure the startup parameters.
6.
7.
8.
9.
10.
The Intergraph Batch Server service must be stopped and restarted for the change to take
effect.
Select the General tab.
Click Stop.
Click Start to restart Batch Services.
Click OK to close the properties window.
Exit the Services window.
Removing the Batch Service

To remove the batch services:
1. As an administrator, go to the Control Panel and then Add or Remove Programs
(Windows XP and some Windows Server versions) or Programs and Features (Windows
Vista, Windows 7, and some Windows Server versions).
2. Select Intergraph Batch Services.
3. Click Change/Remove or Uninstall depending on your version of Windows.
4. Click Yes.
43
Setting Batch Server Logging Level (Debug Level)

The batch server logs its messages and problems in the Event Log. The amount and detail of
the messages is dependent on the auditing (or debug) level set in the server.
Setting any of the "Debugging" auditing categories causes many events to be logged,
and may fill up the event log.
You must have manager privileges on the server to set the debug level.

Batch Manager displays the Server Properties Dialog Box (on page 74).
3. Select the levels of auditing desired under the Auditing block.
4. Click OK.

1. Start qmgr.
2. Use the set debug (on page 145) command.

1. Use the BatchGetServerInfo (on page 107) function to obtain the BATCH_SERVER_INFO
(on page 92) structure for the server.
2. Edit the BATCH_SERVER_INFO (on page 92) debuglevel.
3. Use the BatchSetServerInfo (on page 119) function with the BATCH_SERVER_INFO
structure to set the new debug level.
To view messages in the Event Log:

1. Start Event Viewer from the Administrative Tools group.
2. Select Application from the Log menu.
Setting Server Managers and Operators

By default, only the Administrators group on a given server has privileges on that server. This
group always has manager privileges. Additional users must be added to the manager or
operator lists.
You can grant users either manager or operator privileges. Users with manager privileges are
able to use all commands that affect server configuration and operation, while users with
operator privileges are able to start or stop queues, and manipulate jobs.
Only users with manager privileges can grant and remove server privileges.

Batch Manager displays the Server Properties dialog box.
3. Select the Security tab.
4. Select Add to grant operator or manager privileges.
44

The Add Managers and Operators dialog box displays.
5. Key in the users or groups you want to add, separated by semi-colons.
6. Select the type of privilege:
Operator - Allows the user or group to manage jobs that it does not own.
Manager - Allows the user or group full privileges in the batch system. By default, only
members of the Administrators group are granted Manager priviledges.
7. Click OK.
Note that the selected privilege applies to all users or groups being added; you cannot add
an operator and a manager at the same time.
You can remove selected users or groups from the authorization list by selecting them and
choosing Remove.

1. Start qmgr.
2. Use the add managers (on page 141) command to grant privileges to the specified users or
groups. You must specify the type of privilege (manager or operator).
3. Use the delete managers (on page 143) command to remove privileges from the specified
users or groups.
You can use the set managers (on page 147) command to remove privileges from all
current managers and operators, and reset them to the specified users or groups.

1. Use the BatchGetServerInfo (on page 107) function to obtain the current
BATCH_SERVER_INFO (on page 92) structure.
2. Modify the pSD field.
3. Use the BatchSetServerInfo (on page 119) function with the modified
BATCH_SERVER_INFO (on page 92) structure to change the operator/manager privileges.
Configuring SMTP Mail

You can configure Batch Services to notify you (or anyone you choose) about the status of your
Batch jobs. SMTP mail is one method Batch Services can use to send job notification
information. To use SMTP mail notification, your mail system must be able to handle SMTP
mail. In some systems a program called an SMTP gateway provides this functionality. The
gateway allows mail to be sent between users running various mail packages. Contact your mail
administrator to see if your installation will support SMTP mail notification.
SMTP mail is the most convenient notification method supported by Batch Services, since it
sends notification directly to you. The other notification method requires you to periodically
check the event log for the information. To use the SMTP mail method, you must configure
Batch Services to recognize the SMTP address to which you want to send notification mail.
There are two methods used to provide this information. The method you choose will depend on
whether or not a direct SMTP address is available for the person to whom you want to send
mail. For example, if your address is "jsmith@mymachine.b101.mycomp.com," you can use the
direct method. If you want to use the address "jsmith@mycomp.com," an alias for the previous
address, you must use the indirect method. Contact your mail administrator to determine which
of these cases describes your mail situation.
45

Microsoft has enhanced security that changed the default behavior of controlled
access to the Outlook automation code. The default is now to Prompt User that causes a dialog
to appear on the server. Using the PDS Batch Mail Utility now displays the dialog prompting the
user to confirm or cancel the email request. You must click Yes on the dialog prompt before the
email will send. No remaining batch jobs will process until the acknowledgement is made.
Direct SMTP Mail Support

If you or the user(s) to which you want to send job notification have a direct SMTP address, no
further configuration is necessary. Batch Services sends mail directly to those addresses.
Indirect SMTP Mail Support

If you or the user(s) to which you want to send job notification do not have a direct SMTP
address, you must give Batch Services the location of your SMTP host (a computer that is
running SMTP). This computer will be used to route the mail to the requested user for you. Ask
your mail administrator for the name of your SMTP host computer and for the address of the
person to whom you want to send job notification mail.
To notify the batch server of the name of your SMTP host, add the following information to the
HKEY_LOCAL_MACHINE\SOFTWARE\Intergraph\Batch Service entry in the system registry:
Value Name:
SMTPhost
Type:
REG_SZ
String:
Any computer running SMTP
Stop and restart the Intergraph Batch Server for this change to take effect. The SMTPhost
computer will send any SMTP mail from the batch service.
Administrator privileges are required to configure the SMTPhost in the system registry.

1. When submitting a job, select the Notification tab from the Job Submit dialog box.
2. Key in the email address in the Address box.
3. Click Add to add the address to the List box.
You can specify more than one email address.
4. Complete the Job Submit dialog as appropriate for the job.
5. Click OK.

Use the qsub -M or -mu options when submitting the job.

Edit the BATCH_JOB_INFO_2 (on page 86) structure and place the mail address(es) in element
mailaddress.
Submit the job with the QueueBatchJob (on page 123) function.
See SMTP Mail (on page 157) in the Troubleshooting section for additional information.
46
Shutting Down the Batch Server

There are four methods for shutting down the batch server.
This command requires manager privileges on the batch server.
Using Program Manager:

1. Start Control Panel > Administrative Tools > Services.
2. Select "Intergraph Batch Server," and click Stop. You must be a member of the
Administrators group to use this method.

1. Start qmgr.
2. Use the shutdown (on page 149) command to shut down the batch server.

Use the BatchServerShutdown (on page 113) function.
Using an Command Prompt window:

If you are a member of the Administrators group, you may also use the following command from
an MS-DOS command prompt window:
net stop "Intergraph Batch Server"
Starting the Batch Server

The batch server can be restarted three ways.
Using Program Manager:

1. Start Control Panel > Administrative Tools > Services.
2. Select "Intergraph Batch Server," and click Start. You must be a member of the
Administrators group to use this method.
If you are a member of the Administrators group, you may also use the following command from
an command prompt window:
net start "Intergraph Batch Server"
The third method is to restart the computer.
Using a Default Mail Address

The mail address receives job notification messages (for example, mail when the job starts,
stops, or aborts). By default, the mail address is the Event Log on the system from which the job
was submitted.
To view the event log:

1. Start Event Viewer from the Administrative Tools group.
2. Select Application from the Log menu.
To view the event log of the system where the job executed, start the event viewer
application, and select "Select Computer" from the "Log" menu. Key in the name of the system
where the job executed.
47

Note that you must select the Refresh option from the View menu to view any new mail.
You can also use the MAIL= environment variable to specify a default mail addresses other than
the default provided by Batch Services. There are two methods for using the MAIL environment
variable:
To use a default mail address for a single job from the command line:
Key in set MAIL=address at the command prompt before submitting the job with the qsub
command, where address is the address you want to use.
To use a default mail address with the Batch Manager GUI, or for all jobs at the command
line:
1.
2.
3.
4.
5.
Select the System icon from the Control Panel.

Key in MAIL in the Variable box.
Key in the address you want to use in the Value box.
Select Set.
Log out and log back in for these changes to take effect.
Working with Account Mapping

Topics
Mapping to Other Computers....................................................... 48
Mapping to Other Computers

Batch Services requires the following information to map accounts for submitting jobs to and
from systems running Batch Services for Windows. The method used to map accounts depends
on the security requirements of your site.
Accounts must be mapped to a Windows user with the "Log on locally" user right.
For Minimum Security:

At sites where security is not a major concern, all jobs can be run as the same user. For
example, if your system name is ROSE, then the following account mapping entry maps all users
to the guest account on ROSE:
*\* = ROSE\Guest
For Increased Security Using Domain Accounts:

If users will be submitting jobs using domain accounts, then you can enter an account mapping
for each user who will be running jobs on this system. For example, if your domain name is
FLOWERS and your user name is Joe, then the following account mapping entry will ensure that
all jobs submitted by FLOWERS\Joe are run as FLOWERS\Joe
FLOWERS\Joe = FLOWERS\Joe
Note that even if FLOWERS\Joe submits a job from a different Windows system to the system
with the account mapping, his job will still be run as FLOWERS\Joe.
48

For Increased Security Using Local Accounts:
If your site does not use domain accounts but you require a higher level of security, use the
following method:
If you are using the same account name and password on several systems, then you should
create an account mapping entry that maps each account name from all computers. For
example, if your account name is "Bob" on all the systems you log into (and your password is
the same on all those systems) and this system is named "ROSE", you should create the
following account mapping entry to map "Bob" from all computers to ROSE\Bob:
*\Bob = ROSE\Bob
If users use different accounts and passwords on different systems, you must use the Minimum
Security method to map accounts.
Working with Batch Manager Display

Topics
Displaying Batch Manager Help ................................................... 49
Managing the Batch Manager Display ......................................... 50
Displaying Batch Manager Help

Use the Help menu (on page 76) to manage Batch Manager help.
To display various components of the help system:

Select Contents to display the introductory page of the help system. You can also select the
Contents button from the help system.
To obtain help on using help:

Select Using Help to display brief instructions for using the help system.
To display the current version of batch services:

Select About Batch to display the current version of Batch Services.
To obtain context-sensitive help:

Select the context-sensitive help button (
), and then click the mouse on a menu item,
button, or view. Batch Manager displays help about the selected item.
49
Managing the Batch Manager Display

Use the Window menu to customize the Batch Manager display by arranging queue and server
views, or switching from one view to another. Use the View menu to toggle display of the toolbar
and status bar.
To select a view:
Selecting a view activates the view. Click anywhere on the view you want to select. The title bar
changes to indicate the view is now active.
To arrange views:
To overlap each view so that the title is visible, choose Cascade from the Window menu.
To overlap and resize each view, choose Tile from the Window menu.
To arrange icons:
When a view is minimized, it displays as an icon. To move icons, you can drag and drop them
with the mouse. To arrange icons automatically, select Arrange Icons from the Window menu.
To close all views:

To close all open views, choose Close All from the Window menu.
To display the toolbar:

The toolbar provides mouse access to commands provided in the Queue and Job menus. To
toggle the display of the toolbar, select Toolbar from the View menu.
To display the status bar:

The status bar displays information about the queue or server view. For the server view, the
status bar displays the server name. For the queue view, the status bar indicates relevant queue
status, including queue name, queue type, queue description, and inflow and outflow states.
To toggle the display of the status bar, select Status Bar from the View menu.
50
SECTION 4
Batch Manager Interface

In This Section
Overview .................................................................................... 51
Batch Manager Interface ............................................................. 52
Input Methods ............................................................................. 54
Job Menu.................................................................................... 55
Queue Menu............................................................................... 64
Server Menu ............................................................................... 72
View Menu .................................................................................. 75
Help Menu .................................................................................. 76
Script Browser ............................................................................ 76
Script Examples .......................................................................... 77
Overview
Batch Manager provides an object-oriented interface for viewing and managing job flow. Batch
Manager allows you to create batch or pipe queues, and to connect to remote queues.
Connection to remote servers allows you to manage other Windows batch servers on the
network.
The Batch Manager interface provides a two objects, or views, for managing batch services:
Server View (on page 53)
Queue View (on page 53)
51

The following diagram shows the Batch Manager interface.
Figure 1: Batch Manager
Toolbar
Provides button access to certain commands available in the Job and Queue menus.
Job Menu
Contains commands for the submission and management of jobs in local and remote queues. In
addition, you can modify job characteristics such as job hold/release. The job menu is active
when a queue within a server view is selected, or a queue view is active. A subset of the
commands in the job menu is also available from the toolbar.
Queue Menu
Provides those operations related to creating, connecting to, deleting, and controlling job inflow
and outflow from batch and pipe queues. A subset of these commands is also available from the
toolbar.
Server Menu
Provides those operations related to connecting to a batch server and modifying properties of a
server. When you connect to a batch server, the queues configured on that computer are
displayed in a separate server window.
View Menu
Toggles the display of the toolbar and status bar, and allows you to manually refresh the active
Queue View or Server View.
52
Help Menu
Allows you to access the Batch Manager online help file that is delivered with the Batch Services
product. You can also obtain help on using Windows help, or display information about the
Batch Manager version.
Server View
The server view displays information about the server. When the server view is active, you can
configure the queues on the server. This includes creating, deleting, and managing the queues
on a Windows server. The server view shows the queues on that server. To connect a server,
click Server > Connect to. To display a queue, double-click on a queue line in a server view.
Batch Manager displays a list of the jobs contained within that queue.
The server view displays the following information:
Server
The name of the server.
Queue
The name of the queue.
Type
The queue type (Batch/Pipe).
Priority
The scheduling priority of the queue.
Inflow
The inflow state of the queue: enabled or disabled.
Outflow
The outflow state of the queue: stopped or started.
Job Count
The number of jobs in the queue.
You can sort the queues based on columns. By default, sorting is based on Queue.
Server Accelerator Keys

The following accelerator keys are available for a server view:
F5
Refreshes the active view.
ENTER
Displays a queue view for the selected queue.
ALT+ENTER
Displays the Queue Properties dialog for the selected queue.
DELETE
Deletes the selected queue, provided the queue can be deleted.
INSERT
Displays the Job Submit dialog, provided the selected queue can
accept jobs.
ALT+INSERT
Displays the Create Queue dialog box.
CTRL+ENTER
Displays the Server Properties dialog box.
Server Status Bar

The server status bar displays the server name.
Queue View
The queue window, or view, displays information about the jobs contained in the specified
queue(s). A queue view represents a batch or pipe queue. The queue view displays the
following information:
53

Server
The name of the server.
Queue
The name of the queue.
Job ID
The identifier of the job.
Status
The job state, such as QUEUED or RUNNING.
Priority
The job scheduling priority.
User
The username of the submitting user.
Job Name
The user-defined name for the job.
Start Time
The start time of a job, or the next occurrence time of a recurring job.
You can sort the jobs based on columns. By default, sorting is based on Start Time.
You can create new queues with the Queue > Create command, or you can connect to remote
existing queues using the Queue > Connect to command. Double clicking on a queue in a
server view also displays a queue view.
After a queue is created or a connection to a remote queue is established, users with manager
privileges may change attributes of the selected queue. The queue window displays any jobs
that are presently in that queue.
Queue Accelerator Keys

The following accelerator keys are available for a queue view:
F5
Refreshes the view.
ALT+INSERT
Displays the Create Queue dialog for the selected server.
CTRL+ENTER
Displays the Server Properties dialog for the selected server.
ENTER
Displays the Job Properties dialog for the selected job.
ALT+ ENTER
Displays the Queue Properties dialog for the selected queue.
DELETE
Deletes the selected job, or the queue if no jobs are selected.
INSERT
Displays the Submit Job dialog, provided the selected queue can
accept jobs.
Queue Status Bar

The queue status bar indicates relevant queue status, including queue name, queue type,
queue description, and inflow and outflow states.
Status Bar
Displays information about the server or queue view. For the server view, the status bar displays
the server name. For the queue view, the status bar indicates relevant queue status, including
queue name, queue type, queue description, and inflow and outflow states.
Input Methods
Batch Manager accepts input from the mouse, keyboard, and menus. Other methods of input
are available, such as mouse-selectable toolbar buttons and keyboard accessible hotkeys (for
54

example, CTRL+F). These methods are useful for users who are more familiar with Batch
Manager, and wish to select actions more quickly and succinctly.
In general, the availability of commands in either menus or the toolbar depends on what is
currently selected or active. If no object in a particular queue or server view is selected,
commands apply to the currently active window.
Job Menu
If a job is selected and you have appropriate privileges, the job menu is active and allows
various operations to be performed on the selected job. Only the owner of the job, an operator,
or a manager may modify job parameters.
Submit - Displays a Job Submit (on page 60) dialog in order to submit a job. The tab has
reasonable defaults so you can minimally select the script name and submit the job.
The queue defaults to the currently selected queue. You can use the Default Queue check box
to select the default queue for the local server.
Delete - Deletes the currently selected job. If the job is running, Batch Manager provides the
option of restarting the job. Job restart is dependent on whether the restartable flag is set in the
job or not. If the job is not running, the job deletion is confirmed.
Properties - Displays the Job Properties Dialog Box (on page 55) dialog allowing viewing and
modification of job information. Job properties cannot be modified once a job has begun
execution.
User Hold / Release Operator Hold / Release - Controls the setting and releasing of the hold
flag on a job. Only operators and managers can set or release operator holds. Job owners can
set and release user holds.
Run Now - Runs the selected job immediately.
Move - Displays the Move Job Dialog Box (on page 60) requesting the queue to which the job
should be moved. Only the job owner, an operator, or a manager may perform this operation.
Exit - Exits Batch Manager.
Exit command (Job Menu)

Exits Batch Manager.
Properties command (Job Menu)

Allows you to view and modify job information. This command displays the Job Properties
Dialog Box (on page 55). Job properties cannot be modified after a job has begun execution.
Job Properties Dialog Box

Shows the various job-related parameters that can be viewed or changed.
The Job Properties dialog box contains tabs that correspond to various categories including
general information, scheduling, notification, output, resources, and file staging. You can display
this dialog box using one of the following methods:
Use the Job > Properties command.
Double-click a job line.
Job properties cannot be modified after the execution of a job has begun. After a job has been
submitted and before its execution starts, only Scheduling Priority, Job Name, Execution
55

Priority, Restartable, and recurring job frequency (Minutes, Hourly, Daily, Weekly, Monthly,
or Yearly) controls can be modified.
Topics
Job Properties: General .............................................................. 56
Job Properties: Scheduling ......................................................... 56
Job Properties: Notification ......................................................... 57
Job Properties: Resources .......................................................... 57
Job Properties: File Staging ........................................................ 58
Job Properties: Advanced ........................................................... 59
Job Properties: Output ................................................................ 59
Job Properties: General

Displays the following basic information about the job.
Job ID - Shows the ID of the job.
Owner - Specifies the user who has submitted the job.
State - Shows the status of the job.
Queue - Specifies the queue to which the job is submitted.
Job Name - Specifies a user-defined name for the job.
Script File - Specifies the shell script submitted for execution.
Account Name - Specifies a user-defined string describing the account.
Size - Shows the size of the shell file.
Shell - Displays the currently selected shell for the job. A blank value indicates the default shell
for the queue. This value can be set only at job submission.
Restartable - Controls whether the job is restarted after a system crash, system shutdown, or
batch service shutdown while the job is running.
Job Properties: Scheduling

Describes the various parameters associated with scheduling the job for execution.
Job Occurs - Sets the execution frequency of a job. Jobs can be scheduled to run once or at
regular intervals. If you choose to run jobs at regular intervals, additional recurring job frequency
controls (Minutes, Hourly, Daily, Weekly, Monthly, or Yearly) appear to the right of this field.
These controls allow you to enter more specific scheduling information. The scheduling controls
can be changed at job submission, and the recurring jobs frequency controls can be modified for
recurring jobs already submitted.
Time Ranges / Range Times - Sets a period of time within a day for the recurring job to run.
This option is available only with Minute(s) and Hourly settings. The Range Times controls are
shown after you click Time Ranges. For example, if you want to schedule an hourly recurring
job to run from 15:30 to 22:00, specify 15 Hours, 30 Minutes for the From field and 22 Hours,
00 Minutes for the To field.
Start Date - Specifies the date when a one-time job should be run or when the execution series
of a recurring job should begin. This setting can be changed at any time before the end date.
End After - Specifies how many times the job is run before its execution series ends
No End Date - Sets the recurring job to run indefinitely.
End By - Specifies an end date for the execution series of the job.
56

Start Time - Specifies the time the job is allowed to start. These fields can be changed at job
submission and at any time before the end date for submitted recurring jobs.
Current Time - Uses the submission time of the job as its start time. This field can be changed
at job submission and at any time before the end date for submitted recurring jobs.
Next Occurrence - Shows the date and time of the next occurrence of the recurring job. This
read-only field appears only for recurring jobs (on page 162). It is calculated by Batch Services.
Job Properties: Notification

Describes the notification preferences for the job. Notification preferences can be set only at job
submission.
Job Start / Job Completion / Job Abort - Specifies the notification option. You can be notified
for the following events:
The job begins execution (Job Start).
The job completes execution (Job Completion).
The job is aborted (Job Abort).
By default, Job Abort is selected.
Output File / Error File - Sets whether output files and error files are included with the
notification.
Address - Lists mail addresses in the form \\host (event log notification) or user@host (see
Configuring SMTP Mail (on page 45)). Mail will be sent to each recipient. To add an address to
the list, type in the mail address and click Add. You can specify more than one recipient by
typing in addresses separately, and clicking Add after each address. By default, job notification
messages are placed in the event log of the batch server where the job is run.
Address Book - Opens the address book for you to select mail addresses.
Add - Adds the specified recipient to the list box.
Move Up - Moves the selected recipient up in the list of mail addresses.
Remove - Removes the highlighted recipient from the list of mail addresses.
Remove All - Removes all existing recipients from the list of mail addresses.
Job Properties: Resources

Configures the various job resources needed for the batch job.
Execution Priority - Sets the run time priority. The default run time priority is set by the queue.
This value cannot be greater than the execution priority for the queue.
Environment - Enters and updates environment variables. These values can be specified only
at job submission.
Variable - Specifies the environment variable name.
Value - Specifies the environment variable value.
Set - Adds the selected environment variable name to the batch environment of the job.
Remove - Deletes the selected environment variable from the batch environment of the job.
Remove All - Deletes all environment variables from the batch environment of the job.
Add Current Environment Variables - Adds all environment variables in the current
environment to the name list. This option is available only at job submission.
57

Job Properties: File Staging
Describes how required files for the job are handled. See file staging (on page 15) for more
information about handling job input/output files.
Inbound Staging - Indicates the specifications for copying source files before the job is
executed.
Destination Name - Specifies a pathname on the execution computer. If this value is specified
without a complete pathname, the working directory of the job on the execution computer is
used to expand the pathname.
Source Name - Specifies the file to copy from. This value can be a remote file. Incomplete
pathnames for local source file names are expanded using the current working directory.
Stage In Files - Lists the inbound destination name/source name specifications for the job.
Outbound Staging - Indicates the specifications for moving source files after the job is
executed.
Destination Name - Specifies the remote destination file name (the file to copy to). This value
can be a remote file. Incomplete pathnames for local destination file names are expanded using
the current working directory.
Source Name - Specifies the pathname on the execution computer. Incomplete pathnames are
expanded using the working directory of the job on the execution computer.
Stage Out Files - Lists the outbound destination name/source name specifications for the job.
Add File - Adds staging information. This option is available only at job submission.
Remove - Removes the specified staging specification from the Stage Out Files or Stage In
Files list. This option is available only at job submission.
Remove All - Removes all staging information from the Stage Out Files or Stage In Files list.
This option is available only at job submission.
58

Job Properties: Advanced
Sets advanced parameters for the job.
Holds - Indicates whether a user hold or an operator hold applies to the job. This field can be
changed only from the Job menu or through the corresponding commands on the tool bar. You
must be the job owner to set a user hold.
Scheduling Priority - Specifies the relative priority of this job with other jobs. The available
range is -1024 to 1023.
Default Priority - Uses the default job priority of the queue to schedule the job.
Job Properties: Output

Specifies how the output is handled for the job. This information can be changed only at job
submission.
Output Pathname - Specifies a path and file name indicating where the standard output files
are stored. For local files, type in the complete pathname. You can specify a network pathname
using the \\host\pathname\filename format.
Error Pathname - Specifies a path and file name indicating where the standard error files are
stored. For local files, type in the complete pathname. You can specify a network pathname
Keep Output on Execution Host - Specifies whether the output is kept on the execution host.
No Spooling - Specifies whether output is to be created directly in the specified pathname,
rather than spooling (on page 163) the output and waiting until the job is completed. Spooling is
not supported on remote computers.
Join Output in One File - Disables the Standard Error group box and sends all output to the
standard output.
Delete command (Job Menu)

Deletes the currently selected job. If the job is running, Batch Manager provides the option of
restarting the job. If the job is not running, the job deletion is confirmed.
Operator Hold and Release commands (Job Menu)

Controls the setting and releasing of the hold flag on a job. These commands toggle between
the operator hold and release options. Only operators or managers can set or release operator
holds.
59
User Hold and Release commands (Job Menu)

Controls the setting and releasing of the hold flag on a job. These commands toggle between
the user hold and release options. Only job owners can set user holds. Job owners, operators,
and managers can release user holds.
Run Now (Job Menu)

Runs the selected job immediately even though the job may be scheduled to run at a different
time. Use this command when a scheduled job did not run at the scheduled time for some
reason (such as a power failure) or to test if a newly created recurring schedule job is working
correctly.
Only jobs on the local batch server can be run immediately. You must log-in to the remote batch
server to immediately run jobs queued on that computer.
Move command (Job Menu)

Moves a job from one queue to another, as long as the queue resides on the same server. This
command displays the Move Job Dialog Box (on page 60) requesting the queue to which the job
should be moved. Only the job owner, an operator, or a manager may perform this operation.
Move Job Dialog Box

The Move Job dialog specifies the job to be moved and the queue into which the job should be
moved. The default job to be moved is the one currently selected when Move is selected.
Current Queue - Displays the name of the queue to which the job currently belongs.
Job ID - Specifies the job to be moved.
To Queue - Provides a dropdown list box with the allowable queues to which the job can be
moved. Jobs can only be moved to a queue on the server where the job exists.
Submit command (Job Menu)

Submits a job. This command displays a Job Submit (on page 60) dialog box. The tab has
reasonable defaults so you can minimally select the script name and submit the job. The queue
defaults to the currently selected queue (or the default queue for the selected server if this field
is blank). You may also use the Default Queue check box.
Job Submit
The Job Submit dialog is similar to the Job Properties dialog box but provides the following
commands:
OK - Submits the job.
Cancel - Cancels the job submission.
Apply - Causes any changes made to values on the tabs to take effects immediately.
Named Jobs Commands

The following commands apply to named jobs (on page 17).
Open - Opens a specified named job.
Save - Saves all job information that has been entered in the Job Submit dialog to a named job.
60

Save As - Saves a job to a specified filename.
Topics
Job Submit: General ................................................................... 61
Job Submit: Scheduling .............................................................. 61
Job Submit: Notification .............................................................. 62
Job Submit: Resources ............................................................... 62
Job Submit: File Staging ............................................................. 63
Job Submit: Advanced ................................................................ 63
Job Submit: Output ..................................................................... 63
Job Submit: General

Describes the following basic information about the job:
Owner - Specifies the user submitting the job. This value is set to the current user.
Script - Specifies the shell script to submit for execution. Click Browse to search the computer
or the network for an executable. For more information, see Script Browser (on page 76). The
name of the script should not contain any characters that have special meaning to the shell
associated with the queue.
Arguments - Specifies arguments for the script to be submitted.
Queue Name - Specifies the queue to which the job is submitted.
Default Queue - Uses the default queue of the selected server. The Queue Name field will be
filled with the name of the default queue.
Job Name - Specifies a user-defined name for the job.
Account Name - Specifies a user-defined alphanumeric string describing the account.
Shell - Displays the currently selected shell for the job. A blank value indicates the default shell
for the queue. This value can be set only at job submission.
Restartable - Controls whether the job is restarted after a system crash, system shutdown, or
batch service shutdown while the job is running. By default, this option is selected.
Job Submit: Scheduling

Describes the various parameters associated with scheduling the job for execution.
Job Occurs - Sets the execution frequency of a job. Jobs can be scheduled to run once or at
regular intervals. If you choose to run jobs at regular intervals, additional recurring job frequency
controls (Minutes, Hourly, Daily, Weekly, Monthly, or Yearly) appear to the right of this field.
These controls allow you to enter more specific scheduling information. The scheduling controls
can be changed at job submission, and the recurring jobs frequency controls can be modified for
recurring jobs already submitted.
Time Ranges / Range Times - Sets a period of time within a day for the recurring job to run.
This option is available only with Minute(s) and Hourly settings. The Range Times controls are
shown after you click Time Ranges. For example, if you want to schedule an hourly recurring
job to run from 15:30 to 22:00, specify 15 Hours, 30 Minutes for the From field and 22 Hours,
00 Minutes for the To field.
Start Date - Specifies the date when a one-time job should be run or when the execution series
of a recurring job should begin. This setting can be changed at any time before the end date.
End After - Specifies how many times the job is run before its execution series ends
No End Date - Sets the recurring job to run indefinitely.
End By - Specifies an end date for the execution series of the job.
61

Start Time - Specifies the time the job is allowed to start. These fields can be changed at job
submission and at any time before the end date for submitted recurring jobs.
Current Time - Uses the submission time of the job as its start time. This field can be changed
at job submission and at any time before the end date for submitted recurring jobs.
Next Occurrence - Shows the date and time of the next occurrence of the recurring job. This
read-only field appears only for recurring jobs (on page 162). It is calculated by Batch Services.
Job Submit: Notification

Describes the notification preferences for the job. Notification preferences can be set only at job
submission.
Job Start / Job Completion / Job Abort - Specifies the notification option. You can be notified
for the following events:
The job begins execution (Job Start).
The job completes execution (Job Completion).
The job is aborted (Job Abort).
By default, Job Abort is selected.
Output File / Error File - Sets whether output files and error files are included with the
notification.
Address - Lists mail addresses in the form \\host (event log notification) or user@host (see
Configuring SMTP Mail (on page 45)). Mail will be sent to each recipient. To add an address to
the list, type in the mail address and click Add. You can specify more than one recipient by
typing in addresses separately, and clicking Add after each address. By default, job notification
messages are placed in the event log of the batch server where the job is run.
Address Book - Opens the address book for you to select mail addresses.
Add - Adds the specified recipient to the list box.
Move Up - Moves the selected recipient up in the list of mail addresses.
Remove - Removes the highlighted recipient from the list of mail addresses.
Remove All - Removes all existing recipients from the list of mail addresses.
Job Submit: Resources

Configures the various job resources needed for the batch job.
Execution Priority - Sets the run time priority. The default run time priority is set by the queue.
This value cannot be greater than the execution priority for the queue.
Environment - Enters and updates environment variables. These values can be specified only
at job submission.
Variable - Specifies the environment variable name.
Value - Specifies the environment variable value.
Set - Adds the selected environment variable name to the batch environment of the job.
Remove - Deletes the selected environment variable from the batch environment of the job.
Remove All - Deletes all environment variables from the batch environment of the job.
Add Current Environment Variables - Adds all environment variables in the current
environment to the name list. This option is available only at job submission.
62

Job Submit: File Staging
Describes how required files for the job are handled. See file staging (on page 15) for more
information about handling job input/output files.
Inbound Staging - Indicates the specifications for copying source files before the job is
executed.
Destination Name - Specifies a pathname on the execution computer. If this value is specified
without a complete pathname, the working directory of the job on the execution computer is
used to expand the pathname.
Source Name - Specifies the file to copy from. This value can be a remote file. Incomplete
pathnames for local source file names are expanded using the current working directory.
Stage In Files - Lists the inbound destination name/source name specifications for the job.
Outbound Staging - Indicates the specifications for moving source files after the job is
executed.
Destination Name - Specifies the remote destination file name (the file to copy to). This value
can be a remote file. Incomplete pathnames for local destination file names are expanded using
the current working directory.
Source Name - Specifies the pathname on the execution computer. Incomplete pathnames are
expanded using the working directory of the job on the execution computer.
Stage Out Files - Lists the outbound destination name/source name specifications for the job.
Add File - Adds staging information. This option is available only at job submission.
Remove - Removes the specified staging specification from the Stage Out Files or Stage In
Files list. This option is available only at job submission.
Remove All - Removes all staging information from the Stage Out Files or Stage In Files list.
This option is available only at job submission.
Job Submit: Advanced

Sets advanced parameters for the job.
Holds - Indicates whether a user hold or an operator hold applies to the job. This field can be
changed only from the Job menu or through the corresponding commands on the tool bar. You
must be the job owner to set a user hold.
Scheduling Priority - Specifies the relative priority of this job with other jobs. The available
range is -1024 to 1023.
Default Priority - Uses the default job priority of the queue to schedule the job.
Job Submit: Output

Specifies how the output is handled for the job. This information can be changed only at job
submission.
Output Pathname - Specifies a path and file name indicating where the standard output files
are stored. For local files, type in the complete pathname. You can specify a network pathname
Error Pathname - Specifies a path and file name indicating where the standard error files are
stored. For local files, type in the complete pathname. You can specify a network pathname
Keep Output on Execution Host - Specifies whether the output is kept on the execution host.
63

No Spooling - Specifies whether output is to be created directly in the specified pathname,
rather than spooling (on page 163) the output and waiting until the job is completed. Spooling is
not supported on remote computers.
Join Output in One File - Disables the Standard Error group box and sends all output to the
standard output.
Queue Menu
This menu allows you to connect to, create, delete, and change parameters of selected queues.
Connect to - Connects to a queue. Selecting this entry displays the Connect to Queue (on page
65) dialog box, allowing you to specify a queue. You may also select from a drop-down list of the
most recently selected queues.
Create - Creates batch and pipe queues. Selecting this entry displays the Create Queue (on
page 65) dialog box. Manager privileges are required to create queues.
Delete - Deletes the currently selected queue. Batch Manager requests confirmation before
deleting any queues. A batch or pipe queue cannot be deleted if the queue is started or if there
are jobs in the queue. Manager privileges are required to remove queues.
Properties - Displays information about or modifies an existing queue. Batch Manager displays
the Queue Properties Dialog Box (on page 68), allowing you to modify various queue
parameters. Manager privileges are required to modify queue parameters.
Enable - Enables a queue. This command controls whether jobs may be submitted to the
selected queue. This command is also available from the toolbar. The state of the selected
queue controls whether or not this command is selectable. Operator or manager privileges are
required to use this command.
Disable - Disables a queue. This command is also available from the toolbar. The state of the
selected queue controls whether or not this command is selectable. Operator or manager
privileges are required to use this command.
Start - Starts a queue. This command is also available from the toolbar. The state of the
Stop - Stops a queue. This command is also available from the toolbar. The state of the
Abort - Stops any running jobs in the queue. Batch Manager prompts you whether or not you
want to attempt to restart the job. Whether or not a job is restarted is dependent on whether the
"restartable" flag is set for the job.
Purge - Removes any jobs in the queue that are neither running nor being transferred to
another queue. Operator or manager privileges are required to use this command.
64
Connect to command (Queue Menu)

Creates a connection to a queue. Batch Manager displays a Connect to Queue (on page 65)
dialog, requiring you to specify a queue name.
Operations on this queue are only allowed if you have the required privilege on the remote
computer.
Connect to Queue
Select Connect to from the Queue menu to create a connection to a remote queue. Operations
on the selected queue (on page 131) are only allowed if you have the required privilege on that
computer. You can key in a remote queue by using the syntax \\server\queuename, or you can
select a queue that you have recently connected to from the drop down list.
Press ENTER or select OK to complete the dialog box. Select Cancel or press ESC to dismiss
the dialog without making a connection.
Create command (Queue Menu)

Creates a new batch or pipe queue. Batch Manager displays the Create Queue (on page 65)
dialog box. The default queue type is a batch queue. The queue you create is in the Disabled
inflow and Stopped outflow states. Only users with manager privileges are allowed to create
queues.
Create Queue
Select Queue > Create to create a new batch or pipe queue. Batch Manager displays a dialog
that allows you to configure various aspects of the queue.
The Create Queue dialog displays a Queue Type box that displays the type of the
queue, either Batch or Pipe. The two are mutually exclusive. If a batch queue is being created,
the Destinations tab is unavailable for selection. If a pipe queue is being created, the Shells
tab is unavailable for selection.
Tabs
General - Specifies general information about the queue. For more information, see Create
Queue: General (on page 66).
Scheduling - Configures how jobs are scheduled within the queue. For more information, see
Create Queue: Scheduling (on page 66).
Job Defaults - Specifies job defaults. For more information, see Create Queue: Job Defaults
(on page 67).
Security - Configures queue security parameters. For more information, see Create Queue:
Security (on page 67).
Shells - Configures the shells for batch queues. This tab is only available for batch queues. For
more information, see Create Queue: Shells (on page 67).
Destinations - Specifies the destination list for pipe queues. This tab is only available for pipe
queues. For more information, see Create Queue: Destinations (on page 68).
The following defaults are set when a queue is created:
Queue Parameter
Default Setting
Queue Type:
Batch
65

Inflow state:
Disabled
Outflow:
Stopped
Queue Priority:
32
Run Limit:
1 (Intergraph PDS does not support a run limit

greater than 1.)
Scheduling Priority:
31 (This is the default job priority)
Execution Priority:
Normal
Create Queue: General

The General tab provides information of general interest about the queue:
Queue Name - Specifies the name of the queue (on page 131). You must specify a queue
name to display any other tabs.
Description - Allows you to specify a description for the queue.
Disable Job Inflow While Running Job - When selected, the queue will not accept a new job if
another job is currently running in the queue. Therefore, if a pipe queue is configured to send to
any of several different queues, the queue that is not busy will accept the job, enabling the job to
run immediately.
Job Inflow - Displays the inflow state of the queue. The inflow state is either enabled or
disabled queue will not. You can change the inflow state using the Enable or Disable
commands on the Queue Menu (on page 64), or the appropriate toolbar buttons. The inflow
status for a newly created queue is Disabled.
Job Outflow - Displays the outflow state of the queue. The outflow state is stopped, started, or
stopping. A stopped queue will not run the jobs it contains. A queue must be started in order to
run jobs. You can change the outflow state using the Start or Stop commands on the Queue
menu, or the appropriate toolbar buttons. The outflow status for a newly created queue is
Stopped.
Create Queue: Scheduling

The Scheduling tab provides information on how jobs are scheduled within the queue.
Run Limit - Limits the number of jobs that can be in the running (or transferring) state
simultaneously. The default run limit for newly created queues is 1. The allowable range of run
limits is 1-60.
Intergraph Plant Design System (PDS) does not support a run limit greater than 1.
Multiprocessor Scheduling - On a multi-processor system, this option specifies the set of
processors on which the job is to be run. This can be overridden by the batch job itself. This
value has no effect on a single-processor system. If no processor is selected, then all
processors are used.
66

Create Queue: Job Defaults
The Job Defaults tab lists the defaults for a job when no preference is made for the listed
parameters.
Scheduling Priority - Sets the default scheduling priority of a job. The default priority specifies
what the job priority is set to if no priority is specified at submission. The default scheduling
priority for newly created queues is 31. The allowable range is -1024-1023.
Execution Priority - Limits the execution priority of jobs submitted to the selected queue. You
can select Idle, Normal, High, or Realtime execution priority. The default execution priority for
newly created queues is Normal.
A Realtime process preempts all other processes, including the operating system.
Intergraph recommends that you avoid using the Realtime priority.
Create Queue: Security

The Security tab defines the access to the selected queue to allow the submission or viewing of
jobs. The ability to submit a job includes the ability to view jobs.
Queue Access - Specifies whether or not access to the queue is restricted. If the queue is
restricted, you must specify the users and groups authorized to access the queue. If you switch
the queue access from restricted to unrestricted after specifying authorized users or groups, you
will be warned that this action will also delete the list of authorized users and groups.
Authorized Groups and Users - Lists those users and groups authorized to access a restricted
queue. This list is only valid if the Queue Access box is set to Restricted.
Add - Allows you to authorize users and groups to access a restricted queue using the Add
Users and Groups Dialog Box (on page 74).
Remove - Removes the selected user or group from the access list.
Remove All - Removes all users and groups from the access list.
Create Queue: Shells

The Shells tab configures the shells for the batch queue. This tab is only available if you select
Batch in the Queue Type box.
Shell Configuration - Configures shells to be added. This section contains the following
options:
Name - The short name of the shell.
Location - The associated path to the location of the shell.
Shell List - Lists the currently configured shells and paths. Selecting shells from this list places
the name and location in the Shell Configuration section. This list also allows you to set a
default shell.
Add - Adds the shell that is currently displayed in the Shell Configuration section to the shell
list.
Remove - Removes a shell from the list. The shell must be selected from the Shell List or listed
in the Shell Configuration section.
Remove All - Removes all shells in the shell list.
Set Default - Sets the currently selected shell as the default shell for the queue. The selected
value displays in the Default Shell field.
Clear Default - Clears the current default shell setting.
Default Shell - Lists the current default shell.
67

Create Queue: Destinations
The Destinations tab describes the list of destination queues to use for pipe queues.
Destination queues are used in the order they are listed. This tab is only available when you
select Pipe in the Queue Type box.
Destination - Adds a new destination to the pipe queue. Key the new destination into the
Destination edit box.
List - Displays the current list of destination queues. Destinations selected from this list display
in the Destination box.
Add - Adds the destination to the destination list.
Move Up - Moves the selected destination one line higher in the destination list.
Remove - Removes the destination from the destination list. Select the destination to be
removed in the List box, and then click Remove.
Remove all - Removes all existing destinations from the destination list.
Delete command (Queue Menu)

Deletes the currently selected queue. Confirmation of deletion is requested. A batch or pipe
queue cannot be deleted if the queue is enabled, started or has jobs in the queue. Only users
with manager privileges are allowed to remove batch and pipe queues.
Properties command (Queue Menu)

Displays the Queue Properties Dialog Box (on page 68) dialog, allowing you to modify how a
particular queue is configured. Tabs are provided for configuring queues. You must be a
manager to modify parameters.
Queue Properties Dialog Box

The Queue Properties dialog box provides information on how a particular queue is configured.
Queue properties are divided into several configured areas, with a corresponding tab available
for each area. Select Queue > Properties to display the Queue Properties dialog box.
The Queue Properties dialog contains a Queue Type indicator that displays the type of
the queue, either Batch or Pipe. The two queue types are mutually exclusive. If a batch queue
is being displayed, the Destinations tab is unavailable for selection. If a pipe queue is being
displayed, the Shells tab is unavailable for selection.
Topics
Queue Properties: General ......................................................... 69
Queue Properties: Scheduling .................................................... 69
Queue Properties: Job Defaults .................................................. 69
Queue Properties: Security ......................................................... 70
Queue Properties: Shells ............................................................ 70
Queue Properties: Destinations................................................... 71
68

Queue Properties: General
The General tab provides information of general interest about the queue:
Queue Name - Displays the name of the queue. This field cannot be modified after the queue is
created.
Description - Specifies a description for the queue.
Disable Job Inflow while Running Job - When selected, the queue will not accept a new job if
another job is currently running in the queue. Therefore, if a pipe queue is configured to send to
any of several different queues, the queue that is not busy will accept the job, enabling the job to
run immediately.
Job Inflow - Displays the inflow state of the queue. The inflow state is either enabled or
disabled queue will not. You can change the inflow state using the Enable or Disable
commands on the Queue Menu (on page 64), or the appropriate toolbar buttons.
Job Outflow - Displays the outflow state of the queue. The outflow state is stopped, started, or
stopping. A stopped queue will not run the jobs it contains. A queue must be started in order to
run jobs. You can change the outflow state using the Start or Stop commands on the Queue
menu, or the appropriate toolbar buttons.
Queue Properties: Scheduling

The Scheduling tab provides information on how jobs are scheduled within the queue.
Run Limit - Limits the number of jobs that can be in the running (or transferring) state
simultaneously. The allowable range of run limits is 1-60.
Intergraph Plant Design System (PDS) does not support a run limit greater than 1.
Multiprocessor Scheduling - On a multi-processor system, this option specifies the set of
processors on which the queue is to reside. This can be overridden by the batch job itself. This
value has no effect on a single-processor system. If no processor is selected, then all
processors are used.
Queue Properties: Job Defaults

The Job Defaults tab lists the defaults for a job when no preference is made for the listed
parameters.
Scheduling Priority - Specifies what the job scheduling priority is set to if no priority is specified
at submission. The allowable priority range is -1024 to 1023.
Execution Priority - Limits the execution priority of jobs submitted to the selected queue. You
can select Idle, Normal, High, or Realtime execution priority. The default execution priority for
newly created queues is Normal.
A Realtime process preempts all other processes, including the operating system.
Intergraph recommends that you avoid using the Realtime priority.
69

Queue Properties: Security
The Security tab defines the access to the selected queue to allow the submission of jobs.
Queue Access - Specifies whether or not access to the queue is restricted. If the queue is
restricted, you must specify the users and groups authorized to access the queue. If you switch
the queue access from restricted to unrestricted after specifying authorized users or groups, you
will be warned that this action will also delete the list of authorized users and groups.
Authorized Groups and Users - Lists those users and groups authorized to access a restricted
queue. This list is only valid if the Queue Access box is set to Restricted.
Add - Allows you to authorize users and groups to access a restricted queue. This button
displays the Add Users and Groups Dialog Box (on page 74).
Remove - Removes the selected user or group from the access list.
Remove All - Removes all users and groups from the access list.
Queue Properties: Shells

The Shells tab configures the shells for the batch queue. This dialog provides the following
options:
Shell Configuration - Configures shells to be added. This section contains the following
options:
Name - The short name of the shell.
Location - The associated path to the location of the shell.
Shell List - Lists the currently configured shells and paths. Selecting shells from this list places
the name and location in the Shell Configuration section. This list also allows you to set a
default shell.
Add - Adds the shell that is currently displayed in the Shell Configuration section to the shell
list.
Remove - Removes a shell from the list. The shell must be selected from the Shell List or listed
in the Shell Configuration section.
Remove All - Removes all shells in the shell list.
Set Default - Sets the currently selected shell as the default shell for the queue. The selected
value displays in the Default Shell box.
Clear Default - Clears the current default shell setting, and sets the default shell value to none.
Default Shell - Lists the current default shell.
Click OK to accept the selected settings. Click Cancel to return to the Queue View without
changing the shell settings.
70

Queue Properties: Destinations
The Destinations tab describes the list of destination queues to use for pipe queues. Note that
destination queues are used in the order they are listed.
Destination - Adds a new destination to the pipe queue. Key the new destination into the
Destination edit box.
List - Displays the current list of destination queues. Destinations selected from this list display
in the Destination box.
Add - Adds the destination to the destination list.
Move Up - Moves the selected destination one line higher in the destination list.
Remove - Removes the currently selected destination from the destination list.
Remove all - Removes all destinations currently in the list box.
Start command (Queue Menu)

Controls the outflow state of the queue. The outflow state is either stopped, started, or stopping.
A stopped queue will not run the jobs it contains. A queue must be started in order to run jobs.
This menu entry is available only if the selected queue is in the stopped state. Batch Manager
also provides a toolbar button for starting the queue. This command requires operator or
manager privileges.
Stop command (Queue Menu)

Controls the outflow state of the queue. The outflow state is either stopped, started, or stopping.
A stopped queue will not run the jobs it contains. This menu entry is only available if the
selected queue is in the started state. Batch Manager also provides a toolbar button for stopping
the queue. This command requires operator or manager privileges.
Enable command (Queue Menu)

Controls the inflow state of the queue. The inflow state is either enabled or disabled. An enabled
queue will accept new jobs that are submitted or transferred to it. This menu entry is available
only if the selected queue is currently in the disabled state. Batch Manager also provides a
toolbar button for enabling the queue. This command requires operator or manager privileges.
Disable command (Queue Menu)

Controls the inflow state of the queue. The inflow state is either enabled or disabled. A disabled
queue will not accept new jobs that are submitted or transferred to it. This menu entry is enabled
only if the selected queue is currently in the enabled state. Batch Manager also provides toolbar
buttons for enabling or disabling the queue. This command requires operator or manager
privileges.
71
Abort command (Queue Menu)

Aborts any running jobs in the queue. A secondary dialog confirms whether or not jobs should
attempt to be restarted after the abort. Whether or not a job is restarted is dependent on whether
the restartable flag is set for the job. This command requires operator or manager privileges.
Purge command (Queue Menu)

Removes any jobs that are not running in the selected queue, or being transferred to another
queue. This command requires operator or manager privileges.
Server Menu
The Server menu provides the following options:
Connect to - Provides access to a remote batch server for management of those resources.
This command displays the Connect to Server Dialog (on page 72), which requires you to
specify the name of a remote Windows host.
Operations on the selected remote server are only allowed if you have privileges on the remote
computer to do so.
Properties - Displays information about the server in the form of tabs that display general
information and allow you to specify security information. This command displays the Server
Properties Dialog Box (on page 74), which contains the following tabs:
General - Displays information about the server, including the server name and the default
batch queue.
Security - Allows you to specify security information for the selected server.
Account Mapping - Displays the Account Mapping Dialog (on page 73) dialog box, which
specifies information about the account name and password to use when running jobs.
When a server is selected, the status bar displays the server name.
Connect To Command (Server Menu)

Provides access to a batch server for management of those resources. This command displays
the Connect to Server Dialog (on page 72), which requires you to specify the name of a host.
Connect to Server Dialog

The Connect to Server dialog box allows you to specify information for connecting to a batch
server. Select Connect to from the Server menu. Specify the following information:
Server - Type the name of the host to which you want to connect. You may also select the host
from a drop-down list of the most recently selected computers.
Click OK (or press ENTER) to connect to the specified host. Click Cancel (or press ESC) to
cancel the request and dismiss the dialog box.
72
Account Mapping Command (Server Menu)

The Account Mapping dialog box specifies information about the account name and password
to use when running jobs.
Account Mapping Dialog

The Account Mapping dialog box specifies information about the account name and password
to use when running jobs.
An account mapping entry comprises two parts: the user information to map (the Map From
Account field), and the account to whom that user maps (the Map To Account information).
Account mapping entries are displayed in the Mapped Accounts list box in the order that the
server will search for them. To perform account mapping, the server tries to match the job owner
with an account mapping entry using the following order:
1. The server first tries to find an exact match, matching the job owner's domain or computer
name and user name with the "from" user in the account mapping entries.
2. If the server cannot find an exact match, the server then searches the account mapping
entries using the job owner's domain or computer name, with "*" (meaning any user) as the
user name.
3. If no match is found, the server then searches the account mapping entries using "*"
(meaning any domain or computer) as the domain name, with the job owner's user name.
4. Finally, if a match still has not been found, a search is done using "*" as the domain name
and "*" as the user name.
Batch Services has account mapping for Mapping to Other Computers (on page 48).
The first time you select the Add, Remove, Remove All or Set Password buttons, Batch
Manager displays a warning that the selected action will take place immediately. Batch Manager
prompts you to confirm before continuing.
The Account Mapping dialog box contains the following fields and commands:
Map From Account - The user information to map.
Map To Account - The account to whom that user maps.
Add - Adds the account mapping entry specified by the Map To Account and Map From
Account information to the Mapped Accounts list box. If this is the first time the Map From
Account has been added, the Enter Password dialog box displays so you can set the
password for the Map From Account user.
Remove - Removes the selected account mapping entry from the Mapped Accounts list box.
Remove All - Removes all the account mapping entries from the Mapped Accounts list box.
Set Password - Displays the Enter Password dialog box, allowing you to set the password for
the user listed in the Map From Account field. You can use this button when the password of
that user has changed or was entered incorrectly. Passwords are limited to 32 characters.
When a password for a user is keyed into the Enter Password dialog boxes, the value of
the Password and Confirm Password fields must match.
73
Add Users and Groups Dialog Box

Key in any users and groups you wish to add to the access list, separated by semi-colons. Click
OK to add the specified users and groups.
Properties Command (Server Menu)

Displays information about the server in the form of tabs that display general information and
allow you to specify security information. This command displays the Server Properties Dialog
Box (on page 74), allowing you to select from the General (information of general interest) and
Security (security parameters) tabs.
Server Properties Dialog Box

The Server Properties dialog box (available from the Properties command on the Server
menu) provides a series of tabs that allow you to change batch server configuration parameters.
The parameters currently being changed are displayed in the tab heading. The Server
Properties dialog box includes two tabs for the following categories:
Server Properties: General Tap (see "Server Properties: General Tab" on page 74)
Server Properties: Security Tab (on page 75)
The tabs each provide an Apply button that you can use to cause any changes made to
values on the tabs to take effect immediately.
Server Properties: General Tab

The General tab displays the following information about the selected server:
Batch Server - Displays the name of the server currently being displayed.
Default Queue - Provides a drop down box specifying the queue to which jobs are submitted if
no queue is specified. The drop down box includes a list of all the queues on the server.
Auditing - Provides a group of check-boxes that specify what events should be audited on the
server:
Server Logging - Provides information about the current state of the server and changes in
its configuration.
Queue Logging - Provides information about the creation and deletion of queues, and
about any changes in queue states or attributes.
Job Logging - Provides information about job submission and job status.
Job Error Logging - Provides information that is useful for understanding why a job is
failing.
Debugging Events - Aid in diagnosing low-level problems with the batch service. This
information may not be useful to users or operators.
Setting debug auditing causes many events to be logged, and may fill up the event
log.
74

Server Properties: Security Tab
The Security tab configures management authorization for the selected batch server. This tab
provides the following options:
Managers and Operators - Lists users and groups with manager or operator privileges on the
server.
Add - Grants operator or manager privileges to a user or group. This button displays the Add
Managers and Operators dialog box. Key in the users or groups you wish to add, separated by
semi-colons. Select the type of privilege:
1. Operator privileges allow the user or group to manage jobs that it does not own.
2. Manager privileges allow the user or group full privileges in the batch system. By
default, the Administrators group is granted Manager privileges.
Click OK to add the users or groups. Note that the selected privilege applies to all users or
groups being added; you cannot add an operator and a manager at the same time.
Remove - Removes the selected user or group from the authorization list.
Remove All - Removes all users (except the built-in Administrators group) from the
authorization list.
View Menu
The View menu toggles display of the tool and status bars.
Toolbar - Toggles display of the toolbar, which provides mouse access to commands provided
in the Queue and Job menus.
Status Bar - Toggles display of the status bar. The status bar displays information about the
queue or server view, such as inflow/outflow states, queue name, and the server name.
Refresh - Refreshes the active Queue View or Server View.
Toolbar command (View Menu)

Toggles display of the tool bar. The toolbar provides mouse access to commands provided in
the Queue and Job menus. To toggle the display of the toolbar, select Toolbar.
Status Bar command (View Menu)

The status bar displays information about the server or queue view. For the server view, the
status bar displays the server name. For the queue view, the status bar indicates relevant queue
status, including queue name, queue type, queue description, and inflow and outflow states.
To toggle the display of the status bar, select Status Bar.
75
Refresh command (View Menu)

Manually refreshes the active view. By default, queue views and server view are refreshed every
5 seconds.
Help Menu
The help menu allows you to display a comprehensive index of information contained in the
Batch Services help system, display the main contents page of the help system, and display
information about the current version of Batch Services.
Contents - Displays the introductory page of the help system. You can also select the Contents
button from the help system.
Using Help - Displays brief instructions for using the help system.
About Batch Manager - Displays the current version of Batch Services.
Contents command (Help Menu)

Allows you to access the Batch Manager online help system that is delivered with the Batch
Services product.
Context Sensitive Help Button

Starts context sensitive help. Select this button, and then click the cursor on the Batch Manager
interface. Batch Manager displays help for the selected view, command, or button.
Using Help command (Help Menu)

Displays help for using Windows help.
About Batch command (Help Menu)

Displays information about Batch Manager, including the current version.
Script Browser
Selects an existing script for submission. Select or type the name of the script you want to
submit in the File Name box. This box lists scripts with the filename extension selected in the
List Files of Type box. By default, the Script Browser lists the executable extensions (.EXE,
.BAT, .COM, .PIF). The All Files (*.*) option lists all files in the current directory.
Drives - Select the drive that contains the script you want to submit.
Directories - Select the directory that contains the script.
Network - Opens the Connect Network Drive dialog box so you connect to a network drive. For
more information, select Help in the dialog box.
76
Script Examples
A batch job reads a script and performs the instructions in it, using the appropriate shell (the
program that runs the instructions in the script). Scripts can take many forms, including .bat files
and Perl scripts. A script can also be an executable program (.EXE file) if the queue has no
default shell or if the default shell is set to CMD.EXE.
The following example is a .bat script that backs up a directory on the batch server to a shared
drive that has been locally mounted from a remote system. To use the script, ensure that a
batch queue has been created, enabled, and started, and that the queue's default shell is the
cmd.exe program.
REM This script will do the following:
REM
REM
1. Mount the shared drive \\machine\share
REM
2. Copy all files in c:\users\default to the shared drive.
REM
3. Unmount the shared drive.
REM
net use p: \\machine\share
copy c:\users\default\*.* p:
net use /delete p:
The following example is a .bat script that prints all PostScript files in the c:\temp directory on
the batch server to a printer on a remote Windows system. To use the script, ensure that a
batch queue has been created, enabled, and started; that the queue's default shell is the
cmd.exe program; and that the server system has access to the printer on the remote Windows
system.
REM This script will do the following:
REM
REM
1. Associate a remote printer on a Windows system
REM
(\\machine\printer) with a local printer port.
REM
2. Copy files in c:\temp that end in .ps to the local printer
REM
port.
REM
3. Remove the printer association.
REM
net use lpt1: \\machine\printer
cd c:\temp
for %%I in (*.ps) do copy %%I lpt1:
net use /delete lpt1:
77
78
SECTION 5
Batch Client API

The Batch Client API provides an application-level interface for performing batch-oriented tasks.
All communications with the batch server are done through the Batch Client API. The API
handles the details of communicating with the batch server and returning data to the calling
applications.
In This Section
API Description ........................................................................... 79
Batch Client API interface ........................................................... 80
Batch API Structures................................................................... 81
Batch API Function Calls ............................................................ 93
API Error Codes.......................................................................... 127
API Description
The Batch Client API provides an application-level interface for performing batch-oriented tasks.
All communications with the batch server are done through the Batch Client API. The API
handles the details of communicating with the batch server and returning data to the calling
applications.
Use the following steps to use the Batch Client API:
1. Programs should include the header file Batchapi.h, located in the batchapi sub-directory of
the batch product directory.
2. Applications that use Batch API functions should link with the batchapi.lib library in the same
directory.
3. At run time, the DLLs in the batch product bin directory should be in the applications' path.
Batch Provider DLLs

Since the Batch Client API must communicate with remote batch servers using at least two
completely different protocols, the Batch Client API functions are implemented in separate DLLs
centered on these communications protocols. These DLLs are known as batch providers.
79
Batch Client API

The front end of the batch client API acts as a switch. Based on the syntax of the jobid, queue
name, or server name passed into the API call, the request is routed to the correct batch
provider DLL for action, as shown in the following diagram:
At this time, only the NTBAT.DLL batch provider that communicates with Windows batch servers
is available.
Argument Syntax
If the syntax of the argument does not conform to the syntax expected by any of the batch
providers, the value ERROR_INVALID_PARAMETER is returned to the caller, and the operation
is not performed. If a batch provider is selected but cannot perform the given API function, the
value BATCH_ERROR_NOT_SUPPORTED is returned. Otherwise, the batch provider
performs the operation and provides a return value.
Batch Client API interface

The external interface to the Batch Client API is advertised by a header file (BATCHAPI.H)
containing the relevant constants, structures, and function prototypes.
In general, Batch Client APIs work the same when applied to either batch or pipe queues.
However, when using an API to retrieve or modify a BATCH_QUEUE_INFO_2 (on page 82)
structure, remember to take into account the differences between batch queues (shell lists and
default shells) and pipe queues (destination lists).
The function implementations are accessed through the Batch Client API DLL.
Remote Operations and Batch API

The following table shows the syntax for specifying various parameters in the batch system.
80
Parameter
Local Syntax
Remote Syntax
server
NULL or empty
\\host
queue
queue
\\host\queue
job-id
seqno.host
\\host\job-id
user
user
host\user, domain\user
group
group
host\group, domain\group
file
filename
\\host\filename
Batch Client API
Batch API Structures

The following structures are used as parameters for the API function calls. The structures
describe batch jobs and queues in both a brief and extended format. There is also a structure
describing the server.
BATCH_QUEUE_INFO_1 (on page 81)
BATCH_QUEUE_INFO_2 (on page 82)
BATCH_JOB_INFO_1 (on page 85)
BATCH_JOB_INFO_2 (on page 86)
BATCH_RECURRENCE_INFO (on page 90)
BATCH_SERVER_INFO (on page 92)
BATCH_QUEUE_INFO_1
Description
The BATCH_QUEUE_INFO_1 structure is a short form of the queue information suitable for
quick status update or for changing common queue attributes.
Structure
struct _batchQinfo1
{
LPTSTR qname
/* full batch queue name */
DWORD qtype
/* type: BATCH or PIPE */
DWORD state
/* INFLOW | OUTFLOW */
DWORD qpri
/* intraqueue priority */
DWORD jobcount
/* number of jobs currently in queue */
LPTSTR description
/* text description of queue */
LPBYTE reserved
/* NULL: reserved for future features. */
} BATCH_QUEUE_INFO_1, *PBATCH_QUEUE_INFO_1;
Parameters
LPTSTR qname
The full name of the queue, including the server name.
DWORD qtype
The queue type. This value is either

BATCH_QUEUE_TYPE_BATCH (batch queue) or
BATCH_QUEUE_TYPE_PIPE (pipe queue).
DWORD state
The state of the queue, either inflow or outflow (a bitwise OR of

the inflow and outflow states). The following states are valid:
BATCH_QUEUE_INFLOW_STATE_CLOSED
BATCH_QUEUE_INFLOW_STATE_ENABLED
BATCH_QUEUE_INFLOW_STATE_DISABLED
The following outflow states are valid:
81
Batch Client API

BATCH_QUEUE_OUTFLOW_STATE_STARTED
BATCH_QUEUE_OUTFLOW_STATE_STOPPED
BATCH_QUEUE_OUTFLOW_STATE_STOPPING
BATCH_QUEUE_OUTFLOW_STATE_SHUTDOWN
DWORD qpri
The priority of the queue, which is used to determine the relative

order of access to limited resources between queues. Queue
priorities range from 0 to 64.
DWORD jobcount
The number of jobs in this queue.
LPTSTR description
A user-supplied text description of the queue.
LPBYTE reserved
NULL pointer. In future versions, this pointer may reference

added queue attributes.
BATCH_QUEUE_INFO_2
Description
The BATCH_QUEUE_INFO_2 structure completely describes a queue and all of its attributes.
Structure
struct _batchQinfo2
{
LPTSTR qname
/* full batch queue name */
DWORD qtype
/* type: BATCH or PIPE */
DWORD state
/* INFLOW | OUTFLOW */
DWORD qpri
/* intraqueue priority */
long defaultpri
/* default job priority */
DWORD runprilimit
/* maximum run-time priority. */
DWORD runlimit
/* max running jobs */
DWORD sizelimit
/* max size of incoming jobs. [Not Implemented] */
DWORD jobcount
/* number of jobs currently in queue */
LPTSTR description
/* text description of queue */
PSECURITY_DESCRIPTOR
pSD
/* who can use this queue */
FILETIME system
/* amount of kernel time used by jobs */
FILETIME user
/* amount of user time used by jobs */
DWORD processor_affinity
/* multiprocessor flags */
LPBYTE reserved
/* NULL: reserved for future features */
union v
{
82
Batch Client API

struct batch
{
LPTSTR *shell_list
/* list of valid shells for this queue */
LPTSTR defaultshell
/* default shell for jobs */
};
struct pipe
{
LPTSTR *dest_list
/* list of pipe queue destinations */
};
}
} BATCH_QUEUE_INFO_2, *PBATCH_QUEUE_INFO_2;
Parameters
LPTSTR qname
The full name of the queue, including the server name.
DWORD qtype
The queue type. This value is either

BATCH_QUEUE_TYPE_BATCH (batch queue) or
BATCH_QUEUE_TYPE_PIPE (pipe queue).
DWORD state
The queue state (a bitwise OR of the inflow and outflow

states). The following inflow states are valid:
BATCH_QUEUE_INFLOW_STATE_CLOSED
BATCH_QUEUE_INFLOW_STATE_ENABLED
BATCH_QUEUE_INFLOW_STATE_DISABLED
The following outflow states are valid:
BATCH_QUEUE_OUTFLOW_STATE_STARTED
BATCH_QUEUE_OUTFLOW_STATE_STOPPED
BATCH_QUEUE_OUTFLOW_STATE_STOPPING
BATCH_QUEUE_OUTFLOW_STATE_SHUTDOWN
DWORD qpri
The priority of the queue, which is used to determine the

relative order of access to limited resources between
queues. Queue priorities range from 0 to 64.
long defaultpri
The priority assigned to jobs in the queue that do not

have a job priority set, in the range -1024 to 1023. The
default value is 31.
DWORD runprilimit
The maximum run-time job priority allowed in this queue.

This limit is only enforced for batch queues. The following
values are valid (the default priority is
NORMAL_PRIORITY_CLASS):
IDLE_PRIORITY_CLASS
NORMAL_PRIORITY_CLASS
83
Batch Client API

HIGH_PRIORITY_CLASS
REALTIME_PRIORITY_CLASS
A REALTIME process preempts all other
processes, including the operating system. Intergraph
recommends that you avoid using the REALTIME
priority.
DWORD runlimit
The maximum number of simultaneous running jobs

allowed in this queue. The default runlimit is 1.
DWORD sizelimit
The maximum total file size allowed for a batch job. This
limit is not enforced, but may be used in later versions.
DWORD jobcount
The number of jobs in this queue.
LPTSTR description
A user-supplied text description of the queue.
PSECURITY_DESCRIPTOR
pSD
A security descriptor containing the access control list for

this queue. By default, the access control list will allow all
users to have submit access to the queue.
FILETIME system
The cumulative system-execution time used by all batch

jobs run in this queue since its creation.
FILETIME user
The cumulative user-space execution time used by all

batch jobs run in this queue since its creation.
DWORD processor_affinity
A bitmask of flags used to set multiprocessor options.
LPBYTE reserved
A NULL pointer. In future versions, this pointer may

reference added queue attributes.
union v
A union of structures containing batch and pipe queue

specific information.
v.batch
LPTSTR *shell_list
A structure containing batch queue specific information

that is not needed for other queue types.
A list of command interpreters that jobs are allowed to
use for this queue. The list is in the format
shellname=shellpath, where shellname is the short text
name of the shell (such as ksh, perl, or DOS), and
shellpath is a full pathname to the corresponding
command interpreter.
The same pathname may be used for more than one
shellname, but the shellnames must be unique. Both
shellname and shellpath may be of unlimited length.
LPTSTR defaultshell The name of the default command interpreter for batch
shell scripts.
v.pipe
LPTSTR *dest_list
84
A structure containing pipe queue specific information

that is not needed for other queue types.
A list of pipe queue destinations. The list consists of full
queue names (including the server name) to which jobs
in the pipe queue may be routed.
Batch Client API
BATCH_JOB_INFO_1
Description
The BATCH_JOB_INFO_1 structure contains the most common job attributes needed for a
quick status check.
Structure
struct _batchjobinfo1
{
LPTSTR jobid;
/* full unique job identifier */
LPTSTR owner;
/* who owns this job */
LPTSTR name;
/* user description of job */
long priority;
/* assigned job priority */
DWORD size;
/* size of job data files */
DWORD state;
/* state of the job */
LPBYTE reserved;
/* reserved for future features */
} BATCH_JOB_INFO_1, *PBATCH_JOB_INFO_1;
Parameters
LPTSTR jobid
A string containing the unique job identifier. No

two jobs may have the same jobid. The jobid
string is in the format idnum.orighost, where
orighost is the name of the computer to which
the job was originally submitted, and idnum is
the nth job submitted to that host. The id
numbers do not exceed 5 digits, and are reset
to zero after 99,999 jobs have been submitted.
LPTSTR owner
The account name of the owner of this batch

job.
LPTSTR name
The user-supplied name of the job. The default

job name is the name of the script file.
long priority
The job priority used for scheduling execution of

the job. Higher priority jobs are placed first in
the queue, and run before lower priority jobs.
The range of priorities is -1024 to 1023.
DWORD size
The sum of the size of all files associated with

this job.
DWORD state
The state of the job. The following states are

possible:
BATCH_JOB_STATE_QUEUED
The job has been queued.
BATCH_JOB_STATE_RUNNING
The job is currently running.
BATCH_JOB_STATE_HELD
The job is in a hold state.
BATCH_JOB_STATE_WAITING
The job is waiting for execution.
85
Batch Client API

BATCH_JOB_STATE_EXITING
The job has completed, and is exiting the batch

subsystem.
BATCH_JOB_STATE_TRANSITING The job is being transferred.

BATCH_JOB_STATE_RECURRING The job is a recurring job.
BATCH_JOB_STATE_ARRIVING
LPBYTE reserved
The job is arriving in the batch subsystem.

NULL pointer. In future versions, this pointer
may reference added job attributes.
BATCH_JOB_INFO_2
The BATCH_JOB_INFO_2 structure contains all of the information about a batch job and its
attributes.
Structure
struct_batchjobinfo2
{
86
LPTSTR jobid
/* full unique job identifier */
LPTSTR owner
/* who owns this job */
LPTSTR name
/* user description of job */
long priority
/* assigned job priority */
DWORD runpriority
/* system priority level to run job at */
DWORD restartable
/* should job ever be restarted? */
FILETIME starttime
/* when to run the job. */
DWORD size
/* size of job data files */
DWORD state
/* state of the job */
LPTSTR qname
/* which queue this job is in */
DWORD holds
/* types of hold on job */
LPTSTR script
/* path of script to execute */
LPTSTR reserved2
/* reserved for future use */
LPTSTR Stderr
/* path of stderr file */
LPTSTR Stdout
/* path of stdout file */
FILETIME system
/* amount of system time used */
FILETIME user
/* amount of user time used */
LPTSTR shell
/* which shell to use. NULL=default */
char **envp
/* execution environment */
LPTSTR logmsg
/* user-defined log msg */
LPTSTR account
/* accounting label */
Batch Client API

LPTSTR *infiles
/* files to stage in */
LPTSTR *outfiles
/* files to stage out */
DWORD origin
/* native NT, other */
LPTSTR *mailaddress
/* list of addresses to send mail to */
DWORD flags
/* bit mask of flags for batch job */
DWORD filesizelimit
/* limit on the size of files in this job */
BATCH_RECURRENCE_I /* recurring job information */

NFO recurrence
} BATCH_JOB_INFO_2, *PBATCH_JOB_INFO_2;
Parameters
LPTSTR jobid
A string containing the unique job identifier. No two jobs

may have the same jobid. The jobid string is in the format
idnum.orighost, where orighost is the name of the computer
to which the job was originally submitted, and idnum is the
nth job submitted to that host. The id numbers do not
exceed 5 digits, and are reset to zero after 99,999 jobs
have been submitted.
LPTSTR owner
The account name of the owner of this batch job.
LPTSTR name
The user-supplied name of the job.
long priority
The job priority used for scheduling execution of the job.

Higher priority jobs are placed first in the queue, and run
before lower priority jobs.
DWORD runpriority
The system execution priority for the job. This must be less
than or equal to the runprilimit of the queue. The following
priorities are valid:
IDLE_PRIORITY_CLASS
NORMAL_PRIORITY_CLASS
HIGH_PRIORITY_CLASS
REALTIME_PRIORITY_CLASS
A REALTIME process preempts all other processes,
including the operating system. Intergraph recommends
that you avoid using the REALTIME priority.
DWORD restartable
Whether the job should be rescheduled in the event that

the job is aborted due to a system error or crash. A
non-zero value causes the job to be rescheduled.
FILETIME starttime
The time at which the job is to be executed. If this time is 0

or less than the current time, then the job will be executed
as soon as possible.
DWORD size
The sum of size of all files associated with this job.
DWORD state
The state of the job. The following states are possible:
87
Batch Client API

BATCH_JOB_STATE_QUEUED
The job has been queued.
BATCH_JOB_STATE_RUNNING
The job is currently running.
BATCH_JOB_STATE_HELD
The job is in a hold state.
BATCH_JOB_STATE_WAITING
The job is waiting for execution.
BATCH_JOB_STATE_EXITING
The job has completed, and is exiting the batch

subsystem.
BATCH_JOB_STATE_TRANSITING The job is being transferred.

BATCH_JOB_STATE_ARRIVING
The job is arriving in the batch subsystem.
BATCH_JOB_STATE_RECURRING The job is a recurring job.
88
LPTSTR qname
The name of the queue in which the job resides.
DWORD holds
Any combination of BATCH_USER_HOLD or

BATCH_MGR_HOLD. If this value is 0, then no holds are
applied to the job. (The holds value is a bitwise OR of the
applicable hold types.) Jobs may be submitted with a user
hold.
LPTSTR script
The pathname of the batch job script file. This script

contains the commands for the shell that comprise the
batch job.
LPTSTR reserved2
Reserved for future use.
LPTSTR Stderr
The path name of the file that will contain the standard
error output of the job. If this value is NULL, then a default
stderr path name will be used (jobname.e).
LPTSTR Stdout
The pathname of the file that will contain the standard

output of the batch job. If this value is NULL, then a default
stdout path name will be used (jobname.o).
FILETIME system
The total amount of system execution time used by this job.
FILETIME user
The total amount of user execution time used by this job.
LPTSTR shell
The name of the command interpreter for running the shell

script.
char **envp
A list of environment variables to be used in the batch job

environment during execution.
LPTSTR logmsg
A user-defined line of text to be inserted into the log file

when the job is executed.
LPTSTR account
A user-defined text string that may be used for accounting

purposes.
LPTSTR infiles
A list of files that the batch job requires before beginning

execution. This is also called "staging files in." The format
of this list is dest_file=source_file, where dest_file is the
name to call the file on the execution machine, and
source_file is the name of the file to send to the execution
computer. For more information, see file staging (on page
15).
Batch Client API

LPTSTR outfiles
A list of files that the batch job returns to the user after
execution. This is also called "staging files out." The format
of this list is source_file=dest_file, where source_file is the
name of the file on the execution computer, and dest_file is
the name and location of the output file. For more
information, see file staging (on page 15).
DWORD origin
A value determining where the job came from, and thus the
transport mechanism to use when returning files to a
remote client. The following values are possible:
BATCH_JOB_ORIGIN_LOCAL
For a job that has not left the local computer.
BATCH_JOB_ORIGIN_NT
For a job that originated on an Windows computer.
LPTSTR *mailaddress
A NULL-terminated list of strings representing addresses

that mail about this batch job may be sent to. Currently, the
formats supported are SMTP mail addresses and event log
messages. If this field is supplied by the user as NULL, a
default of \\localhost is used. In this case, messages about
the job are sent to the event log on the local host.
DWORD flags
A bitmask of flags that affect the batch job. The following

flags are valid:
BATCH_JOB_FLAG_KEEP_STDOUT
BATCH_JOB_FLAG_KEEP_STDERR
BATCH_JOB_FLAG_NOSPOOL_STDOUT
BATCH_JOB_FLAG_NOSPOOL_STDERR
BATCH_JOB_FLAG_MAIL_BEGINNING
BATCH_JOB_FLAG_MAIL_END
BATCH_JOB_FLAG_MAIL_ABORT
BATCH_JOB_FLAG_COMBINE_OUTPUT
BATCH_JOB_FLAG_HOURLY_FREQUENCY
BATCH_JOB_FLAG_DAILY_FREQUENCY
BATCH_JOB_FLAG_WEEKLY_FREQUENCY
BATCH_JOB_FLAG_MONTHLY_FREQUENCY
BATCH_JOB_FLAG_YEARLY_FREQUENCY
BATCH_JOB_FLAG_SPECIFIC_TYPE (must be used with
either BATCH_JOB_FLAG_MONTHLY_FREQUENCY or
BATCH_JOB_FLAG_YEARLY_FREQUENCY)
BATCH_JOB_FLAG_DETERMINED_TYPE (must be used
with either BATCH_JOB_FLAG_MONTHLY_FREQUENCY
or BATCH_JOB_FLAG_YEARLY_FREQUENCY)
89
Batch Client API

BATCH_RECURRENCE_INFO
recurrence
Describes scheduling details of jobs that run more than

once. Unused unless a recurring job flag is set in the flags
field.
BATCH_RECURRENCE_INFO
The BATCH_RECURRENCE_INFO structure contains scheduling information for recurring
jobs (on page 162). It is only used within the BATCH_JOB_INFO_2 structure and is
ignored unless one of the recurring jobs flags is set in the flags field of the
BATCH_JOB_INFO_2 structure. The interpretation of its contents depends on which
recurring job flags are set in the flags field.
Two types of monthly and yearly recurring jobs are available. When using the API to
schedule monthly or yearly recurring jobs, you must specify which type of monthly or yearly
job you are scheduling by using either the BATCH_JOB_FLAG_SPECIFIC_TYPE or the
BATCH_JOB_FLAG_DETERMINED_TYPE along with the monthly or yearly frequency type
in the flags field of the BATCH_JOB_INFO_2 structure.
The first type of monthly or yearly job is called specific since the user specifies a specific
execution date for it. An example of a specific monthly job is a job that is scheduled to run
on the 15th day of every 2 months. An example of a specific yearly job is a job that is
scheduled to run on July 30 of each year.
The second type of monthly or yearly job is called determined since its actual execution date
is not specified but instead is determined from the scheduling information that is supplied.
An example of a determined monthly job is a job that is scheduled to run on the last
Tuesday of every 2 months. An example of a determined yearly job is a job that is
scheduled to run on the third Wednesday of July of each year.
Structure
typedef union _recurrenceInfo
{
struct union
{
BYTE interval;
/* BATCH_JOB_FLAG_HOURLY_FREQUENCY: hour interval,

BATCH_JOB_FLAG_DAILY_FREQUENCY: day interval,
BATCH_JOB_FLAG_WEEKLY_FREQUENCY: week interval,
BATCH_JOB_FLAG_DETERMINED_MONTHLY_FREQUENCY:
Nth day information (1st, 2nd, 3rd, 4th, or last (5) day, weekday, or
weekend day) or
BATCH_JOB_FLAG_DETERMINED_YEARLY_FREQUENCY:
Nth day information (1st, 2nd, 3rd, 4th, or last (5) day, weekday, or
weekend day) */
BYTE month_interval;
90
/* BATCH_JOB_FLAG_SPECIFIC_MONTHLY_FREQUENCY:
month interval, or
month interval. */
Batch Client API

BYTE
day_information;
/* BATCH_JOB_FLAG_WEEKLY_FREQUENCY:
day of the week mask,
BATCH_JOB_FLAG_SPECIFIC_MONTHLY_FREQUENCY:
day of the month, or
BATCH_JOB_FLAG_SPECIFIC_YEARLY_FREQUENCY:
day of the month. */
BYTE month_of_year; /* BATCH_JOB_FLAG_SPECIFIC_YEARLY_FREQUENCY:

month of the year, or
month of the year. */
} recurrence_info;
DWORD recurrence_data;
} BATCH_RECURRENCE_INFO, *PBATCH_RECURRENCE_INFO;
Parameters
BYTE interval
A byte containing the hourly interval for hourly jobs, the daily
interval for daily jobs, or the weekly interval for weekly jobs. The
valid interval values are 1 to 99. For monthly and
yearly-determined jobs, this byte contains a number from 1 to 5
representing an ordinal (first, second, third, fourth, or last) that
indicates which day, weekday, or weekend day is being chosen.
For example a 1 would mean the first such day, and a 5 would
mean the last such day.
BYTE month_interval
A byte containing a number that represents the monthly interval for

monthly recurring jobs. Valid values are 1 to 99.
BYTE day_information
A byte containing a mask that represents the selected days of the

week for weekly jobs, monthly-determined jobs, or
yearly-determined jobs. Use the BATCH_JOB_*_OCCURRENCE
defines for 'day of the week' mask values. For monthly specific jobs
and yearly specific jobs, this number represents a specific day of
the month.
BYTE month_of_year
A byte containing a number that represents the month of the year

for yearly specific and yearly-determined jobs. The 'month of the
year' the values are: January = 1, February = 2, ..., December = 12.
91
Batch Client API
BATCH_SERVER_INFO
The BATCH_SERVER_INFO structure contains attributes for the server and overall batch
environment.
Structure
struct _batchservinfo
{
DWORD state
/* batch server state */
PSECURITY_DESCRIPTOR pSD
/* Access control list */
LPTSTR defaultqueue
/* default batch queue */
DWORD debuglevel
/* level of information for log file */
LPTSTR reserved 2
LPBYTE reserved
} BATCH_SERVER_INFO, *PBATCH_SERVER_INFO;
Parameters
DWORD state
The state of the batch server. The following values are

possible:
BATCH_SERVER_STATE_INITIALIZING
BATCH_SERVER_STATE_RUNNING
BATCH_SERVER_STATE_EXITING
BATCH_SERVER_STATE_SHUTDOWN
PSECURITY_DESCRIPTOR pSD A security descriptor containing the access control list

for this server. A user or group may be an operator or
a manager.
By default, a user may only get information about the
server, jobs and queues. Job management access
grants the user or group the ability to manipulate jobs
that it does not own (this grants the user operator
privileges).
Full management access grants all privileges to the user
or group. The default server access control list
contains the group Administrators, with full management
access. The Administrators group will always have full
management access.
LPTSTR defaultqueue
92
The queue to be used if for some reason a queue name

is not given for a job.
Batch Client API

DWORD debuglevel
A bitmask of the following values:

BATCH_LOG_SERVER
BATCH_LOG_QUE
BATCH_LOG_JOB
BATCH_LOG_JOB_ERROR
BATCH_DEBUG_SERVER
BATCH_DEBUG_QUEUE
BATCH_DEBUG_JOB
BATCH_DEBUG_PIPE
BATCH_DEBUG_PACKETS
BATCH_DEBUG_OTHER
LPBYTE reserved 2

reference added server attributes.
LPBYTE reserved

reference added server attributes.
Batch API Function Calls

Each API function call is prototyped in a batch API header file. These functions are available in a
library file (BATCHAPI.LIB) that an application can link with at compile time. The actual functions
are contained in a DLL (BATCHAPI.DLL), which is loaded at run-time. Each function call returns
an error code. The ERROR_SUCCESS (0) return value indicates that the function successfully
completed. A set of Batch-specific and other general error codes is defined in API Error Codes
(on page 127).
BatchAbortJob (on page 94)
BatchAbortQueue (on page 95)
BatchCreateQueue (on page 96)
BatchDeleteJob (on page 98)
BatchDeleteQueue (on page 99)
BatchDisableQueue (on page 100)
BatchEnableQueue (on page 101)
BatchEnumerateJobs (on page 102)
BatchEnumerateQueues (on page 103)
BatchGetJobInfo (on page 104)
BatchGetQueueInfo (on page 105)
BatchGetServerInfo (on page 107)
BatchJobHold (on page 108)
BatchJobRelease (on page 109)
BatchMoveJob (on page 110)
BatchPurgeQueue (on page 112)
BatchServerShutdown (on page 113)
BatchSetJobInfo (on page 114)
BatchSetQueueInfo (on page 116)
BatchSetServerInfo (on page 119)
BatchStartQueue (on page 121)
BatchStopQueue (on page 122)
QueueBatchJob (on page 123)
93
Batch Client API
BatchAbortJob
Description
Aborts the execution of a running job. The caller must either own the job, or have operator
privileges on the server on which the job is running.
Syntax
DWORD BatchAbortJob(LPCTSTR jobid, DWORD restart, LPCTSTR reserved);
Parameters
LPCTSTR jobid
Specifies the unique job-identification string.
DWORD restart
Specifies a flag indicating whether or not the job may be

re-scheduled for execution. If the value is 0, the job is deleted.
LPCTSTR reserved
This parameter is reserved for future use, and is currently

ignored.
Return Values
BATCH_ERROR_JOB_NOT_RUNNIN
G
The job is not running. Use BatchDeleteJob

(on page 98) to cancel a job that is not
running.
BATCH_ERROR_NO_SUCH_JOB
The system could not find the named job.
BATCH_ERROR_BAD_JOB_NAME
The jobid was null or the syntax was incorrect.
BATCH_ERROR_OWNER_OR_OPER
ATOR_ACCESS_DENIED
The caller neither owns the job nor has

operator privileges.
Example Program
#include <iostream.h>
#include "batchapi.h"
#define MAX_LENGTH 25
void main()
{
LPCTSTR FirstArg;
LPCTSTR LastArg = NULL;
TCHAR * pJobId;
DWORD
ReturnVal = 9999;
DWORD
Restart = 0;
DWORD
SigNo = NULL;
cout << " STARTING OF BATCHABORTJOB API " << endl;
pJobId = new TCHAR [ MAX_LENGTH ];
if (pJobId==NULL){
cout << "Unable to allocate the Memory.\n Exiting the program"<<endl;
exit(0);
}
cout << " Enter the job-id of the job to Abort ";
cin >> pJobId;
FirstArg = (const TCHAR *)pJobId;
ReturnVal = BatchAbortJob ( FirstArg , Restart , SigNo , LastArg );
switch ( ReturnVal)
{
case BATCH_ERROR_JOB_NOT_RUNNING:
cout << " The job is not running. Use BatchDeleteJob to cancel a job that is not running : " << FirstArg
<< endl;
break;
case BATCH_ERROR_NO_SUCH_JOB:
cout << " The system could not find the named job : " << FirstArg << endl;
break;
case BATCH_ERROR_BAD_JOB_NAME:
cout << " The jobid was null or the syntax was incorrect : " << FirstArg << endl;
break;
case BATCH_ERROR_OWNER_OR_OPERATOR_ACCESS_DENIED:
cout << " The caller neither owns the job nor has operator privileges. : " << FirstArg << endl;
94
Batch Client API

break;
case 0:
cout << "JOB HAS BEEN SUCCESSFULLY ABORTED" <<endl;
break;
default:
cout << "Abort of the job couldn't be completed.\nThe call returned "<<ReturnVal<<endl;
}
cout << " FINISHED EXECUTING OF BATCHABORTJOB API " <<endl;
delete [] pJobId;
}
BatchAbortQueue
Description
Aborts all running jobs in the named queue. The caller must have operator privileges on the
server.
Syntax
DWORD BatchAbortQueue(LPCTSTR queuename, DWORD restart);
Parameters
LPCTSTR queuename
Specifies the name of the queue to abort.
DWORD restart
Specifies a flag indicating whether or not jobs may be re-scheduled

for execution. If this flag is 0, the jobs are deleted.
Return Values
BATCH_ERROR_NO_SUCH_QUEUE
The queue does not exist.
BATCH_ERROR_BAD_QUEUE_NAME
The syntax of the queue name was not valid.
BATCH_ERROR_OPERATOR_
ACCESS_DENIED
The user does not have operator privileges.
Example Program
void main()
{
char * pTemp = NULL;
LPCTSTR QueName;
DWORD ReturnVal = 0;
DWORD Status = 0;
cout << "STARTING THE EXECUTION OF BATCHABORTQUEUE API "<< endl;
pTemp = new char[ MAX_LENGTH];
if (pTemp == NULL){
cout << " Unable to allocate the memory.\n Exiting the program "<<endl;
exit(0);
}
cout << " Enter the name of the QUEUE to Abort"<< endl;
cin >> pTemp;
QueName = (const char *)pTemp;
cout << " Enter the status whether to restart or not"
<< " 0
for DELETION
1 for Restarting "<< endl;
cin >> Status;
ReturnVal = BatchAbortQueue( QueName,Status);
switch(ReturnVal)
{
case BATCH_ERROR_NO_SUCH_QUEUE
:
cout << " The queue does not exist. " << endl;
break;
case BATCH_ERROR_BAD_QUEUE_NAME
:
cout << " The syntax of the queue name was not valid. " << endl;
break;
case BATCH_ERROR_OPERATOR_ACCESS_DENIED
:
cout << " The user does not have operator privileges. " << endl;
break;
default:
cout << "SUCCESSFUL COMPLETION OF ABORTING THE QUEUE "<< endl;
}
95
Batch Client API

cout << "COMPLETED THE EXECUTION OF BATCHABORTQUEUE API "<< endl;
delete [] pTemp;
}
BatchCreateQueue
Description
Creates a batch queue on a batch server. The caller must have management privileges on the
server. The queue is described by the BATCH_QUEUE_INFO_2 (on page 82) structure.
Default values for this structure have been defined, see BatchCreateQueue Default
BATCH_QUEUE_INFO_2 Values (on page 97).
Syntax
DWORD BatchCreateQueue(LPCTSTR queue, BATCH_QUEUE_INFO_2 qinfo);
Parameters
LPCTSTR queue
Specifies the full name of the queue to create.
BATCH_QUEUE_INFO_2 qinfo
Points to a structure describing the queue.
Return Values
BATCH_ERROR_ALREADY_EXISTS
The queue already exists
BATCH_ERROR_BAD_QUEUE_TYPE
The queue type was neither pipe nor batch.
BATCH_ERROR_MANAGER_
ACCESS_DENIED
The user does not have manager privileges.
Example Program
void main()
{
LPCTSTR QueName;
DWORD TempVar=NULL;
DWORD ReturnVal=NULL;
char * pTempName;
BATCH_QUEUE_INFO_2 NewQue;
cout << " STARTED EXECUTION OF BATCHCREATEQUEUE API"<< endl;
pTempName = new char[ MAX_LENGTH];
if ( pTempName ==NULL ){
cout << "Unable to allocate the memory."<<endl;
exit(0);
}
cout << " Enter the Queue Name to be created ";
cin
>> pTempName;
QueName = (const char *)pTempName;
cout << " Enter the Queue Type 1 PIPE QUEUE 2 for BATCH QUEUE ";
cin >> TempVar;
if (TempVar == 1)
NewQue.qtype = BATCH_QUEUE_TYPE_PIPE;
else
if (TempVar == 2)
NewQue.qtype = BATCH_QUEUE_TYPE_BATCH;
else
NewQue.qtype = 3;
cout << " Enter the priority type ";
cin >> TempVar;
NewQue.qpri = TempVar;
cout << " Enter the Max Running Jobs Limit ";
cin >> TempVar;
NewQue.runlimit = TempVar;
NewQue.pSD = NULL;
if ( NewQue.qtype == 2){
NewQue.defaultpri = 31;
NewQue.sizelimit = 1000000;
}
else
if (NewQue.qtype == 1) {
NewQue.defaultpri = 0;
NewQue.sizelimit = 0;
96
Batch Client API

}
ReturnVal = BatchCreateQueue( QueName , NewQue);
switch (ReturnVal)
{
case BATCH_ERROR_ALREADY_EXISTS
:
cout << " The queue already exists " << endl;
break;
:
cout << " Queue name was not valid. " << endl;
break;
case BATCH_ERROR_BAD_QUEUE_TYPE
:
cout << " The queue type was neither pipe nor batch. " << endl;
break;
case BATCH_ERROR_MANAGER_ACCESS_DENIED :
cout << " The user does not have manager privileges. " << endl;
break;
default:
cout << "SUCCESSFUL COMPLETION OF CREATEQUEUE "<< endl;
}
cout << " COMPLETED EXECUTION OF BATCHCREATEQUEUE API"<< endl;
delete [] pTempName;
}
BatchCreateQueue Default BATCH_QUEUE_INFO_2 Values

qname
This value cannot be set by the user, and is ignored.
qtype
The default is BATCH_QUEUE_TYPE_BATCH.
state
qpri
This value has no default, and must be set.
defaultpri
The default priority is 31.
runprilimit
The default is NORMAL_PRIORITY_CLASS.
runlimit
The default run limit is 1. Intergraph PDS does not support a run
limit greater than 1.
sizelimit
The default size limit is 1,000,000.
jobcount
description
This value has no default, and may be set to NULL.
pSD
system
user
processor_affinity
The default is 0.
v.batch.shell_list
v.batch.defaultshell
The default setting is no default shell.
v.pipe.dest_list
reserved
This value must be NULL.
97
Batch Client API
BatchDeleteJob
Description
Deletes the named batch job on the named server. The caller must own the job, or have
operator privileges on the server.
Structure
DWORD BatchDeleteJob(LPCTSTR jobid, LPCTSTR reserved);
Parameters
LPCTSTR jobid
LPCTSTR reserved
This parameter is reserved for future use, and is currently

ignored.
Return Values
BATCH_ERROR_JOB_IS_RUNNING
The job is currently running. Use

BatchAbortJob (on page 94) to cancel a
running job.
BATCH_ERROR_OWNER_OR_OPE
RATOR_ACCESS_DENIED
The caller neither owns the job nor has

Example Program
void main()
{
LPCTSTR JobId=NULL;
LPCTSTR Reserved=NULL;
char *
pJobId;
DWORD
ReturnVal=0;
cout << "TESTING THE BATCHDELETEJOB API"<<endl;
pJobId = new char [ MAX_LENGTH ];
if (pJobId == NULL){
cout << "unable to allocate the memory.\n Exiting the program"<<endl;
exit(0);
}
cout << "Enter the job-id of the job
cin >> pJobId;
JobId = (const char *)pJobId;
to delete";
ReturnVal = BatchDeleteJob(JobId,Reserved);
switch (ReturnVal)
{
case BATCH_ERROR_NO_SUCH_JOB :
cout << " The Job does not exist : " << JobId <<endl;
break;
case BATCH_ERROR_JOB_IS_RUNNING
:
cout << " The Job Is In Running Mode : " << JobId <<endl;
break;
case BATCH_ERROR_BAD_JOB_NAME :
cout << " The First argument syntax is wrong or it is NULL : " << JobId <<endl;
break;
case BATCH_ERROR_OWNER_OR_OPERATOR_ACCESS_DENIED :
cout << " The Job is Not Owned by the Current User : " << JobId << endl;
break;
default :
cout << "THE JOB HAS BEEN SUCCESSFULLY DELETED" <<endl;
break;
}
cout<<"FINISHED TESTING THE BATCHDELETEJOB API"<<endl;
delete [] pJobId;
}
98
Batch Client API
BatchDeleteQueue
Description
Deletes the named queue. The queue must be empty, and disabled before it can be deleted.
The caller must have management privileges on the server.
Syntax
DWORD BatchDeleteQueue(LPCTSTR queuename);
Parameter
LPCTSTR queuename
Specifies the name of the queue to delete.
Return Values
BATCH_ERROR_QUEUE_IS_ACTIVE
The queue is still enabled.
BATCH_ERROR_QUEUE_NOT_EMPTY
There are still jobs in the queue.
The syntax of the queue name was not

valid.
BATCH_ERROR_MANAGER_
ACCESS_DENIED
The user does not have manager

privileges.
Example Program
void main()
{
LPCTSTR QueName=NULL;
DWORD
ReturnVal=0;
char *
pTempName;
cout << "STARTED THE EXECUTION OF BATCHDELETEQUEUE API " << endl;
pTempName = new char [MAX_LENGTH];
if(pTempName == NULL){
cout << " Unable to allocate the memory." << endl;
exit(0);
}
cout << " Enter the Queue Name to be Deleted ";
cin >> pTempName;
ReturnVal = BatchDeleteQueue( QueName );
switch(ReturnVal)
{
:
break;
case BATCH_ERROR_QUEUE_IS_ACTIVE :
cout << " The queue is still enabled. " << endl;
break;
case BATCH_ERROR_QUEUE_NOT_EMPTY
:
cout << " There are still jobs in the queue. " << endl;
break;
:
break;
case BATCH_ERROR_MANAGER_ACCESS_DENIED
:
break;
default:
cout << "SUCCESSFUL DELETION OF THE QUEUE "<< endl;
}
cout << "FINISHED THE EXECUTION OF BATCHDELETEQUEUE API " << endl;
}
99
Batch Client API
BatchDisableQueue
Description
Sets the inflow state of the named queue to "DISABLED". The caller must have operator
privileges on the server.
Syntax
DWORD BatchDisableQueue(LPCTSTR queuename);
Parameter
LPCTSTR queuename
Specifies the name of the queue to disable.
Return Values

valid.
BATCH_ERROR_OPERATOR_
ACCESS_DENIED
The user does not have operator

privileges.
Example Program
void main()
{
DWORD
ReturnVal=0;
char * pTempName;
cout << " STARTING THE EXECUTION OF BATCHDISABLEQUEUE API " << endl;
if (pTempName == NULL){
cout << "Unable to allocate the memory." << endl;
exit(0);
}
cout << " Enter the Queue Name to be Deleted ";
cin >> pTempName;
ReturnVal = BatchDisableQueue(QueName );
switch(ReturnVal)
{
:
break;
case BATCH_ERROR_BAD_QUEUE_NAME :
break;
:
break;
default:
cout << " SUCCESSFUL COMPLETION OF DISABLING THE QUEUE "<< endl;
}
cout << " COMPLETED THE EXECUTION OF BATCHDISABLEQUEUE API " << endl;
}
100
Batch Client API
BatchEnableQueue
Description
Sets the inflow state of the named queue to "ENABLED". The caller must have operator
Syntax
DWORD BatchEnableQueue(LPCTSTR queuename);
Parameters
LPCTSTR queuename
Specifies the name of the queue to enable.
Return Values

valid.
BATCH_ERROR_OPERATOR_ACCESS The user does not have operator

_DENIED
privileges.
Example Program
void main()
{
char * pTemp;
DWORD
ReturnVal=0;
cout << "STARTED EXECUTION OF THE BATCHENABLEQUEUE API " << endl;
pTemp = new char [MAX_LENGTH];
if(pTemp == NULL){
cout << "unable to allocate the memory." << endl;
exit(0);
}
cout << "Enter the QUEUE TO ENABLE "<< endl;
cin >> pTemp;
QueName = (const char *) pTemp;
ReturnVal= BatchEnableQueue(QueName);
switch( ReturnVal)
{
:
break;
:
break;
:
break;
default:
cout << " SUCCESSFUL COMPLETION OF ENABLEQUEUE " << endl;
}
cout << "COMPLETED EXECUTION OF THE BATCHENABLEQUEUE API " << endl;
delete [] pTemp;
}
101
Batch Client API
BatchEnumerateJobs
Description
Enumerates all of the jobs associated with a given queue or server.
Syntax
DWORD BatchEnumerateJobs (LPCTSTR queue, DWORD level, LPBYTE jobbuf, DWORD
cbsize, LPDWORD cbneeded, LPDWORD jobcount);
Parameters
LPCTSTR queue
Specifies the queue name.
DWORD level
Specifies the amount to information to be returned for each job.

Levels 1 and 2 are supported, which correspond to the
BATCH_JOB_INFO_1 (on page 85) andBATCH_JOB_INFO_2 (on
page 86) structures, respectively.
LPBYTE jobbuf
Defines the buffer space to store an array of BATCH_JOB_INFO

structures.
DWORD cbsize
Specifies the size of the buffer in bytes.
LPDWORD cbneeded
Specifies the size of the returned information. If cbsize is too small,

ERROR_INSUFFICIENT_BUFFER is returned, and cbneeded is set
to the needed size.
LPDWORD jobcount
Defines a pointer to contain the number of jobs returned in the jobbuf.
Return Values
Could not find the named queue.
ERROR_INVALID_LEVEL
The level parameter is not 1 or 2.
The queue name syntax is not valid.
Example Program
void main()
{
LPBYTE Jobid;
char * pTemp=NULL;
DWORD
ReturnVal;
DWORD
Jobcount;
DWORD
Level;
DWORD
Need;
DWORD
CbSize;
cout << endl << "STARTING THE EXECUTION OF
CbSize = BATCH_JOB_ID_SIZE + 4;
BATCHENUMERATEJOBS API "<< endl;

if (pTemp ==NULL){
cout << "Unable to allocate the memory. Exiting." << endl;
exit(0);
}
cout << " Enter the Queue to Enumerate the Jobs ";
cin >> pTemp;
cout << " Enter the Level with Which to Enumerate the Jobs ";
cin >> Level;
ReturnVal = BatchEnumerateJobs(QueName , Level , NULL,0,&Need,&Jobcount);
// first time to get the cbsize ( which is returned in 5th(Need) argument)
Jobid = (LPBYTE)LocalAlloc(0,Need);
if (Jobid ==NULL){
cout << "unable to allocate the memory.\n Exiting"<<endl;
delete [] pTemp;
102
Batch Client API

exit(0);
}
CbSize= Need;
ReturnVal = BatchEnumerateJobs(QueName , Level , Jobid,CbSize,&Need,&Jobcount);
// Now we have the Data about the jobs from the queue QueName in Jobid which can
// be retrieved using an BATCH_JOB_INFO_2 or a BATCH_JOB_INFO_1 pointer variable
// For further Info See BatchSetJobInfo API example.
switch(ReturnVal)
{
:
cout << " Could not find the named queue. : " << QueName << endl;
break;
case ERROR_INVALID_LEVEL
:
cout << " The level parameter is not 1 or 2. " << endl;
break;
cout << " The queue name syntax is not valid. : " << QueName << endl;
break;
default :
cout << "Successfully enumerated the jobs " << endl;
}
cout << endl << "FINISHED THE EXECUTION OF BATCHENUMERATEJOBS API "<< endl;
delete [] pTemp;
LocalFree(Jobid);
}
BatchEnumerateQueues
Description
Returns information about all of the queues on a server.
Syntax
DWORD BatchEnumerateQueues(LPCTSTR server, DWORD level, LPBYTE qbuff, DWORD
cbsize, LPDWORD cbneeded, LPDWORD qcount);
Parameters
LPCTSTR server
Specifies the name of a server. If this parameter is null or empty,

then queues from the local server are enumerated.
DWORD level
Specifies the amount to information to be returned for each job.

Currently, only levels 1 and 2 are supported, which correspond to
the BATCH_QUEUE_INFO_1 (on page 81) and
BATCH_QUEUE_INFO_2 (on page 82) structures, respectively.
LPBYTE qbuff
Buffer space to store an array of BATCH_QUEUE_INFO

structures.
DWORD cbsize
LPDWORD cbneeded
Specifies the size of the returned information. If cbsize is too

small, ERROR_INSUFFICIENT_BUFFER is returned, and
cbneeded is set to the needed size.
LPDWORD qcount
Provides a pointer to contain the number of queues returned in the

qbuf.
Return Values
BATCH_ERROR_BAD_SERVER_NAME
The syntax of the server name was invalid.
ERROR_INVALID_LEVEL
Example Program
void main()
{
103
Batch Client API

char *
LPBYTE
LPCTSTR
DWORD
DWORD
DWORD
DWORD
DWORD
pTemp;
QBuff;
ServName;
Level;
CbSize;
ReturnVal;
Need;
Qcount;
cout << "STARTING THE EXECUTION OF BATCHENUMERATEQUEUE API "<< endl;

if (pTemp == NULL){
cout << "Unable to allocate the memory.\n Exiting"<<endl;
exit(0);
}
cout << " Enter the Server to Enumerate the Queues ";
cin >> pTemp;
ServName = (const char *) pTemp;
cout << " Enter the Level with Which to Enumerate the Jobs ";
cin >> Level;
ReturnVal = BatchEnumerateQueues(ServName,Level,NULL,0,&Need,&Qcount);
QBuff = (LPBYTE)LocalAlloc(0,Need);
if (QBuff == NULL){
cout << "Unable to allocate the memory.\n Exiting the program"<<endl;
delete [] pTemp;
exit(0);
}
CbSize = Need;
ReturnVal = BatchEnumerateQueues(ServName,Level,QBuff,CbSize,&Need,&Qcount);
// Now we have the Data(in QBuff) about the Queues from the server ServName which can
// be retrieved using an BATCH_JOB_INFO_2 or a BATCH_JOB_INFO_1 pointer variable
// which can be seen by seeing the BatchSetQueueInfo api example.
switch(ReturnVal)
{
case BATCH_ERROR_BAD_SERVER_NAME
:
cout << " The syntax of the server name was invalid. " << endl;
break;
:
break;
default:
cout << "SUCCESSFUL COMPLETION OF ENUMERATION"<<endl;
}
cout << "COMPLETED THE EXECUTION OF BATCHENUMERATEQUEUE API "<< endl;
delete [] pTemp;
LocalFree(QBuff);
}
BatchGetJobInfo
Description
Returns information about a particular job.
Structure
DWORD BatchGetJobInfo(LPCTSTR jobid, DWORD level, LPBYTE buff, DWORD cbsize,
LPDWORD cbneeded);
Parameters
LPCTSTR jobid
DWORD level
Specifies the amount to information to be returned for each

job. Currently, only levels 1 and 2 are supported, which
correspond to the BATCH_JOB_INFO_1 (on page 85) and
BATCH_JOB_INFO_2 (on page 86) structures, respectively.
LPBYTE buff
Buffer space to store a BATCH_JOB_INFO structure.
DWORD cbsize
LPDWORD cbneeded
Specifies the size of the returned information. If cbsize is too

Return Values
104
Batch Client API

ERROR_INVALID_LEVEL
Example Program
void main()
{
LPCTSTR JobId=NULL;
LPBYTE Buff;
char * pTemp=NULL;
DWORD
ReturnVal=0;
DWORD
Level;
DWORD
Need;
DWORD
CbSize;
cout << " STARTING THE EXECUTION OF BATCHGETJOBINFO API " << endl;
CbSize= BATCH_JOB_ID_SIZE + 4;
pTemp = new char[MAX_LENGTH];
if (pTemp ==NULL){
exit(0);
}
cout << " Enter the Job id for which to get the info ";
cin >> pTemp;
JobId = (const char *)pTemp;
cout << " Enter the Level of Extraction ( 1 or 2) ";
cin >> Level;
ReturnVal = BatchGetJobInfo ( JobId , Level , NULL , 0 , &Need);
Buff = (LPBYTE)LocalAlloc(0,Need);
if (Buff ==NULL){
delete [] pTemp;
exit(0);
}
CbSize= Need;
ReturnVal = BatchGetJobInfo ( JobId , Level , Buff , CbSize , &Need);
switch(ReturnVal)
{
case BATCH_ERROR_NO_SUCH_JOB
:
cout << "The system could not find the named job. : " << endl;
break;
:
cout << "The level parameter is not 1 or 2. " << endl;
break;
cout << "The jobid was null or the syntax was incorrect." << endl;
break;
default :
cout << "SUCCESSFUL IN GETTING THE JOB INFO"<< endl;
}
cout << " FINISHED THE EXECUTION OF BATCHGETJOBINFO API " << endl;
delete [] pTemp;
LocalFree(Buff);
}
BatchGetQueueInfo
Description
Gets information about the named queue.
Syntax
DWORD BatchGetQueueInfo(LPCTSTR queue, DWORD level, LPBYTE qbuff, DWORD cbsize,
LPDWORD cbneeded);
Parameters
LPCTSTR queue
Specifies the queue name.
DWORD level
Specifies the amount of information to be returned for each

job. Currently, only levels 1 and 2 are supported, which
correspond to the BATCH_QUEUE_INFO_1 (on page 81) and
105
Batch Client API

BATCH_QUEUE_INFO_2 (on page 82) structures,
respectively.
LPBYTE qbuff
Buffer space to store a BATCH_QUEUE_INFO structure.
DWORD cbsize
LPDWORD cbneeded
Indicates the size of the returned information. If cbsize is too

Return Values
The system could not find the named queue.
ERROR_INVALID_LEVEL
Example Program
void main()
{
char*
pTemp;
LPCTSTR QueName;
LPBYTE QBuff;
DWORD
ReturnVal;
DWORD
Level;
DWORD
CbSize;
DWORD
Need;
cout << " STARTING THE EXECUTION OF BATCHGETQUEUEINFO API "<< endl;
if (pTemp == NULL){
exit(0);
}
cout << " Please enter the name of the Queue ";
cin >> pTemp;
cout << " Enter the Level of Enumeration required ";
cin >> Level;
ReturnVal = BatchGetQueueInfo( QueName, Level, NULL, 0, &Need);
QBuff = (LPBYTE) LocalAlloc (0,Need);
if (QBuff == NULL){
delete [] pTemp;
exit(0);
}
CbSize = Need;
ReturnVal = BatchGetQueueInfo( QueName, Level, QBuff, CbSize, &Need);
switch(ReturnVal)
{
case BATCH_ERROR_NO_SUCH_QUEUE :
cout << " The system could not find the named queue. "<< endl;
break;
:
break;
:
break;
default:
cout << "SUCCESSFUL COMPLETION OF GETQUEUEINFO "<< endl;
}
cout << " COMPLETED THE EXECUTION OF BATCHGETQUEUEINFO API "<< endl;
delete [] pTemp;
LocalFree(QBuff);
}
106
Batch Client API
BatchGetServerInfo
Description
Returns information about the batch service on the named server.
Syntax
DWORD BatchGetServerInfo(LPCTSTR server, LPBYTE servinfobuf, DWORD cbsize,
LPDWORD cbneeded);
Parameters
LPCTSTR server
Specifies the server name. If this parameter is null or empty,

information about the local batch server is returned.
LPBYTE servinfobuf
Buffer space to store a BATCH_SERVER_INFO (on page 92)

structure.
DWORD cbsize
LPDWORD cbneeded
Indicates the size of the returned information. If cbsize is too

Return Values
The syntax of the server name was invalid.
Example Program
void main()
{
LPCTSTR ServName;
LPBYTE ServInfoBuff;
DWORD CbSize,Need,ReturnVal;
char * pTempName;
cout << "STARTING THE EXECUTION OF BATCHGETSERVERINFO API "<< endl;
if (pTempName ==NULL){
exit(0);
}
cout << " Enter the Name of the server for which info is required ";
cin >> pTempName;
ServName = (const char*)pTempName;
ReturnVal = BatchGetServerInfo(ServName , NULL , 0 ,&Need);
ServInfoBuff = (LPBYTE)LocalAlloc(0,Need);
if (ServInfoBuff ==NULL){
exit(0);
}
CbSize = Need;
ReturnVal = BatchGetServerInfo(ServName, ServInfoBuff,CbSize,&Need);
switch (ReturnVal)
{
:
cout << " The syntax of the server name was invalid. " << endl;
break;
default:
cout << "SUCCESSFUL COMPLETION OF GETTING SERVER INFORMATION "<< endl;
}
cout << "COMPLETED THE EXECUTION OF BATCHGETSERVERINFO API "<< endl;
LocalFree(ServInfoBuff);
}
107
Batch Client API
BatchJobHold
Description
Puts a hold on a batch job, preventing it from being executed until the hold is released. To apply
a BATCH_USER_HOLD to the job, the caller must own the job. To apply a
BATCH_MGR_HOLD, the caller must have operator privileges.
Syntax
DWORD BatchJobHold(LPCTSTR jobid, DWORD holdtype);
Parameters
LPCTSTR jobid
DWORD holdtype
Indicates the hold type, either BATCH_USER_HOLD or

BATCH_MGR_HOLD, or both.
Return Values
The system could not find the named

job.
The jobid was null or the syntax was

incorrect.
BATCH_ERROR_OWNER_ACCESS_DENIED
The user is trying to place a user hold on

the job, but does not own the job.
BATCH_ERROR_OPERATOR_ACCESS_DENIED The user is trying to place an operator

hold on the job, but does not have at
least operator privilege.
BATCH_ERROR_INVALID_HOLD
An invalid hold was specified.
The job is already running.
Example Program
void main()
{
char * pTemp;
LPCTSTR JobId;
DWORD HoldType,ReturnVal;
cout << " STARTING THE EXECUTION OF BATCHJOBHOLD API "<< endl;
if (pTemp == NULL){
exit(0);
}
cin >> pTemp;
cout << "Enter the Job Hold type wanted"
<< " 0 for BATCH_USER_HOLD 1 for BATCH_MGR_HOLD, 2 for both " << endl;
cin >> HoldType;
switch (HoldType)
{
case 0 :
// the hold type required is only Userhold
ReturnVal=BatchJobHold( JobId, BATCH_USER_HOLD);
break;
case 1:
// the hold type required is only ManagerHold
ReturnVal=BatchJobHold( JobId, BATCH_MGR_HOLD);
break;
case 2:
// the hold type required is both Userhold and MangerHold
ReturnVal=BatchJobHold( JobId, BATCH_USER_HOLD | BATCH_MGR_HOLD);
break;
108
Batch Client API

default:
cout << " THE HOLD TYPE IS UNKNOWN" << endl;
}
switch(ReturnVal)
{
:
cout << " The system could not find the named job. " << endl;
break;
cout << " The jobid was null or the syntax was incorrect. " << endl;
break;
case BATCH_ERROR_OWNER_ACCESS_DENIED
:
cout << " The user is trying to place an user hold on the job, but does not own the job." << endl;
break;
case BATCH_ERROR_OPERATOR_ACCESS_DENIED :
cout << " The user is trying to place an operator hold on the job, but does not have at least operator
privilege. " << endl;
break;
case BATCH_ERROR_INVALID_HOLD :
cout << " An invalid hold was specified. " << endl;
break;
:
cout << " The job is already running. " << endl;
break;
default:
cout << "SUCCESSFUL HOLD OF THE REQUESTED JOB " << endl;
}
cout << " FINISHED THE EXECUTION OF BATCHJOBHOLD API "<< endl;
delete [] pTemp;
}
BatchJobRelease
Description
Removes a user or manager hold on a job, freeing it for execution. To remove a
BATCH_USER_HOLD from the job, the caller must own the job. To remove a
BATCH_MGR_HOLD, the caller must have operator privileges.
Syntax
DWORD BatchJobRelease(LPCTSTR jobid, DWORD holdtype);
Parameters
LPCTSTR jobid
DWORD holdtype
Specifies the hold type, either BATCH_USER_HOLD or

BATCH_MGR_HOLD, or both.
Return Values
The jobid syntax was incorrect.
BATCH_ERROR_OWNER_OR_
OPERATOR_ACCESS_DENIED
The user is trying to release a user hold, but is

not the job owner and does not have at least
operator privilege.
An invalid hold type was specified.
Example Program
#include < iostream.h>
void main()
{
LPCTSTR JobId;
char * pTemp;
DWORD
HoldType;
DWORD
ReturnVal;
cout << " STARTED EXECUTION OF BATCHJOBRELEASE API" << endl;
if (pTemp == NULL){
109
Batch Client API

exit(0);
}
cin >> pTemp;
cout << endl << " Enter the Job Hold type to release"
<< " 0 for BATCH_USER_HOLD 1 for BATCH_MGR_HOLD, 2 for both" << endl;
cin >> HoldType;
switch (HoldType)
{
case 0 :
// the Jobs hold type is only Userhold
ReturnVal=BatchJobRelease( JobId, BATCH_USER_HOLD);
break;
case 1:
// the Jobs hold type is only ManagerHold
ReturnVal=BatchJobRelease( JobId, BATCH_MGR_HOLD);
break;
case 2:
// the Jobs hold type is both Userhold & ManagerHold
ReturnVal=BatchJobRelease( JobId, BATCH_USER_HOLD && BATCH_MGR_HOLD);
break;
default:
cout << " THE HOLD TYPE IS UNKNOWN" << endl;
}
switch( ReturnVal)
{
:
break;
case BATCH_ERROR_BAD_JOB_NAME
:
cout << " The jobid syntax was incorrect. " << endl;
break;
case BATCH_ERROR_OWNER_OR_OPERATOR_ACCESS_DENIED
:
cout << " The user is trying to release a user hold, but is not the job "
<<" owner and does not have at least operator privilege. " <<endl;
break;
case BATCH_ERROR_INVALID_HOLD
:
cout << " An invalid hold type was specified. " << endl;
break;
:
cout << " The job is already running. " << endl;
break;
default :
cout << " SUCCESSFUL COMPLETION OF RELEASE OF JOB"<< endl;
}
cout << " COMPLETED EXECUTION OF BATCHJOBRELEASE API" << endl;
delete [] pTemp;
}
BatchMoveJob
Description
Moves a batch job from one queue to another on the same server. The caller must own the job,
or have operator privileges. The caller must have submit access to the destination queue.
Syntax
DWORD BatchMoveJob(LPCTSTR jobid, LPCTSTR toqueue);
Parameters
LPCTSTR jobid
LPCTSTR toqueue
Specifies the queue to which the job will move. The queue must
exist on the same server as the job. A job cannot be moved
between servers. The value of toqueue must be a simple text string
and not the full remote queue specification.
Return Values
110

job.
The jobid syntax was incorrect.
Batch Client API


queue. The queue does not exist on
the same server as the job.
BATCH_ERROR_QUEUE_ACCESS_DENIED
The user does not have access to the

named queue.
BATCH_ERROR_QUEUE_NOT_ENABLED
The destination queue is not enabled,

and jobs may not be moved into it.
BATCH_ERROR_QUEUE_RUN_PRIORITY_EXCEE The job's run priority is higher than the

DED
queue's run priority.
BATCH_ERROR_OWNER_OR_OPERATOR_ACCE The user does not own the job, and

does not have operator privileges on
SS_DENIED
the system.
Example Program
void main()
{
DWORD
ReturnVal;
LPCTSTR JobDest;
LPCTSTR JobId;
char * pTemp =NULL;
char * pTempDest=NULL;
cout << " STARTED EXECUTION OF BATCHMOVEJOB API " << endl;
if (pTemp == NULL){
exit(0);
}
pTempDest = new char[MAX_LENGTH];
if (pTempDest == NULL){
delete [] pTemp;
exit(0);
}
cout << " Enter the Job id which needs to be moved ";
cin >> pTemp;
cout << " Enter the QueName to which the job should be moved ";
cin >> pTempDest;
JobDest = (const char *)pTempDest;
ReturnVal = BatchMoveJob( JobId , JobDest );
switch (ReturnVal)
{
:
break;
:
cout << " The jobid syntax was incorrect. " << endl;
break;
:
cout << " The system could not find the named queue."
<< The queue does not exist on the same server as the job. " << endl;
break;
case BATCH_ERROR_QUEUE_ACCESS_DENIED
:
cout << " The user does not have access to the named queue. " << endl;
break;
case BATCH_ERROR_QUEUE_NOT_ENABLED
:
cout << " The destination queue is not enabled, and jobs may not be moved into it. " << endl;
break;
case BATCH_ERROR_QUEUE_RUN_PRIORITY_EXCEEDED
:
cout << " The job's run priority is higher than the queue's run priority." << endl;
break;
:
cout << "The job is already running. " << endl;
break;
111
Batch Client API

case BATCH_ERROR_OWNER_OR_OPERATOR_ACCESS_DENIED :
cout << " The user does not own the job, and does not have operator privileges on the system. " <<
endl;
break;
default:
cout << "SUCCESSFUL MOVE OF THE JOB"<< endl;
}
cout << " COMPLETED EXECUTION OF BATCHMOVEJOB API " << endl;
delete [] pTemp;
delete [] pTempDest;
}
BatchPurgeQueue
Description
Removes all jobs from the named queue that are not in the RUNNING or TRANSITING state.
The caller must have operator privileges on the server.
Syntax
DWORD BatchPurgeQueue(LPCTSTR queuename);
Parameter
LPCTSTR queuename
Specifies the name of the queue to purge.
Return Values

valid.
BATCH_ERROR_OPERATOR_ACCESS_DENIED

privileges.
Example Program
void main()
{
char * pTemp;
LPCTSTR QueName;
DWORD
ReturnVal;
cout << " STARTING THE EXECUTION OF BATCHPURGEQUEUE API " << endl;
if (pTemp == NULL){
exit(0);
}
cout << " Enter the Queue to Purge ";
cin >> pTemp;
ReturnVal = BatchPurgeQueue(QueName);
switch(ReturnVal)
{
:
break;
:
break;
:
break;
default:
cout << "SUCCESSFUL COMPLETION OF PURGING THE QUEUE "<< endl;
}
cout << " COMPLETED THE EXECUTION OF BATCHPURGEQUEUE API " << endl;
delete [] pTemp;
}
112
Batch Client API
BatchServerShutdown
Description
Shuts down the batch service on the named server. The caller must have operator privileges on
the server.
Syntax
DWORD BatchServerShutdown(LPCTSTR server, DWORD graceperiod);
Parameters
LPCTSTR server
Specifies the server to shut down. If this parameter is null or

empty, the local server is shut down.
DWORD graceperiod
Specifies the amount of time in seconds to allow currently running

jobs to complete. No new jobs will be started during this period.
Return Values
ERROR_SUCCESS
Request successfully submitted. The

server may not shut down until after the
grace period.
The syntax of the server name was not

valid.
BATCH_ERROR_OPERATOR_ACCESS_DENIE The user does not have operator

D
privileges.
Example Program
void main()
{
char * pTemp;
LPCTSTR ServName;
DWORD
GracePeriod;
DWORD
ReturnVal;
cout << " STARTING THE EXECUTION OF BATCHSERVERSHUTDOWN API "<< endl;
if (pTemp ==NULL){
exit(0);
}
cout << " Enter the Name of the server to shutdown ";
cin >> pTemp;
ServName = (const char*)pTemp;
cout << " Enter the Graceperiod in which to shutdown the Server ";
cin >> GracePeriod;
ReturnVal = BatchServerShutdown(ServName,GracePeriod);
switch ( ReturnVal)
{
case ERROR_SUCCESS
:
cout << " Request successfully submitted. The server may not "
<< "shut down until after the grace period." << endl;
break;
:
cout << " The syntax of the server name was not valid." << endl;
break;
:
cout << " The user does not have operator privileges." << endl;
break;
default:
cout << "SUCCESSFUL COMPLETION OF SERVER SHUTDOWN"<< endl;
}
cout << " COMPLETED THE EXECUTION OF BATCHSERVERSHUTDOWN API "<< endl;
delete [] pTemp;
}
113
Batch Client API
BatchSetJobInfo
Description
Sets or modifies various job attributes. You can modify the following job properties:
Level
Properties
1. priority
2. name
2
1. priority
2. name
3. runpriority
4. restartable
5. job recurrence information
The other job attributes are ignored, and are not set. If a job attribute is missing or is not valid,
then it is not set, and the function returns success. The caller must own the job or have operator
privileges to use this function.
Syntax
DWORD BatchSetJobInfo(LPCTSTR jobid, DWORD level, LPBYTE jobinfo);
Parameters
LPCTSTR jobid
DWORD level
Specifies the amount of information to be returned for each job.

Currently, only levels 1 and 2 are supported, which correspond to the
BATCH_JOB_INFO_1 (on page 85) and BATCH_JOB_INFO_2 (on
page 86) structures, respectively.
LPBYTE jobinfo
Points to a buffer containing the job info structure. Note that some job
attributes cannot be set with this call.
Return Values
You cannot modify job attributes while the

job is running.
ERROR_INVALID_LEVEL
The value of the level parameter is not 1 or

2.
The jobid was null or the syntax was

incorrect.
BATCH_ERROR_OWNER_OR_OPERATOR_AC The caller neither owns the job nor has

CESS_DENIED
Example Program
void main()
{
LPBYTE Buff;
long
Priority;
LPCTSTR JobId;
114
Batch Client API

char * pTempName;
char * pTemp;
char * pName;
DWORD
Need;
DWORD
Level;
DWORD
CbSize;
DWORD
m_ReturnVal;
DWORD
RunPriority;
DWORD
Restartable;
if (pTemp == NULL){
exit(0);
}
pTempName = new char[MAX_LENGTH];
if (pTempName == NULL){
delete [] pTemp;
exit(0);
}
cout << "STARTING THE EXECUTION OF BATCHSETJOBINFO API"<<endl;
cout << " YOU CAN CHANGE only priority,name,runpriority,restartable properties"<< endl;
cin >> pTemp;
cin
cout << " Enter the Level of Extraction ( 1 or 2) ";

>> Level;
cout << " Enter the priority to set for the job " ;
cin >> Priority;
cout << " Enter the Runpriority to set for the job ";
cin >> RunPriority;
cout << " Enter whether to restart the job " ;
cin >> Restartable;
cout << " Enter the name to set for the job ";
cin >> pTempName;
pName = pTempName;
m_ReturnVal = BatchGetJobInfo ( JobId , Level , NULL , 0 , &Need);
Buff = (LPBYTE)LocalAlloc(0,Need);
if (Buff == NULL){
delete [] pTemp; delete []pTempName;
exit(0);
}
CbSize= Need;
m_ReturnVal = BatchGetJobInfo ( JobId , Level , Buff , CbSize , &Need);
if (Level==2)
{
BATCH_JOB_INFO_2 * Jinfo;
Jinfo = (BATCH_JOB_INFO_2 *)Buff;
Jinfo->priority = Priority;
Jinfo->runpriority = RunPriority;
Jinfo->restartable = Restartable;
Jinfo->name = pName;
m_ReturnVal = BatchSetJobInfo (JobId , Level, (LPBYTE)Jinfo);
}
else
if (Level == 1)
{
BATCH_JOB_INFO_1 * Jinfo;
Jinfo = (BATCH_JOB_INFO_1 *)Buff;
Jinfo->priority = Priority;
Jinfo->name = pName;
m_ReturnVal = BatchSetJobInfo (JobId , Level, (LPBYTE)Jinfo);
}
switch (m_ReturnVal)
{
:
cout << " You cannot modify job attributes while the job is running." << endl;
break;
:
cout << " The system could not find the named job." << endl;
break;
case ERROR_INVALID_LEVEL :
cout << " The value of the level parameter is not 1 or 2." << endl;
break;
:
cout << " The jobid was null or the syntax was incorrect. " << endl;
break;
case BATCH_ERROR_OWNER_OR_OPERATOR_ACCESS_DENIED
:
cout << " The caller neither owns the job nor has operator privileges. " << endl;
break;
115
Batch Client API

case ERROR_ACCESS_DENIED :
cout << " The user was not the job owner and did not have operator "
<<"privileges." <<endl;
break;
default:
cout << "SUCCESSFUL COMPLETION OF SETTING UP THE JOB INFO" << endl;
}
cout << "FINISHED THE EXECUTION OF BATCHSETJOBINFO API"<<endl;
delete [] pTemp;
LocalFree(Buff);
}
BatchSetQueueInfo
Description
Sets attributes of the named queue. The caller must have management privileges. The following
attributes of the queue can be set:
1. qpri
2. defaultpri
3. runprilimit
4. runlimit
5. sizelimit
6. description
7. pSD (security descriptor)
8. processor_affinity
9. v.batch.shell_list
10. v.batch.defaultshell
11. v.pipe.dest_list
Syntax
DWORD BatchSetQueueInfo(LPCTSTR queue, DWORD level, LPBYTE queueinfo);
Parameters
LPCTSTR queue
Specifies the name of the queue.
DWORD level
Specifies the amount to information to be returned for each queue.

Currently, only levels 1 and 2 are supported, which correspond to the
BATCH_QUEUE_INFO_1 (on page 81) and BATCH_QUEUE_INFO_2
(on page 82) structures, respectively.
LPBYTE queueinfo
Points to a buffer containing the queue info structure.
Return Values

queue.
ERROR_INVALID_LEVEL
A level other than 1 or 2 was specified.

valid.
BATCH_ERROR_MANAGER_ACCESS_DENIED The user does not have manager

privileges.
BATCH_ERROR_BAD_SHELLNAME
116
The requested default shell is not in the

queue's shell list.
Batch Client API
Example Program
void main()
{
LPCTSTR QueName;
long
DefPri;
LPBYTE QBuff;
char * pTemp;
char * pTempDesc;
char * pTempShell;
LPTSTR Desc;
LPTSTR * ShellList;
LPTSTR * DestList;
DWORD
ReturnVal;
DWORD
Level;
DWORD
CbSize;
DWORD
Need;
DWORD
Number;
DWORD
QuePri;
DWORD
RunPriLim;
DWORD
RunLim;
DWORD
SizLim;
DWORD
ProcAffin;
cout << " STARTING THE EXECUTION OF BATCHSETQUEUEINFO API "<< endl;
cout << endl << " You can set only the following attributes "<<endl
<< " quepriority defaultpriority runprioritylimit runlimit "<<endl
<< " sizelimit
description
pSD(security descriptor) "<<endl
<< " processor_affinity v.batch.shell_list
v.batch.defaultshell "<<endl
<< " v.pipe.dest_list " << endl;
if (pTemp ==NULL){
exit(0);
}
pTempShell = new char[MAX_LENGTH];
if (pTempShell == NULL){
delete [] pTemp;
exit(0);
}
pTempDesc = new char[MAX_LENGTH];
if (pTempDesc == NULL){
delete [] pTemp;
delete [] pTempShell;
exit(0);
}
cout << " Please enter the name of the Queue ";
cin >> pTemp;
cout << " Enter the Level of Enumeration required ";
cin >> Level;
cout << " Enter the Description value ";
cin >> pTempDesc;
Desc = (char *)pTempDesc;
cout << " Enter the QueuPriority value ";
cin >> QuePri;
if (Level == 2)
{
cout << " Enter the DefaultPriority value ";
cin >> DefPri;
cout << " Enter the RunPriorityLimit value ";
cin >> RunPriLim;
cout << " Enter the RunLimit value ";
cin >> RunLim;
cout << " Enter the sizeLimit value ";
cin >> SizLim;
cout << " Enter the ProcessorAffinity value ";
cin
>> ProcAffin;
}
ReturnVal = BatchGetQueueInfo( QueName, Level, NULL, 0, &Need);
QBuff = (LPBYTE) LocalAlloc (0,Need);
if (QBuff == NULL){
delete [] pTemp;
delete [] pTempDesc;
exit(0);
}
CbSize = Need;
117
Batch Client API

ReturnVal = BatchGetQueueInfo( QueName, Level, QBuff, CbSize, &Need);
if (Level == 2)
{
BATCH_QUEUE_INFO_2 * Jinfo;
Jinfo = (BATCH_QUEUE_INFO_2 *)QBuff;
Jinfo->description = Desc;
Jinfo->defaultpri = DefPri;
Jinfo->qpri = QuePri;
Jinfo->runprilimit = RunPriLim;
Jinfo->runlimit=RunLim;
Jinfo->sizelimit= SizLim;
Jinfo->processor_affinity = ProcAffin;
switch(Jinfo->qtype)
{
case BATCH_QUEUE_TYPE_BATCH:
cout << " Enter the number of valid shells for this Batch queue ";
cin >> Number;
if (Number >0)
{
ShellList = new LPTSTR[Number];
char * TestShell;
TestShell = new char[MAX_LENGTH];
if (QBuff == NULL){
delete [] pTemp;
LocalFree(QBuff);
exit(0);
}
for ( DWORD j = 0; j< Number; ++j)
{
cout << " Please enter the ShellName and its absolute path "<<endl
<< " [ as example BATCH=D:\\NTABATCH\\BIN\\BATCH.EXE ]\n "<< endl;
cin >> TestShell;
ShellList[j] = new char[strlen(TestShell)+1];
if (ShellList[j] == NULL){
delete [] pTemp;
LocalFree(QBuff);
delete [] ShellList;
exit(0);
}
strcpy(ShellList[j],TestShell);
}
cout << " \nEnter the Default ShellName to be used "<<endl
<< " for the above example the ShellName is BATCH \n"<< endl;
cin >> pTempShell;
Jinfo->v.batch.defaultshell = pTempShell;
Jinfo->v.batch.shell_list = ShellList;
}
break;
case BATCH_QUEUE_TYPE_PIPE :
cout << " Enter the number of destinations for this Pipe queue";
cin >> Number;
if (Number >0){
DestList = new LPTSTR[Number];
if (DestList == NULL){
cout << "unable to allocate the memory.\n Exiting program"<<endl;
delete [] pTemp;
LocalFree(QBuff);
exit(0);
}
char * TestDest;
TestDest = new char[MAX_LENGTH];
if (TestDest == NULL){
delete [] pTemp;
LocalFree(QBuff);
delete [] DestList;
exit(0);
}
for ( DWORD j = 0; j< Number; ++j)
{
cout << " Please enter the destination queue ";
cin >> TestDest;
DestList[j] = new char[strlen(TestDest)+1];
if (DestList[j] == NULL){
delete [] pTemp;
LocalFree(QBuff);
118
Batch Client API

delete [] DestList;
delete [] TestDest;
exit(0);
}
strcpy(DestList[j],TestDest);
}
Jinfo->v.pipe.dest_list = DestList;
}
break;
}
ReturnVal = BatchSetQueueInfo( QueName , Level , (LPBYTE) Jinfo);
}
else
if (Level == 1)
{
BATCH_QUEUE_INFO_1 * Jinfo;
Jinfo = (BATCH_QUEUE_INFO_1 *)QBuff;
Jinfo->description = Desc;
Jinfo->qpri = QuePri;
ReturnVal = BatchSetQueueInfo( QueName , Level , (LPBYTE) Jinfo);
}
switch(ReturnVal)
{
:
cout << " The system could not find the named queue. " << endl;
break;
:
cout << " A level other than 1 or 2 was specified. " << endl;
break;
break;
:
break;
default:
cout << "SUCCESSFUL COMPLETION OF BATCHQUEUSETINFO INFORMATION"<< endl;
}
cout << " COMPLETED THE EXECUTION OF BATCHSETQUEUEINFO API "<< endl;
delete [] pTemp;
LocalFree(QBuff);
}
BatchSetServerInfo
Description
Sets attributes for the batch service on the named server. Invalid or missing values are ignored.
The caller must have management access to the server. The following attributes can be set:
1. debuglevel
2. defaultqueue
3. pSD
Syntax
DWORD BatchSetServerInfo(LPCTSTR server, BATCH_SERVER_INFO servinfo);
Parameters
LPCTSTR server
Specifies the server. If this parameter is NULL or

empty, the local server is used.
BATCH_SERVER_INFO servinfo
A BATch_Server_Info (on page 92) structure

containing the server information to set.
Return Values
The syntax of the server name was

not valid.
119
Batch Client API

BATCH_ERROR_MANAGER_ACCESS_DENIED
The user does not have manager

privileges.
Example Program
void main()
{
LPTSTR
DefQue;
LPCTSTR ServName;
LPBYTE
ServBuff;
char *
pTempName;
char *
pTempQue;
DWORD
ReturnVal;
DWORD
CbSize;
DWORD
Need;
DWORD
DebugLevel;
BATCH_SERVER_INFO * ServInfo;
cout << "STARTED EXECUTION OF BATCHGETSERVERINFO API" << endl;
cout << " The Caller Must have Manager privileges and can set any of "<< endl
<< " the following attributes only. debuglevel defaultqueue pSD "<< endl;
pTempName = new char [ MAX_LENGTH];
if (pTempName == NULL) {
exit(0);
}
pTempQue = new char[MAX_LENGTH];
if ( pTempQue == NULL){
exit(0);
}
cout << " Enter the name of the server for which to set the info ";
cin >> pTempName;
ServName = (const char *)pTempName;
ReturnVal = BatchGetServerInfo(ServName, NULL,0,&Need);
ServBuff = (LPBYTE) LocalAlloc(0,Need);
if (ServBuff == NULL) {
delete [] pTempName; delete [] pTempQue;
exit(0);
}
CbSize = Need;
ReturnVal = BatchGetServerInfo(ServName,ServBuff,CbSize,&Need);
cout << " Enter the Default Queue to set for the server ";
cin >> pTempQue;
DefQue = (char *)pTempQue;
cout << " Enter the Debug level for Log file to set for the Server ";
cin >> DebugLevel;
ServInfo = (BATCH_SERVER_INFO *)ServBuff;
ServInfo->debuglevel = DebugLevel;
ServInfo->defaultqueue = DefQue;
ReturnVal = BatchSetServerInfo(ServName,*ServInfo);
switch(ReturnVal)
{
case BATCH_ERROR_BAD_SERVER_NAME :
cout << " The syntax of the server name was not valid. " << endl;
break;
:
break;
default:
cout << "SUCCESSFUL COMPLETION OF BATCHSETSERVER INFORMATION"<< endl;
}
cout << " COMPLETED EXECUTION OF BATCHGETSERVERINFO API " << endl;
delete [] pTempQue;
LocalFree(ServBuff );
}
120
Batch Client API
BatchStartQueue
Description
Sets the outflow state of the named queue to "STARTED". The caller must have operator
Syntax
DWORD BatchStartQueue(LPCTSTR queuename);
Parameter
LPCTSTR queuename
Specifies the name of the queue to start.
Return Values

valid.

privileges.
Example Program
void main()
{
char * pTemp;
LPCTSTR QueName;
DWORD
ReturnVal;
cout << " STARTING THE EXECUTION OF BATCHSTARTQUEUE API"<< endl;
pTemp= new char[ MAX_LENGTH];
if (pTemp == NULL){
exit(0);
}
cout << " Enter the name of the QUEUE to start"<< endl;
cin >> pTemp;
ReturnVal = BatchStartQueue(QueName);
switch(ReturnVal)
{
:
cout << "The queue does not exist. " << endl;
break;
break;
:
break;
default:
cout << " SUCCESSFUL COMPLETION OF START QUEUE "<< endl;
}
cout << " COMPLETED THE EXECUTION OF BATCHSTARTQUEUE API"<< endl;
delete [] pTemp;
}
121
Batch Client API
BatchStopQueue
Description
Sets the outflow state of the named queue to "STOPPED". If jobs are running in the queue, the
state is set to "STOPPING" until the jobs complete, and then it is set to "STOPPED". The caller
must have operator privileges on the server.
Syntax
DWORD BatchStopQueue(LPCTSTR queuename);
Parameter
LPCTSTR queuename
Specifies the name of the queue to stop.
Return Values
The syntax of the queue name was

not valid.

privileges.
Example Program
void main()
{
char * pTemp;
LPCTSTR QueName;
DWORD
ReturnVal;
cout << " STARTING THE EXECUTION OF BATCHSTOPQUEUE API"<< endl;
pTemp = new char[ MAX_LENGTH];
if (pTemp == NULL){
exit(0);
}
cout << " Enter the name of the QUEUE to start"<< endl;
cin >> pTemp;
ReturnVal = BatchStopQueue(QueName);
switch(ReturnVal)
{
:
break;
break;
:
break;
default:
cout << "SUCCESSFUL COMPLETION OF STOPPING THE QUEUE " << endl;
}
cout << " COMPLETED THE EXECUTION OF BATCHSTOPQUEUE API"<< endl;
delete [] pTemp;
}
122
Batch Client API
QueueBatchJob
Submits a batch job to a batch queue. The caller must have submit access to the named queue.
The job is described in the BATCH_JOB_INFO_2 (on page 86) structure. Default values for
this structure have been defined, see Default Values for QueueBatchJob (on page 125).
Syntax
DWORD QueueBatchJob(LPCTSTR queue, BATCH_JOB_INFO_2 jobinfo, LPBYTE jobid,
DWORD cbsize, LPDWORD cbneeded);
Parameters
LPCTSTR queue
Specifies the full queue name to which the job is submitted.
BATCH_JOB_INFO_2 jobinfo
Points to a structure identifying the attributes of the job.
LPBYTE jobid
Points to a buffer that will receive the job identifier.
DWORD cbsize
Specifies the size of the jobid buffer. This value must greater
than or equal to BATCH_JOB_ID_SIZE.
LPDWORD cbneeded
Indicates the size of the returned information. If cbsize is

too small, ERROR_INSUFFICIENT_BUFFER is returned,
and cbneeded is set to the required size.
Return Values
BATCH_ERROR_BAD_JOB_INFO
The jobinfo structure is not complete or

contains bad information.

queue.
The specified queue was not enabled.
BATCH_ERROR_QUEUE_ACCESS_DENIED
The user is not allowed to submit jobs to

this queue.
The syntax of the queue name was

invalid.
BATCH_ERROR_NO_ACCOUNT_MAPPING
The system was unable to map the user.
BATCH_ERROR_BAD_SCRIPTNAME
Either the script does not exist, or the

system was unable to open it for read
access.
BATCH_ERROR_BAD_JOB_PRIORITY
The job priority was invalid.
BATCH_ERROR_BAD_RUN_PRIORITY
The run priority was invalid.
A hold other than a user hold was

specified.
BATCH_ERROR_BAD_JOB_FLAG
An invalid job flag was specified.
BATCH_ERROR_QUEUE_RUN_
PRIORITY_EXCEEDED
The run priority of the job is greater than

the run priority of the queue.
123
Batch Client API

Example Program
void main()
{
LPBYTE JobId;
DWORD ReturnVal;
DWORD Need;
BATCH_JOB_INFO_2 NewJob;
LPCTSTR QueName;
char * pTempQue=NULL;
char * pTempScript=NULL;
cout << " STARTING THE EXECUTION OF QUEUEBATCHJOB API "<< endl;
pTempQue = new char[MAX_LENGTH];
if (pTempQue == NULL){
exit(0);
}
pTempScript = new char[MAX_LENGTH];
if (pTempScript == NULL){
cout << "unable to allocate the memory.\n Exiting program"<<endl;
delete [] pTempQue;
exit(0);
}
cout << " Enter the name of queue to which the job should be submitted ";
cin >> pTempQue;
QueName = (const char *)pTempQue;
JobId = (LPBYTE)LocalAlloc(0,BATCH_JOB_ID_SIZE);
if (JobId == NULL ) {
delete [] pTempScript;
delete [] pTempQue;
exit(0);
}
ZeroMemory(&NewJob, sizeof NewJob);
NewJob.script=(char *)pTempScript;
cout<<endl << "please enter the standard output filename " ;
cin >> strOut;
NewJob.Stdout=(LPTSTR)strOut;
cout<<endl << "please enter the standard error filename " ;
cin >> strErr;
NewJob.Stderr=(LPTSTR)strErr;
ReturnVal = QueueBatchJob(QueName,NewJob,JobId,BATCH_JOB_ID_SIZE,&Need);
switch(ReturnVal)
{
case BATCH_ERROR_BAD_JOB_INFO
:
cout << " The jobinfo structure is not complete or contains bad information." << endl;
break;
:
cout << " The system could not find the named queue. " << endl;
break;
case BATCH_ERROR_QUEUE_NOT_ENABLED
:
cout << " The specified queue was not enabled. " << endl;
break;
case BATCH_ERROR_QUEUE_ACCESS_DENIED
:
cout << " The user is not allowed to submit jobs to this queue. " << endl;
break;
:
cout << " The syntax of the queue name was invalid." << endl;
break;
case BATCH_ERROR_NO_ACCOUNT_MAPPING
:
cout << " The system was unable to map the user. " << endl;
break;
case BATCH_ERROR_BAD_SCRIPTNAME
:
cout << " Either the script does not exist, or the system was unable to open it for read access. "<< endl;
break;
case BATCH_ERROR_BAD_JOB_PRIORITY
:
cout << " The job priority was invalid. " << endl;
break;
124
case
:
cout << " The run priority was invalid." << endl;
break;
case
:
cout << " A hold other than a user hold was specified. " << endl;
Batch Client API

break;
case BATCH_ERROR_BAD_JOB_FLAG :
cout << " An invalid job flag was specified. " << endl;
break;
case BATCH_ERROR_QUEUE_RUN_PRIORITY_EXCEEDED
:
cout << " The job run priority is greater than the queue run priority." << endl;
break;
default:
cout << "SUCCESSFUL COMPLETION OF QUEUEBATCHJOB "<< endl;
}
cout << " COMPLETED THE EXECUTION OF QUEUEBATCHJOB API "<< endl;
delete [] pTempQue;
delete [] pTempScript;
LocalFree(JobId);
}
Default Values for QueueBatchJob

qname
jobid
owner
name
If this value is NULL, it is set to the basename of the script (or STDIN if the
script has no pathname).
priority
This value must be set. The default is BATCH_JOB_PRI_DEFAULT.
runpriority
The default is NORMAL_PRIORITY_CLASS.
restartable
The default is TRUE
starttime
If this value is not set, the job is started immediately
size
state
holds
The default is no holds. Jobs may be submitted with a user hold.
script
If this value is NULL, the script is read from STDIN.
reserved2
stderr
The default is jobname.e, where jobname is the filename of the script.
stdout
The default is jobname.o, where jobname is the filename of the script.
system
user
shell
If this value is NULL, the system uses the default shell set in the queue.
envp
This value has no default, and may be set to NULL. (See comments below
for more information.)
logmsg
account
infiles
outfiles
origin
125
Batch Client API

mailaddress
If this value is NULL, it is set to \\localhost.
flags
The default is BATCH_JOB_FLAGS_MAIL_ABORT.
filesizelimit
If this value is 0, it defaults to the size limit for the queue.
recurrence
Set to zero by default. Unused until a recurring job flag is set in the flags
field.
The envp member has some special constraints. The following environment variables will not be
put into the job environment, even if they are included in the envp structure:
HOMEDRIVE
HOMEPATH
HOMESHARE
Path
ComSpec
MAIL
TZ
USERNAME
QSUB_HOME
QSUB_PATH
QSUB_SHELL
QSUB_MAIL
QSUB_TZ
QSUB_USER
QSUB_REQID
QSUB_REQNAME
QSUB_HOST
Certain environment variables will be taken from the submitting user's environment (NOT the
envp member), renamed, and put into the job execution environment:
User environment variable
Job environment variable
ComSpec
QSUB_SHELL
HOMEDRIVE, HOMEDIR
QSUB_HOME
MAIL
QSUB_MAIL
Path
QSUB_PATH
TZ
QSUB_TZ
USERNAME
QSUB_USER
If an environment variable does not exist in the user's environment, then the corresponding
variable is not exported into the job execution environment.
At job execution time, the following environment variables are exported into the job environment:
126
QSUB_HOST
the name of the computer where the queue to which the job was
submitted resides
QSUB_REQID
the jobid
QSUB_REQNAME
the job name
Batch Client API
API Error Codes

If a batch API call is successfully completed, it returns ERROR_SUCCESS (0). Otherwise it
returns either a batch-specific error code or one of the Win32 error codes.
Batch Specific Error Conditions (on page 127)
Win32 Error Codes (on page 129)
Required Calling Privileges (on page 129)
Batch Specific Error Conditions

The following is a list of Batch-service specific error conditions, with a short description of their
cause. These batch-specific error codes are defined in the header file for the Batch client API.
BATCH_ERROR_ALREADY_EXISTS
You cannot create a queue or job that already

exists.
BATCH_ERROR_BAD_HEADER
There is a problem communicating with batch

server.
BATCH_ERROR_BAD_JOB_FLAG
An invalid job flag was specified.
BATCH_ERROR_BAD_JOB_INFO
The specified job structure contained bad

information.
The syntax of the job name was not valid.
BATCH_ERROR_BAD_JOB_PRIORITY
The job priority was invalid.
BATCH_ERROR_BAD_MAGIC
A non-batch program is attempting to use the

batch communications protocol.
BATCH_ERROR_BAD_QUEUE_INFO
The specified queue structure contained bad

information.
The syntax of the queue name was invalid.
BATCH_ERROR_BAD_QUEUE_TYPE
The specified queue type was not valid.
The run priority was invalid.
BATCH_ERROR_BAD_SCRIPTNAME
Either the script does not exist, or the system

was unable to open it for read access.
BATCH_ERROR_BAD_SERVER_INFO
The specified server structure contained bad

information.
The syntax of the server name was not valid.
BATCH_ERROR_BAD_SHELLNAME
The requested default shell is not in the queue's

shell list.
A hold other than a user hold was specified.
You cannot perform this operation on a running

job.
BATCH_ERROR_JOB_NOT_RUNNING
An attempt was made to abort a job that is not

running.
127
Batch Client API

BATCH_ERROR_LIMIT_EXCEEDED
A job was rejected because it exceeded one of

the limitations defined by a batch queue.
BATCH_ERROR_MANAGER_ACCESS_DEN The user does not have manager privileges.

IED
BATCH_ERROR_MEMORY
The batch server is out of memory, or the API

function could not allocate needed memory.
BATCH_ERROR_NO_ACCOUNT_MAPPING The system was unable to map the user.

The specified jobid does not exist.
The specified queue does not exist.
BATCH_ERROR_NOT_SUPPORTED
The batch server does not support this operation.
BATCH_ERROR_OPERATOR_ACCESS_DE The user does not have operator privileges.

NIED
BATCH_ERROR_OWNER_ACCESS_DENIE The user does not own the job.
D
BATCH_ERROR_OWNER_OR_OPERATOR The user neither owns the job nor has operator
_ACCESS_DENIED
privileges.
BATCH_ERROR_PROTOCOL
There is a problem communicating with the batch

service.
BATCH_ERROR_QUEUE_ACCESS_DENIE
D
The user is not allowed to submit jobs to this

queue.
BATCH_ERROR_QUEUE_IS_ACTIVE
An attempt was made to delete an enabled

queue.
An attempt was made to queue a job to a

disabled queue.
BATCH_ERROR_QUEUE_NOT_EMPTY
An attempt was made to delete a queue with jobs

in it.
BATCH_ERROR_QUEUE_RUN_PRIORITY_ The run priority of the job is greater than the run
EXCEEDED
priority of the queue.
128
BATCH_ERROR_SERVER_DOWN
The specified batch server is not running.
BATCH_ERROR_UNEXPECTED
A batch-specific error occurred that could not be

handled.
BATCH_ERROR_UNKNOWN_PKT
The batch server does not recognize the

operation requested.
Batch Client API
Win32 Error Codes

A batch API call may also return any valid Win32 error code. Unless otherwise specified, each
API call can return the following error codes:
BATCH_ERROR_SERVER_DOWN
BATCH_ERROR_BAD_MAGIC
BATCH_ERROR_PROTOCOL
BATCH_ERROR_BAD_HEADER
BATCH_ERROR_UNEXPECTED
BATCH_ERROR_MEMORY
ERROR_INSUFFICIENT_BUFFER
ERROR_INVALID_PARAMETER
ERROR_ACCESS_DENIED
Required Calling Privileges

The following table lists the API calls and the batch privileges needed to use them. If the calling
user does not have at least the privileges marked below then an error will be returned.
API call
No privileges
BatchAbortJob
job owner
operator
BatchAbortQueue
BatchCreateQueue
BatchDeleteJob
BatchDeleteQueue
BatchDisableQueue
BatchEnableQueue
BatchEnumerateJobs
BatchEnumerateQueues
BatchGetJobInfo
BatchGetQueueInfo
BatchGetServerInfo
BatchJobHold
BatchJobMove
BatchJobRelease
BatchPurgeQueue
BatchServerShutdown
BatchSetJobInfo
BatchSetQueueInfo
manager
X
X
129
Batch Client API

API call
No privileges
job owner
operator
BatchSetServerInfo
130
BatchStartQueue
BatchStopQueue
QueueBatchJob
manager
Command Line Interface
SECTION 6

The command line utilities provide a text interface to the Batch Service. The command line
interface allows you to perform the following tasks:
In This Section
Name Syntax .............................................................................. 131
Submitting Jobs .......................................................................... 135
Deleting or Aborting Batch Jobs .................................................. 138
Obtaining Job and Queue Status ................................................ 139
Managing Batch Services ........................................................... 140
Name Syntax
The batch service determines which batch provider to use for operations based on the syntax of
names. Servers, queues, job-ids, user names, group names, and file names may all be remote.
The following table shows the remote items and their syntax for the various batch providers:
Item
Local syntax
Remote Windows syntax
server
\\LocalNodeName
\\host
queue
queue
\\host\queue
job-id
seqno.host
\\host\job-id
user
user
DOMAIN\user
HOST\user
group
group
DOMAIN\group
HOST\group
file
filename
\\host\filename
Queue
Specifies the local or remote queue name. A set of valid characters has been chosen for queue
names. The character set consists of all alphanumeric (both upper and lower case) and
punctuation characters, with the following exceptions:
The punctuation characters @ \ ( ) = and , are invalid. These characters already have
The punctuation characters - and / are invalid for the first character of a queue or shell
name. In most cases, the command line utilities expect these characters to signal the start of
an option.
Specify the queue name according to the following syntax:
131

Local syntax
Remote Windows Syntax
queue
\\host\queue
Dest-name
Specifies the local or remote destination name. Destinations can be a local or remote queue,
according to the following syntax:
Local syntax
queue
\\host\queue
Group
Specifies the name of the local or remote group, according to the following syntax:
Local syntax
group
HOST\group
DOMAIN\group
Server
Specifies the name of the server, according to the following syntax:
Local syntax
\\LocalNodeName
\\host
User
Specifies the name of the local or remote user, according to the following syntax:
Local syntax
user
DOMAIN\user
HOST\user
Shell-name
Specifies the simple name of the shell. If the specified shell is located on a removable media, a
dialog will prompt you to insert the media. Batch Services provides a set of valid characters for
shell names. The character set consists of all alphanumeric (both upper and lower case) and
punctuation characters, with the following exceptions:
The punctuation characters @ \ ( ) = and , are invalid. These characters already have
132
The punctuation characters - and / are invalid for the first character of a queue or shell
name. In most cases, the command line utilities expect these characters to signal the start of
an option.
Runlimit
Defines the maximum number of requests allowed to run in a particular queue at any given time.
The default runlimit is 1.
Job-id
Specifies the local or remote job-id, according to the following syntax:
Local syntax
seqno.host
\\host\job-id
Priority-value
Specifies the scheduling priority of the request. The priority is used for scheduling the order of
job execution within the queue. The priority value must be in the range of [-1024..1023].
Nice-value
Specifies the initial nice value (also known as the run time or execution priority) of the request.
Nice-value can be within the range of [-20..20]. It can also be one of the following alphanumeric
descriptors:
Descriptor
Numeric Equivalent
IDLE
20
NORMAL
HIGH
10
REALTIME
-20
A REALTIME process preempts all other processes, including the operating system.
Intergraph recommends that you avoid using the REALTIME priority.
Debug Level
Specifies the debug level. A value of 0 turns off debug information, while non-zero value enables
debugging. Increasing values indicate that more information is to be displayed.
Debug Level
Logging Type
No Logging
Server Logging
Level 1 plus:
Meaning
Provides information about the current state of

the server and changes in its configuration.
133
Queue Logging
Provides information about the creation and

deletion of queues, and about any changes in
queue states or attributes.
Job Logging
Provides information about job submission and

job status.
Level 2 plus:
Job Error Logging
Provides information that is useful for

understanding why a job is failing.
Server Debugging Debug auditing types may aid in diagnosing

Queue Debugging low-level problems with the batch service. This
information may not be useful to users or
Job Debugging
operators.
4
Level 3 plus:
Pipe Debugging
Debug auditing types may aid in diagnosing
Packet Debugging low-level problems with the batch service. This
information may not be useful to users or
Other Debugging
operators.
Shell-path
Specifies the full pathname of the executable, according to the following syntax:
Local syntax
shell-path
\\host\\share\path*
*This specification works if the user who will run the job has access to the specified share.
date-time parameter
The syntax that is accepted for the date-time parameter is flexible. Unspecified date and time
values default to the current date and time. A date can be specified as a month and a day
(current year assumed).
Examples of valid date-time specifications are:
"01-Jan-2012 12am"
"Tuesday, 23:00:00"
"11pm tues."
"tomorrow 23"
The year can also be explicitly specified. It is also possible to specify the date as a weekday
name (for example, "Tues"), or as one of the strings "today" or "tomorrow." Weekday and month
names can be abbreviated by any three-character (or longer) prefix to the actual name. An
optional period can follow an abbreviated month or day name.
The time of day can be specified using a 24-hour clock or "am" and "pm" specifications. When
"am" or "pm" is not specified, a twenty-four hour clock is assumed. The time of day specification
is interpreted using the precise "am" or "pm" definitions. "12am" refers to the 24-hour clock time
of 0:00:00; "12m" refers to noon; and "12pm" refers to 24:00:00. Alternatively, the phrases
"midnight" and "noon" are accepted as time of day specifications, where "midnight" refers to
24:00:00.
134

The time is based on the local time zone. Daylight saving time is inferred when appropriate.
All alphabetic comparisons are not case-sensitive. Both "WeD" and "weD" refer to Wednesday.
Submitting Jobs
qsub: An Overview
The qsub utility allows you to submit jobs for batch processing. The qsub utility accepts as
arguments a shell script to be executed, a list of environment variables, a list of files to copy
before and after executing the job, and various options controlling job execution.
If the job submission is successful, the qsub will return a unique job identification string, or job
ID. The job ID may be used to perform further operations on that job. If the job submission is
unsuccessful, qsub returns an error message indicating the problem.
Synopsis
qsub [flags...] ["script-file[<TAB>script-args]"]
Qsub Interface (on page 135)
qsub Interface
The qsub utility accepts as an argument the file name of a shell script to execute. If no such
argument is given, the utility reads from stdin until an end of file is encountered, and uses this
input as the shell script. By default, the job name is the name of the shell script. If the shell script
is read from stdin, STDIN is the default job name.
The name of a script should not contain any characters that have special meaning to the
shell associated with the queue.
The qsub utility returns a unique job-identification string (job-id). You can use the job-ID to track
the job.
The return value indicates the success or failure of the submission. If qsub is invoked without
the -z option, qsub returns a message informing you whether or not the job submission was
successful.
If an option requires an argument, you must specify the argument when using the option. For
example, if you specify qsub -j but do not specify y|n, any options following -j will cause an
error. The qsub utility accepts the following options:
-A account -- Defines an account string to use. The account can be an arbitrary string of
unlimited length.
-a time -- Does not run the batch request until the specified date-time parameter (on page 134).
If a date-time specification is composed of two or more words, the date-time specification must
be in double quotes as in: "-a July, 4, 2026 12:31".
-C directive_prefix -- Defines the string of characters used to identify qsub options that appear
on the first line of a shell script. The default is the value of the environment variable
POSIX2_PBS_DPREFIX. If this variable is not defined, then the character string "#@$" is be the
default.
-e file -- Saves stderr into file. A remote file name may be specified, as described in Name
Syntax (on page 131). If a local file is specified without a full pathname, the current working
directory is used. The default stderr file name is "jobname.e." This name may be truncated due
to file system limitations. If the filename for stderr is invalid, the file is placed into the current
user's home directory on the execution computer.
-eo -- Writes stderr to stdout.
135

-h -- Submits the job with a user hold in place. The job will not run until the hold is released. The
hold can be released using either qmgr or the Batch Manager user interface.
-j y|n -- Specifies whether or not to join (write) stderr to stdout. The default is not to join stderr to
stdout.
-k keep_list -- Defines which files to retain on the execution computer. keep_list is a string which
can contain one of the following:
n -- Do not keep any files. This is the default.
eo -- Keep both stderr and stdout.
e -- Same as -ke (described below). This option has no effect if the "-eo" flag is used, or if an
explicit computer name has been given with the "-e" option.
o -- Same as -ko (described below). This option has no effect if an explicit computer name
has been given with the "-o" option.
-ke -- Retains the stderr file on the execution computer, in the directory in which the job was
executed. This option has no effect if the "-eo" flag is used, or if an explicit computer name has
been given with the "-e" option.
-ko -- Retains the stdout file on the execution computer, in the directory in which the job was
executed.
-ln priority -- Sets the execution priority (on page 160). The default run time priority is set by the
queue. A valid priority is a number in the range -20 to 20, or one of the following priority names
(corresponding numerical values are provided):
priority name
valid ranges
will be run at
IDLE
10 ...20
20
NORMAL
0...9
HIGH
-1...-10
-10
REALTIME
-11...-20
-20
If a job is submitted with a run priority that does not match the run priority of the queue to
which it is submitted, the submission fails and qsub will return an error.
-M mail_list -- Defines a list of addresses to which mail is sent, where mail_list is a list of mail
addresses, separated by semi-colons. Supported mail addresses are SMTP format(user@host)
and messages via the event log (\\host). If no mailing address is specified, the default mail
address is the Universal Naming Convention (UNC) name of the local host (\\local_host).
Because of Windows's built-in security, messages will be placed in the event log of the batch
server where the job executed.
-m mailoptions -- Defines when or if mail should be sent about the submitted job. Mailoptions
may include any of the following:
b -- Sends mail when the job begins (same as -mb).
e -- Sends mail when the job ends (same as -me).
a -- Sends mail if the job is aborted (same as -ma). This is the default.
n -- Sends no mail
-mb -- Sends mail when the job begins (same as -m b).
-me -- Sends mail when the job ends (same as -m e).
136

-mu mailaddress -- Specifies the user or users to whom mail will be sent. Supported mail
addresses are SMTP format and messages via the event log. If no mailing address is specified,
the default mail address is \\local_host. Messages that are sent using the default address can be
viewed in the local host's event log.
-N name -- Names the batch job. The job name is not limited in length. The default job name is
the basename of the submitted shell script, or STDIN if the script is read from the command line.
This option is the same as "-r name."
-nr -- Specifies not to restart the job. By default, jobs are restartable.
-o file -- Writes stdout to the specified file. A remote file name may be specified as described in
Name Syntax (on page 131). If a local file is specified without a full pathname, the current
working directory is used. The default stdout file name is "jobname.o" (the name of the job). This
name may be truncated due to file system limitations. If the filename for stdout is invalid, the file
is placed into the current user's home directory on the execution computer.
-O descriptor -- Specifies reoccurrence of a job. The descriptor takes the form of
fFFiIImMMwWWyYY, where "f" is a flag and the value for FF is a hexadecimal number and can
have the value 00 (hourly), 02 (daily), 04 (weekly), 28 (specific monthly), 30 (specific yearly), 48
(determined monthly), and 50 (determined yearly). "i" is the interval value. "m" is the monthly
interval. "w" is the weekly interval and is Hexadecimal. It contains either the day of the week
mask, or the day of the month value. The "y" value is the month of the year in decimal. -O
f01i01m00w3ey00 would cause the job to reoccur every hour on Monday through Friday. (see
reoccurrence table below)
-p priority -- Specifies the scheduling priority (on page 162) for the job. The default scheduling
priority is set by the batch queue to which the job is submitted. The scheduling priority must be
in the range of -1024 to 1023.
-q queue -- Specifies the queue to which the job is submitted. Queue may take one of the
following forms:
A simple queue name which submits the job to the specified queue on the local server
A remote queue name that submits the job to the specified queue on the remote server. A
remote queue may be specified as described in Name Syntax (on page 131).
If -q is not specified, the job is submitted to the default queue on the local batch server.
-r name -- Names the batch job. The default name is the filename of the script file. This option is
the same as "-N name."
-re -- Writes the stderr file directly instead of spooling (on page 163) it. The -re flag forces the
stderr file to be sent to the destination directory as output is generated during execution. This
option is only available when the execution computer is the local computer.
-ro -- Writes the stdout file directly instead of spooling it. The -ro flag forces the stdout file to be
sent to the destination directory as the output is generated during execution. This option is only
available when the execution computer is the local computer.
-s shell -- Specifies the name of the command interpreter to use. If the specified shell is on a
removable media, a dialog will prompt you to insert the media.
-si destfile=sourcefile -- Copies sourcefile to destfile before the job is executed. Destfile specifies
a pathname on the execution computer. Sourcefile may be a remote file as described in Name
Syntax (on page 131). See File Staging (on page 15) for more information.
-so destfile=sourcefile -- Moves sourcefile to destfile after job execution. Destfile may be a
remote file as described in Name Syntax. Sourcefile specifies a pathname on the execution
computer. See File Staging (on page 15) for more information.
-V -- Exports all current environment variables with the job. This option is the same as "-x."
-v var_list -- Exports the named environment variables with the job. The varlist is a comma
separated list of environment variables of the form name[=value]. The value is optional. If no
137

value is specified, it will be taken from the current environment. In the case of conflicting
environment variable names, values specified with -v take precedence over those imported with
-x or -V. Values on the command line take precedence over those specified by embedded
options in the script.
-x -- Exports all current environment variables with the job. This option is the same as "-V."
-z -- Suppresses warning and error messages
Examples:
qsub -q \\gene\myqueue -O f01i01m00w3ey00 "c:\users\default\myscript.bat<tab>/help will
cause the script file "myscript.bat" to execute every hour starting at the current time on Monday
through Friday. The "<tab>" represents the tab character, and is used to separate arguments
from the script name.
Deleting or Aborting Batch Jobs

qdel: An Overview
The qdel utility allows you to delete queued jobs or abort running jobs. It takes as arguments a
list of unique job identification strings (returned from qstat or qsub) to delete or kill. The qdel
utility deletes the job if it is not running. The qdel utility aborts running jobs only if the -k option is
used.
The qdel utility returns a message indicating its success or failure. In the event of a failure, qdel
also provides a message indicating why the operation failed.
You must be the job owner, an operator, or a manager to delete or abort a job.
Synopsis
Windows syntax: qdel [-k] [\\host\]request-id
Qdel Interface (on page 138)
qdel Interface
The qdel utility accepts as arguments a list of job identifiers representing jobs to delete or kill. A
job identifier may contain a server name in the form \\server\job-id. The identifier instructs qdel
to direct the delete job request to the specified host.
If the -k option is not given, and the job is running, qdel informs you that the job is running and
does not delete it. The return value indicates the success or failure of the delete request. A
message is also printed for each job, informing you if it was deleted.
The qdel utility accepts the following options:
138
Option
Purpose
-k
Kills the job, even if it is running.
-u user
This option is ignored by the Windows qdel utility.
Obtaining Job and Queue Status

qstat: An Overview
The qstat utility is the primary means of obtaining information about batch jobs and queues. It
takes as arguments a list of batch queues as well as options indicating how much information is
to be displayed. If successful, qstat displays the requested information. If unsuccessful, qstat
displays an error message.
Synopsis
Windows syntax:
qstat [-abflmpr] [-u username] [-x] [\\host\][queue]...]
Qstat Interface (on page 139)
qstat Interface
The qstat utility accepts as argument a list of queues. You may reference queue names and job
identifiers on remote servers. The qstat utility also accepts a hostname, and displays all of the
queues for that host.
The qstat utility displays information about each specified queue, including each job. If you
invoke qstat with no arguments, the utility displays all batch and pipe queues on the local server.
By default, qstat displays both queue and job information in short format.
The return value for qstat indicates the success or failure of the qstat request.
The qstat utility accepts the following options:
Option
Purpose
-b
Restricts the display to batch queues.
-p
Restricts the display to pipe queues.
-a
Displays the status of all jobs, even if you do not own them.
-r
Recursively displays all destinations, if the queue is a pipe queue.
-u username
Displays jobs owned by username.
139
Managing Batch Services

qmgr: An Overview
The qmgr utility is an interactive, command line utility for managing batch jobs and queues. It
also allows you to manage the batch server. The qmgr utility takes as input a series of
commands specifying batch management operations. It performs each operation in sequence,
and returns a message indicating the success or failure of the operation. If the operation was a
request for information, then qmgr displays the information in a readable format. The qmgr utility
cannot be used to submit jobs.
Synopsis
qmgr
Qmgr Interface (on page 140)
qmgr Interface
The qmgr utility accepts no arguments. Instead, it accepts a series of commands that it
processes interactively. The utility also accepts input from stdin if no console exists. Most of the
commands' arguments can be local or remote. The syntax for the arguments is described in
Name Syntax (on page 131). Exceptions are noted in the command descriptions.
The qmgr utility returns a message to the user after each line of input indicating the success or
failure of the command. The return value will not be set when qmgr exits.
The qmgr utility provides the following commands:
Abort queue (on page 141)
Add destination (on page 141)
Add groups (on page 141)
Add managers (on page 141)
Add shell-name (see "Add shell_name" on page 142)
Add users (on page 142)
Create pipe-queue (see "Create pipe_queue" on page 142)
Create batch-queue (see "Create batch_queue" on page 142)
Delete destination (on page 142)
Delete groups (on page 143)
Delete managers (on page 143)
Delete queue (on page 143)
Delete request (on page 143)
Delete shell-name (see "Delete shell_name" on page 143)
Delete users (on page 144)
Disable queue (on page 144)
Enable queue (on page 144)
Exit (on page 144)
Help (on page 144)
Hold (on page 144)
Modify request (on page 144)
Move request (on page 145)
Purge queue (on page 145)
Quit (on page 145)
Release (on page 145)
Restart queue (on page 145)
Set debug (on page 145)
140

Set default batch request priority (on page 146)
Set default batch request queue (see "Set default batch_request queue" on page 146)
Set default shell (on page 146)
Set destination (on page 146)
Set managers (on page 147)
Set nice-value limit (see "Set nice_value_limit" on page 147)
Set no default batch request queue (on page 147)
Set no default shell (on page 147)
Set no access (see "Set no_access" on page 147)
Set per-process permfile limit (see "Set per_process permfile_limit" on page 147)
Set priority (on page 148)
Set runlimit (on page 148)
Set shell-name (see "Set shell_name" on page 148)
Set unrestricted access (see "Set unrestricted_access" on page 148)
Show all (on page 148)
Show limits supported (on page 148)
Show long queue (on page 148)
Show managers (on page 149)
Show parameters (on page 149)
Show queue (on page 149)
Shutdown (on page 149)
Start queue (on page 149)
Stop queue (on page 149)
Unhold (on page 149)
Abort queue
abort queue queue
Kills all of the running jobs associated with a queue. Jobs are not restarted.
Operator or manager privileges are required to use this command.
Add destination
add destination = dest-name queue
add destination = (dest-name [,dest-name...]) queue
Adds a single destination or several destinations to the existing destination set for a pipe queue.
Manager privileges are required to use this command.
Add groups
add groups = group queue
add groups = (group [,group...]) queue
Adds an entire group (or several groups) to the existing list of those users allowed to access a
queue. Note that you may not add a group when queue access is unrestricted.
Add managers
add managers user:{m,o} ... [server]
add managers group:{m,o} ... [server]
141

Adds manager and/or operator privileges to the specified user(s) or group(s). Managers have all
privileges that operators have, but operators have only a subset of the privileges that managers
have.
You can assign managers and operators on the same line. You can also add multiple users,
groups, or a combination of users and groups, at the same time.
You must use one of the following suffixes at the end of each account:
:m
Indicates that the specified account will be granted Batch manager privileges.
:o
Indicates that the account will be granted Batch operator privileges.
Add shell_name
add shell_name = shell-name:shell-path queue (on page 131)
add shell_name = (shell-name:shell-path [,shell-name:shell-path..]) queue
Adds a shell (or several shells) to the list of shells available for use on a queue.
Add users
add users = user queue
add users = (user [,user...]) queue
Adds a user (or several users) to the list of users allowed to access the named queue. You may
not add a user when queue access is unrestricted.
Create pipe_queue
create pipe_queue queue priority = queue-priority [ destination =dest-name ] [ run_limit =
run-limit ]
create pipe_queue queue priority = queue-priority [destination = (dest-name [,dest-name...])]
[run_limit = run-limit]
Defines a new Batch pipe queue. A set of destination queues can be assigned to the pipe queue
using the destination= parameter. The queue is created in a disabled and stopped state, and
must be explicitly enabled and started. If a pipe queue has no destinations, it will act as though it
is stopped. This will occur even if the outflow state of the queue is "STARTED."
Create batch_queue
create batch_queue queue priority =queue-priority [run_limit = runlimit]
Defines a new Batch request queue. The queue is created in a disabled and stopped state, and
must be explicitly enabled and started.
Delete destination
delete destination = dest-name queue
142

delete destination = ( dest-name [,dest-name...] ) queue
Deletes a destination (or several destinations) from the destination set of a pipe queue. Any
requests in the pipe queue that are currently being transferred to the specified destination are
allowed to successfully complete the transfer process. If a pipe queue has no destinations, it will
act as though it is stopped. This will occur even if the outflow state of the queue is "STARTED."
Delete groups
delete groups = group queue
delete groups = (group [,group...]) queue
Deletes an entire group (or several groups) from the list of those allowed access to the named
queue.
Delete managers
delete managers user:{m,o} ... [server]
delete managers group:{m,o} ... [server]
Removes manager and/or operator privileges from the specified user(s) or group(s). The
Administrators group cannot be removed.
You can delete managers and operators on the same line. You can also delete multiple users,
groups, or a combination of users and groups, at the same time.
:m
Removes manager privileges from the specified user(s) or group(s).
:o
Removes operator privileges from the specified user(s) or group(s).
Delete queue
delete queue queue
Deletes the named queue. To delete a queue, no requests can be present in the queue and the
queue must be disabled and stopped.
Delete request
delete request job-id...
Deletes a request from a queue. If the specified request is running, sending the request signal
terminates it. If the request is not running, it is simply removed from its containing queue and
discarded.
Jobs may be deleted by the job owner or by a user with operator or manager privileges.
Delete shell_name
delete shell_name = shell-name[:shell-path] queue
delete shell_name = (shell-name[:shell-path] [,shell-name[:shell-path]...]) queue
143

Deletes the listed shell(s) being used for batch requests.
Delete users
delete users = user queue
delete users = (user [,user...]) queue
Deletes a user (or several users) from the list of those allowed to access the named queue.
Disable queue
disable queue queue
Prevents any more requests from being placed in the named queue.
Enable queue
enable queue queue
Enables the specified queue. This means that the queue will be able to accept new requests.
Exit
exit
Exits from the qmgr program. The qmgr program is also exited if an end-of-file is encountered
from the standard input file.
Help
help [command]
Displays a page of text about the specified qmgr command or subcommand.
Hold
hold job-id ...
Puts a queued request into the operator hold state.
Modify request
modify request job-id [ priority = priority-value ] [ nice_limit = nice-value ]
Modifies the parameters of a request that is already in its final destination queue, but has not
started yet. Jobs may be modified by the job owner or by an user with operator or manager
privileges.
144
Move request
move request job-id queue
Moves the specified request from the queue it is currently in to the specified queue. The source
queue (the queue that the job currently resides in) and the destination queue must both be on
the same computer.
Jobs may be moved by the job owner or by an user with operator or manager privileges.
Purge queue
purge queue queue
Causes all requests that are not running to be purged (deleted) from the named queue.
Quit
quit
Exits from the qmgr program. The qmgr program is also exited if an end-of-file is encountered in
the standard input file.
Release
release job-id ...
Releases the specified request from any held or waiting states, and places the request into the
queued state ready to run. The release command removes a request from a user and/or
operator hold, if possible.
If the user owns the job, then any user hold will be released. If the user has operator or manager
privileges, then all holds on the job will be released.
Restart queue
restart queue queue
Kills all running jobs in the named queue, and then immediately reschedules the requests for
execution. Only jobs marked as "restartable" will be rescheduled.
Set debug
set debug debug-level [server]
Allows a Batch manager to enable or disable Batch debugging (or auditing) output. Manager
This command accepts the following values:
Debug Level
Logging Type
No Logging
Server Logging
Meaning
Provides information about the current state of the

server and changes in its configuration.
145

2
Level 1 plus:
Queue Logging
Provides information about the creation and deletion

of queues, and about any changes in queue states
or attributes.
Job Logging
Provides information about job submission and job

status.
Levels 2 plus:
Job Error Logging
Provides information that is useful for understanding

why a job is failing.
Server Debugging
Queue Debugging
Job Debugging

low-level problems with the batch service. This
Level 3 plus:
Pipe Debugging
Packet Debugging
Other Debugging

low-level problems with the batch service. This
Set default batch request priority

set default batch_request priority priority queue
Sets the default intra-queue priority for batch requests for the specified queue. The intra-queue
priority determines the relative ordering of requests within queues on the local or remote
computer. This command does not determine the execution-time priority of requests.
Set default batch_request queue

set default batch_request queue queue [server]
Sets the default queue for the specified server. If no server name is specified, this command
sets the default queue for the local computer. The default queue is used when a job is submitted
without an associated queue.
Set default shell

set default shell shell-name queue
Sets the name of the default shell for a batch queue.
Set destination
set destination = dest-name queue
set destination = (dest-name [,dest-name...]) queue
146

Sets the destination for the specified pipe queue to the specified destination (or several
destinations). All previous destinations are discarded.
Set managers
set managers user:{m,o} ... [server]
set managers group:{m,o} ... [server]
Removes manager and operator privileges from existing Batch managers and operators (except
the Administrators group). These privileges are then reassigned to the specified user(s) or
group(s).
:m
Indicates that the specified account will be granted Batch manager privileges.
:o
Indicates that the account will be granted Batch operator privileges.
Set nice_value_limit
set nice_value_limit = nice-value queue
Sets the default per-process run time priority for the specified queue.
Set no default batch request queue

set no_default batch_request queue [server]
Removes the default queue for the specified server. If no server is specified, this command
removes the default queue for the local host.
Set no default shell

set no_default shell queue
Removes the default shell for the specified queue.
Set no_access
set no_access queue
Deletes all groups and users from the access list for the specified queue.
Set per_process permfile_limit

set per_process permfile_limit = (permfile-limit) queue
Sets the default per-process file size limit for any batch request placed in the named batch
queue. The file size limit is used only by Intergraph NQS.
147
Set priority
set priority = queue-priority queue
Changes the priority of a queue, where priority is in the range [0-64]. This command is used only
by Intergraph NQS.
Set runlimit
set run_limit = run-limit queue
Changes the run-limit of a batch or pipe queue.
Set shell_name
set shell_name =shell-name:shell-path queue
set shell_name = (shell-name:shell-path [,shell-name:shell-path...]) queue
Removes any shells from the named queue's list and replaces them with the specified list of
shells.
Set unrestricted_access
set unrestricted_access queue
Grants all users access to the named queue.
Show all
show all [server]
Displays general status information on all of the Batch limits supported, managers, queues, and
the general operating parameters for the specified Batch server. If no server is specified, then
information about the local serer is shown.
Show limits supported

show limits_supported
Displays the set of request and process limits controlled by the host operating system. Each of
the limits shown by this command can be set for individual batch queues from within qmgr.
Show long queue

show long queue [ queue [ user ] ]
Displays status information about the specified Batch queues in a long format. If no queue name
is specified, then status information is displayed for all local Batch queues. If a queue name is
specified, then specific status information for the named queue is displayed. If a user name is
specified, then the requests shown will be limited to those belonging to that user.
148
Show managers
show managers [server]
Displays a list of the users that have either Operator or Manager privileges on the specified
server. If no server is specified, then the information shown applies to the local server.
Show parameters
show parameters [server]
Displays the current values for the general Batch operating parameters on the specified server.
Show queue
show queue [queue [ user ] ]
Displays status information about the specified Batch queue in a short format. If no queue name
is specified, then status information is displayed for all local Batch queues. If a queue name is
specified, then specific status information for the named queue is displayed. If a user name is
specified, then the requests shown will be limited to those belonging to that user.
Shutdown
shutdown [ grace-period ]
Shuts down the Batch Queuing System on the local supporting host. For each queue that is
running, the equivalent of the Abort Queue command is performed, except that all requests
terminated as a result of the shutdown command are requeued for later execution.
If grace-period is not specified, then a default value of twenty (20) seconds is used.
The Batch service on Windows cannot be restarted using qmgr. To restart batch service, either
restart the system, or restart the batch server (BATSERV.EXE) through the Control Panel icon
in Program Manager.
Start queue
start queue queue
Starts the named queue. Any requests in the named queue become eligible for execution.
Stop queue
stop queue queue
Stops the named queue. Any requests in the queue that are currently running are allowed to
complete execution. All other requests eligible for execution in the queue are prevented from
running.
Unhold
unhold job-id ...
149

Removes the specified request from the operator hold state. If the request also has a user hold,
the request will remain in the hold state. Otherwise, the request will return to the queued or
waiting state.
150
setpasswd.exe Utility
APPENDIX A
A command line utility, ..\Win32app\Ingr\BATCH\bin\setpasswd.exe, is available to change
Account Mapping passwords on remote computers (provided write access to remote registry is
available). Using this utility, an adiministrator can change the passwords on all client computers
from a single computer.
The command line syntax is:
setpasswd.exe servername domain account [password]
Where:
servername is the name of the remote computer
domain is the user domain name
account is the user name
password is the user name's password. The password as a command line argument is optional.
If you do not specify the password, the utility will prompt you to type and then confirm the
password. The password is invisible while typing it this way.
Error messages:
"ERROR: Access is denied." - No write permissions to remote registry.
"ERROR: The network path was not found." - A remote computer with the supplied
servername cannot be found.
"ERROR: No mapping between account names and security IDs was done. - Incorrect
domain and/or account names supplied.
"ERROR: The system cannot find the file specified." - No account mapping exists for the
supplied user.
"ERROR:Overlapped I/O operation is in progress" - When you see this error, check all the
above cases.
If the remote computer is running Windows Vista, members of the Administrators group
do not get privileges to the registry by default. Contact Intergraph support for assistance.
151
152
APPENDIX B
Troubleshooting
This section provides tips and information for answering common questions and solving
common problems with Batch Services.
Basics of Batch Services
Understanding batch queues and pipe queues (on page 154)
Understanding queue states and job states (on page 154)
Job Status Notification
Receiving mail notification (on page 155)
Obtaining information about failures (on page 155)
File Staging
Sending and Receiving Files (on page 155)
Security
Submitting jobs to remote nodes (on page 156)
Resource Usage
Controlling queue usage (on page 156)
Aborting running jobs (on page 156)
More Problem Solving Ideas
Setting up a shell (on page 157)
Power failures (on page 157)
SMTP mail (on page 157)
In This Appendix
Customer Support....................................................................... 153
Basics of Batch Services............................................................. 154
Job Status Notification ................................................................ 155
File Staging ................................................................................ 155
Security ...................................................................................... 156
Resource Usage ......................................................................... 156
Frequently Asked Questions ....................................................... 157
Customer Support
Intergraph Process, Power & Marine provides complimentary software support for 30 days. At
the end of the 30-day complimentary support period, you should take advantage of Intergraph
Process, Power & Marine's purchasable support plans. For more information or to purchase a
support plan, call 1-800-766-7701 (in the United States), or contact your local Intergraph
subsidiary or distributor (at international locations).
See the following topics for more information on the various avenues of customer support:
1. Telephone Support (on page 154)
2. Our Web Site (on page 154)
153
Troubleshooting
Telephone Support
If you experience problems with your software, or have questions about the information in this
document, you can contact Intergraph Process and Building Solutions for help.
1. In the United States, call 1-800-766-7701.
2. At international locations, contact the Intergraph subsidiary or distributor from which you
purchased your Intergraph system or software.
Have the following information readily available when you call:
1. Your name and telephone number.
2. The product's name.
3. A brief description of the question or problem.
Information on telephone support is also available on our web site: http://www.intergraph.com.
Web Site
You can find Intergraph on the Internet at http://www.intergraph.com.
Intergraph Directory
If you are outside the United States, contact the subsidiary or distributor from which you
purchased your software.
General Information
1-256-730-2000
Internet
http://www.intergraph.com
Mailing Address
Intergraph Corporation
Process, Power & Marine
300 Intergraph Way
Madison, Alabama 35758 USA
Basics of Batch Services

Understanding batch queues and pipe queues
Question: I do not know the difference between a pipe queue and batch queue.
Answer:
Batch queues execute jobs directly on the computer on which they reside. Pipe
queues route jobs from the computer where they exist to other pipe or batch queues.
Question: I do not know when to use a pipe queue.
Answer:
A good time to use pipe queues is when you want to use any of several
execution locations, any of which may or may not be available. You can configure a pipe queue
to have multiple destinations (pipe or batch queues to route to). When a job is submitted to the
pipe queue, it will be routed to the first available destination.
Understanding queue states and job states

Question: I do not understand the difference between enabled/disabled and started/stopped.
Answer:
Enabled and disabled are "inflow" states. They control whether or not the queue
will accept new jobs. Started and stopped are "outflow" states. They control whether the queue
154
Troubleshooting
will run the jobs that are already queued. When queues are created, they are both disabled and
stopped. You must enable and start a queue before you can submit and run jobs in it.
Question: I do not understand the job states "WAITING," "TRANSITING," "QUEUED," or
"RECURRING."
Answer:
QUEUED: A job that has been accepted into the queue, but is not being
processed by the queue yet.
TRANSITING: A job that is being routed from a pipe queue to a destination queue.
WAITING: A job that has been accepted into the queue, but is waiting on an event
before it can be executed. The most common reason for a job to be in the WAITING state is that
a future start time for the job was specified.
RECURRING: Jobs scheduled to run more than once are called recurring jobs. When a
recurring job is not running, it stays in the RECURRING state until its next occurrence.
Job Status Notification

Receiving mail notification
Problem: I checked the "Mail notification when Job Completion" box and gave my address, but
did not receive mail in MS-Mail.
Solution: At this time, Batch Services supports direct mail notification only to SMTP mail
addresses, not to MS-Mail addresses. The job completion information will be placed in the
application event log of the execution computer.
You can access the event log of the execution computer by starting the Event Viewer
application, selecting the Select Computer item from the Log menu, and entering the name of
the computer where the job executed. See Configuring SMTP Mail (on page 45) for more
information about setting up job status notification.
Obtaining information about failures

Problem: Something went wrong when running an Batch Services job.
Solution: By default, a message describing the failure will be placed in the Event Log on the
computer where the job was executed. If you would like further notification upon job start, job
completion, or job failure, use the Notification tab in the Job Submit dialog box to enter the
addresses to which you want to send job notification information.
To view the event log, open the Administrative Tools program group of Program Manager and
run the Event Viewer. To view the event log of the batch server where the job executed, select
the Select Computer item from the Log menu. Enter the name of the batch server where the job
executed. Messages from Batch Services will be in the Application section of the Event Log.
File Staging
Sending and Receiving Files
Problem: Some of my jobs produce extra output files that I would like to have delivered to my
computer after the job has run. Some jobs also require data files as input.
Solution: You can use the File Staging (see "Job Submit: File Staging" on page 63) menu to tell
the batch server which files you would like to have delivered back to your computer (or to the
location of your choice) after your job completes and which files you would like to have delivered
155
Troubleshooting
to the execution computer for use by your job. When staging files (see "File Staging" on page
15) between Batch servers, be sure to use full path names for source and destination.
Problem: I submitted my job via Batch Manager and did not specify where the job's standard
error and standard output files should be placed. I can't find them now.
Solution: By default the error and output files from your job will be returned to your computer in
the submission directory. If your job produces additional files which you would also like to have
returned, use the File Staging Property Page (see "Job Submit: File Staging" on page 63) in the
Job Submit dialog to tell Batch Services which output files you are interested in. See File
Staging (on page 15) for more information.
When using the Batch Manger, the submission directory starts off as the product
directory. You may change this by modifying the current directory in the Batch Manager's icon. If
you browse for your script, the submission directory becomes the directory where the script file
is located. This is where output and error files will go by default.
If you look in the appropriate directory and do not find the error and output files from your job,
there may be a problem with the account mapping between the submission computer and the
execution computer. Check to be sure the account your job is running as on the remote
computer is able to write files on your local computer. If this situation occurs, the output files will
be on the execution computer in the directory where the job executed.
Security
Submitting jobs to remote nodes
Problem: Whenever I submit a batch job to a remote node, it is deleted by Batch Services and I
get some message about impersonation tokens.
Solution: This could mean that the password for the user you are impersonating on the
execution computer was entered incorrectly into the Server Account Mapping (see "Server
Properties: Security Tab" on page 75) dialog, that the password has expired, or that the user
does not have "log on locally" access. You can check the "log on locally" access via the User
Manager
Resource Usage
Controlling queue usage
Problem: I have a backlog of scripts in my queues and extra processing power.
Solution: Check the run-limit on your queues. The run-limit is the maximum number of running
(or transferring) jobs. The default (and minimum) value is 1. The maximum value is 60.
Problem: I do not understand what the queue processor affinity settings are used for.
Solution: If the computer on which the queue resides is a multiprocessor computer, the
selections tell the queue which processors should run jobs for the queue. These controls are
useful only on a multi-processor computer. If the queue for which you select processors is a
single processor computer, the processor check-boxes will be cleared and setting them will have
no effect.
Aborting running jobs

Problem: When I abort my running batch job, its sub-processes are not aborted.
156
Troubleshooting
Solution: The Windows operating system does not support the concept of a process group.
Therefore, aborting a running job only terminates the script that was submitted. Any processes
started by the script will not be killed.
Frequently Asked Questions

Setting up a shell
Question: I set up a shell named "perl" with location "c:\win32app\ingr\perl\bin". Why don't my
jobs execute?
Answer: The "Location" field must contain the full path to the shell, including the shell itself.
Your location should have been something like "c:\win32app\ingr\perl\bin\perl.exe".
Power failures
Question: A power failure occurred. What happened to my job?
Answer:
If your job is in a queue at the time of the power failure, it will be submitted when
the power returns. If your job is executing when the power failure occurs, it will be re-queued
and restarted when the computer comes back up.
SMTP mail
Question: What port is used?
Answer: Batch Services uses TCP port 25 to establish a connection with the SMTP host.
Question: What identity is used to connect to the email server?
Answer: No account is used to establish connection, but mail is delivered to user@hostname as
selected from the Address Book.
Question: What security measures are in place to prevent abuse of this feature (namely
SPAM)?
Answer: Security should be performed on the SMTP server side.
157
Troubleshooting
158
Glossary
A
account mapping
The process of determining the account name to use when running jobs. Batch Services
requires an account name and password to use when running jobs. To perform account
mapping, the server tries to match the job owner with an account mapping entry.
B
batch job
A batch job is the full set of instructions to Batch Services to perform a given task or set of tasks
on a computer system. The job itself is identified with a script, or a file that can be interpreted by
some program to perform a set of instructions. An example of a script is a .BAT file, which is
interpreted by the CMD.EXE program.
A unique job identifier or jobid identifies each job. No two jobs will have the same jobid. See also
job and shell.
batch queue
A batch queue accepts requests to execute scripts or commands from the keyboard as if the
user submitting the request were logged in to the system. Jobs are executed in a batch queue.
The resulting output returns to the directory from which the original requestor submitted the job.
You can request the output to remain on the executing node or return to a remote node.
Batch queues can also have a list of shells associated with them, allowing an administrator to
configure a queue to run certain types of scripts. For example, a batch queue may be set up to
run scripts for the Perl program. See also queue.
batch server
A Windows service that processes batch jobs, and maintains queue and job information. A
Batch Server is also the system on which Batch Services runs. The Intergraph Batch Server is a
system service that may be controlled using the Services icon on the Control Panel.
D
default queue
The queue to which a job is assigned when a user does not specify a queue.
default shell
The shell that is used to run a job submitted to a queue when a user does not specify a shell for
that job.
159
Glossary
disabled
A queue state in which the queue will not accept new jobs.
E
enabled
A queue state in which the queue will accept new jobs.
execution host
The computer where a batch job is run.
execution priority
The run time priority indicates the priority of a job when it is run. This value is also known as the
"nice value" in the qmgr interface. Valid execution priority values are:
IDLE
NORMAL
HIGH
REALTIME
H
hold
A delay in running a job submitted to a queue. A held job will not run until the hold is released, or
the job is deleted from the queue.
A user hold may be placed on a job submitted by that user when the job is submitted. A user
hold can be released either by the submitting user, or by a user with operator or manager
A user with operator or manager privileges may place an operator hold on a job, after the job is
submitted but before it runs. Only a user with operator or manager privileges can release an
operator hold.
run while the hold is in place. See also privilege.
I
inflow state
The state of a queue with regard to accepting jobs. See also queue state, enable, disable.
160
Glossary
J
job
A set of instructions needed to perform a given task or set of tasks on a computer system. See
also batch job and shell.
job identifier (job ID)

A unique alphanumeric string that identifies a job. A batch job ID is in the form jobid.orighost,
where jobid is a sequentially assigned number up to 5 digits in length, and orighost is the name
of the system from which the batch job originated.
When a job is successfully submitted, it is assigned a unique job-id. The job-id can be used to
reference the job. No two jobs will have the same job-id.
M
manager
See privilege.
O
operator
See privilege.
outflow state
The state of a queue with regard to processing jobs. See also queue state, started, stopped.
P
per-process file size limit
The file size limit indicates the maximum total file size used by a request. This value is not used
in Windows.
pipe queue
A pipe queue routes requests to another queue. Pipe queues can accept either a batch request,
or a request from another pipe queue. A pipe queue receives the request and sends it to the first
available queue in its destination list that will accept the request. The destination list may contain
any queue type. Pipe queues are normally used to create a connection to a remote batch
queue.
privilege
An operational permission level assigned to every Batch Services user. Non-privileged users
can submit jobs to queues to which they have been granted access; operators can issue
commands that directly affect queue management; and managers can control all aspects of
Batch Service operation.
161
Glossary
Q
queue
A queue is a waiting line in which job requests reside until they are processed. A queue can
control the number of jobs submitted to it, the number of simultaneous jobs, and the execution
priority of those jobs. A queue can also restrict the users and groups that have access to it. The
batch system supports batch queue and pipe queue.
queue state
A queue has two states: the inflow state and the outflow state.
Inflow State - The inflow state is either enabled or disabled. An enabled queue will accept new
jobs that are submitted or transferred to it; a disabled queue will not.
Outflow State - The outflow state is either stopped, started, or stopping. A stopped queue will
not run the jobs it contains. A queue must be started in order to run jobs.
Example
An "enabled/stopped queue" is a queue that will accept jobs but not run them.
See also enabled, disabled, started, stopped.
queue view
The view in Batch Manager that shows information on the jobs in a queue.
R
recurring jobs
Jobs scheduled to run more than once at a regular interval. Use the Job Submit\Scheduling tab
in Batch Manager to submit recurring jobs. Hourly, daily, weekly, monthly, and yearly intervals
are available.
S
scheduling priority
The scheduling priority, or "intra-queue priority," is used for scheduling the order of job execution
within the queue. The priority value must be in the range of [-1024..1023].
script
A file that contains instructions for the execution of a batch job.
server view
The view in Batch Manager that shows information about the operation of one or more queues.
162
Glossary
shell
An executable program that can be used to run a script. For example, cmd.exe is a shell that
can be used to run .bat scripts. See also script.
spooling
The process of storing a file internally by Batch Services until a batch job ends, and then
returning the files to the intended directories. Spooling is not supported on remote computers.
started
A queue state in which the queue will run jobs submitted to it.
stdin, stderr, stdout

These are standard streams for input, output, and error output.
By default, standard input (stdin) is read from the keyboard, while standard output (stdout) and
standard error output (stderr) are printed to the screen.
stopped
A queue state in which the queue will not run jobs submitted to it.
163
Glossary
164
Index
A
Abort command (Queue Menu) 72
Abort queue 141
aborting a queue 27
Aborting all jobs 32
aborting jobs 32
Aborting running jobs 156
About Batch command (Help Menu) 76
Access 24
Accessing a remote server 42
Accessing a Remote Server 42
Accessing Other Nodes 13
account mapping 159
Account Mapping 73
Account Mapping Command (Server Menu)
73
Account Mapping Dialog 73
Account Mapping Overview 14
Add destination 141
Add groups 141
Add managers 141
Add shell_name 142
Add shell-name 142
Add users 142
Add Users and Groups dialog 74
Add Users and Groups Dialog Box 74
Adding and Deleting Batch Queue Shell
Lists 27
Adding and deleting destinations 29
Adding and Deleting Pipe Queue
Destinations 29
Adding and deleting shell lists 27
Adding shell lists 27
API Description 79
API Error Codes 126
API structures 81
B
Basics of Batch Services 154
Batch API Error codes 126
Batch API function calls 93
Batch API Function Calls 93
Batch API Structures 81
Batch Client API 79
Batch Client API interface 80
Batch Client API Set 14
batch job 31, 37, 159
Batch job output 34

Batch job submission 36
Batch Manager 51
Batch Manager Components 52
Batch Manager display 50
Batch Manager GUI 51
Batch Manager Interface 51, 52
Batch Privileges 14
batch queue 159
Batch queues 27, 159
Batch Queues and Pipe Queues 154
BATCH RECURRENCE INFO 90
batch server 159
Batch Server 159
Batch service 43
Batch Service Privileges 14
Batch Service Security 15
Batch Services Overview 11
Batch Specific Error Conditions 126
Batch User Interfaces 15
BATCH_JOB_INFO_1 85
BATCH_JOB_INFO_2 86
BATCH_QUEUE_INFO_1 81
BATCH_QUEUE_INFO_2 82
BATCH_RECURRENCE_INFO 90
BATCH_SERVER_INFO 92
BatchAbortJob 94
BatchAbortQueue 95
BatchCreateQueue 96
BatchCreateQueue Default
BATCH_QUEUE_INFO_2 Values 97
BatchCreateQueue Default Structure 97
BatchDeleteJob 98
BatchDeleteQueue 99
BatchDisableQueue 100
BatchEnableQueue 101
BatchEnumerateJobs 101
BatchEnumerateQueues 103
BatchGetJobInfo 104
BatchGetQueueInfo 105
BatchGetServerInfo 106
BatchJobHold 107
BatchJobRelease 109
BatchMoveJob 110
BatchPurgeQueue 112
BatchServerShutdown 112
BatchSetJobInfo 113
BatchSetQueueInfo 116
BatchSetServerInfo 119
165
Index
Batch-Specific Error Conditions 126
BatchStartQueue 120
BatchStopQueue 121
C
Changing security 24
Command Line Interface 131
Configuring SMTP Mail 45
Configuring SMTP mail notification 45
Configuring the batch server 42
Configuring the Batch Server 42
Connect to command (Queue Menu) 65
Connect To Command (Server Menu) 72
Connect to Queue 65
Connect to Server Dialog 72
Connecting to a queue 21
Connecting to a Queue 21
Contents command (Help Menu) 76
Context Sensitive Help Button 76
Controlling queue usage 156
Create batch_queue 142
Create batch-queue 142
Create command (Queue Menu) 65
Create pipe_queue 142
Create pipe-queue 142
Create Queue 65
Destinations 68
General 66
Job Defaults 67
Scheduling 66
Security 67
Shells 67
Create Queue Destinations 68
Create Queue General 66
Create Queue Scheduling 66
Create Queue Shells 67
Creating a queue 21
Creating a Queue 21
Customer Directory 154
customer support 154
Customer Support 153
D
date-time parameter 134
Debug Level 133
default queue 159
Default Queue 159
default shell 159
Default Shell 159
Default Values for QueueBatchJob 124
delete batch job 31
Delete command (Job Menu) 59
166
Delete command (Queue Menu) 68

Delete destination 142
Delete groups 142
Delete managers 143
Delete queue 143
Delete request 143
Delete shell_name 143
Delete shell-name 143
Delete users 143
Deleting a batch job 31
Deleting a Batch Job 31
Deleting a queue 22
Deleting a Queue 22
Deleting all job 32
Deleting or Aborting Batch Jobs 138
Deleting shell lists 27
Deleting/Aborting all Jobs in a Queue 32
Dest-name 132
Disable command (Queue Menu) 71
Disable queue 144
disabled 160
Disabling a queue 23
Displaying Batch Manager help 49
Displaying Batch Manager Help 49
Displaying queue status 22
Displaying Queue Status 22
E
Enable command (Queue Menu) 71
Enable queue 144
enabled 160
Enabling a queue 23
Enabling/Disabling a Queue 23
execution host 160
execution priority 160
Exit 144
Exit command (Job Menu) 55
F
File staging 15, 32, 33
File Staging 15, 155
Staging Files In 32
Staging Files Out 33
File Staging Example 16
files 32, 33
Frequently Asked Questions 157
G
General 69
getting job status 33
Getting job status information 33
Index
Getting Started 13
Granting jobs access to the desktop 43
Granting Jobs Access to the Desktop 43
Group 132
H
Handling Batch Job Output Files 34
Handling output files 34
Handling Queue Security 24
Help 144
Help Menu 53, 76
hold 160
Hold 144, 160
Holding a batch job 37
I
Inbound Staging 16
Inflow 162
inflow state 160
Input Methods 54
Intergraph Directory 154
J
job 161
Job ID 161
job identifier (job ID) 161
Job Menu 52, 55
Job Properties
Advanced 59
File Staging 58
General 56
Notification 57
Output 59
Resources 57
Scheduling 56
Job Properties Dialog Box 55
Job Properties General 56
Job Properties Output 59
Job Property Dialog 55
Job Status Notification 155
Job Submit 60
Advanced 63
File Staging 63
General 61
Notification 62
Output 63
Resources 62
Scheduling 61
Job Submit File Staging 63
Job Submit General 61
Job Submit Notification 62
Job Submit Output 63

Job Submit Scheduling 61
Job-id 133
M
manager 161
Manager 14
Managing Batch Services 139
Managing the Batch Manager Display 50
Mapping One Server to Another 48
Mapping to Other Computers 48
Modify request 144
Modifying a batch job 36
Modifying a Batch Job after Submission
36
Modifying queue parameters 25
Modifying Queue Parameters 25
Move command (Job Menu) 60
Move Job Dialog 60
Move Job Dialog Box 60
Move request 144
Moving a batch job 37
Moving a Batch Job 37
N
Name Syntax 131
Named Jobs 17
Naming Restrictions 18
Nice-value 133
O
Obtaining information about failures 155
Obtaining Job and Queue Status 139
operator 161
Operator 14
Operator Hold and Release commands
(Job Menu) 59
Outbound Staging 17
Outflow 162
outflow state 161
Output files 34
Overview 51
P
Pausing a batch job 37
Pausing/Holding a Batch Job 37
per-process file size limit 161
pipe queue 161
Pipe Queues 161
Power failures 157
Priority-value 133
167
Index
privilege 161
Privilege 161
Properties command (Job Menu) 55
Properties command (Queue Menu) 68
Properties Command (Server Menu) 74
Purge command (Queue Menu) 72
Purge queue 144
Q
qdel
An Overview 138
Qdel 138
qdel Interface 138
Qdel interface 138
qmgr
An Overview 139
Qmgr 139
qmgr Interface 140
Qmgr interface 140
qstat
An Overview 139
Qstat 139
qstat Interface 139
Qstat interface 139
qsub
An Overview 135
Qsub 135
qsub Interface 135
Qsub interface 135
queue 22, 32, 162
Queue 131
Queue Menu 52, 64
Queue Properties
Destinations 71
General 69
Job Defaults 69
Scheduling 69
Security 70
Shells 70
Queue Properties Dialog Box 68
Queue Properties General 69
Queue Properties Job Defaults 69
Queue Properties Scheduling 69
Queue Security 24
queue state 162
Queue States 162
Queue States and Job States 154
queue view 162
Queue View 53, 162
QueueBatchJob 122
Quit 145
168
R
Receiving mail notification 155
recurring jobs 162
Recurring Jobs 162
Refresh command (View Menu) 76
Release 145
Releasing a Batch Job 38
Removing the batch service 43
Removing the Batch Service 43
Required Calling Privileges 128
Resource Usage 156
Restart queue 145
Restarting a batch job 38
Restarting a Batch Job 38
Restricting access 24
Run Now (Job Menu) 60
Runlimit 133
S
Sample Scripts 77
Saving and restoring named batch jobs 39
Saving and Restoring Named Batch Jobs
39
scheduling priority 162
script 162
Script Browser 76
Script Examples 77
Security 156
Sending and Receiving Files 155
Server 132
Server Menu 52, 72
Server Properties
General Tab 74
Security 75
Security Tab 75
Server Properties Dialog Box 74
Server Property Dialog 74
server view 162
Server View 53, 162
Set debug 145
Set default batch request priority 146
Set default batch request queue 146
Set default batch_request queue 146
Set default shell 146
Set destination 146
Set managers 146
Set nice_value_limit 147
Set nice-value limit 147
Set no access 147
Set no default batch request 147
Set no default batch request queue 147
Set no default shell 147
Index
Set no_access 147
Set per_process permfile_limit 147
Set per-process permfile limit 147
Set priority 147
Set runlimit 147
Set shell_name 148
Set shell-name 148
Set unrestricted access 148
Set unrestricted_access 148
setpasswd.exe Utility 151
Setting batch server logging level 44
Setting Batch Server Logging Level (Debug
Level) 44
Setting debug level 44
Setting server managers 44
Setting Server Managers and Operators
44
Setting server operators 44
Setting the default queue 30
Setting the Default Queue 30
Setting the default shell 28
Setting the Default Shell 28
Setting up a shell 157
shell 163
Shell 163
Shell-name 132
Shell-path 134
Show all 148
Show limits supported 148
Show long queue 148
Show managers 148
Show parameters 148
Show queue 149
Shutdown 149
Shutting down the batch server 47
Shutting Down the Batch Server 47
SMTP mail 157
spooling 163
Spooling 163
Staging files in 32
Staging files out 33
Start command (Queue Menu) 71
Start queue 149
started 163
Starting a queue 26
Starting the batch server 47
Starting the Batch Server 47
Starting/Stopping a Queue 26
status 22, 33
Status Bar 54
Status Bar command (View Menu) 75
stderr 163
stdin 163
stdin, stderr, stdout 163

stdout 163
Stop command (Queue Menu) 71
Stop queue 149
stopped 163
Stopping a queue 26
Stopping all Running Jobs 27
Stopping all running jobs in a queue 27
Submit command (Job Menu) 60
Submitting a batch job 40
Submitting a Batch Job 40
Submitting Jobs 135
Submitting jobs to remote nodes 156
support 154
T
Task Reference 19
telephone support 154
Telephone Support 154
Toolbar 52
Toolbar command (View Menu) 75
Troubleshooting 153
U
Understanding batch queues and pipe
queues 154
Understanding queue states and job states
154
Unhold 149
User 132
User Hold and Release commands (Job
Menu) 60
Using a default mail address 47
Using a Default Mail Address 47
Using Help command (Help Menu) 76
Using Recurring Jobs 40
V
View Menu 52, 75
Viewing job notification messages 47
W
web site 154
Web Site 154
What's New in Batch Services 9
Win32 Error Codes 128
Window 50
Working with Account Mapping 48
Working with Batch Jobs 31
Working with Batch Manager Display 49
Working with Batch Queues 27
169
Index
Working with Batch Servers 41
Working with Batch Services 19
Working with Pipe Queues 29
Working with Queues 20
170

Batch Services

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Batch Services

Uploaded by

Copyright:

Available Formats

Batch Services

U.S. Government Restricted Rights Legend

Warranties and Liabilities

Batch Services User's Guide

Batch Services User's Guide

Batch Services User's Guide

Batch Services User's Guide

Batch Services User's Guide

Batch Services User's Guide

What's New in Batch Services

Batch Services User's Guide

What's New in Batch Services

Batch Services User's Guide

Batch Services Overview

Batch Services User's Guide

Batch Services Overview

Batch Services User's Guide

Accessing Other Nodes

Batch Services User's Guide

Account Mapping Overview

Batch Client API Set

Batch Service Privileges

Assigning and Removing Privileges

Batch Services User's Guide

Batch Service Security

Batch User Interfaces

submitting jobs (qsub: An Overview (on page 135))

Batch Services User's Guide

File Staging Example

Batch Services User's Guide

Method 1: Using the Job Submit dialog

Method 2: Using the Named Job File

Batch Services User's Guide

Batch Services User's Guide

Working with Batch Services

Batch Services User's Guide

Working with Batch Services

Batch Manager Display

Batch Services User's Guide

Working with Batch Services

Working with Queues

Using Batch Manager:

Using the command line:

Batch Services User's Guide

Working with Batch Services

Using Batch Manager:

Batch Manager requests confirmation before deleting any queues.

Using the command line:

Using the Batch API:

Displaying Queue Status

Batch Services User's Guide

Working with Batch Services

Using the command line:

Using the Batch API:

Using Batch Manager:

Using the command line:

Using the Batch API:

Batch Services User's Guide

Working with Batch Services

Handling Queue Security

If you are creating a queue using Batch Manager:

If you are modifying an existing queue using Batch Manager:

If you want to restrict access to a queue using the Command Line:

If you want to un-restrict access to a queue using the Command Line: