jpqimport

Organization of this page

Format
Description
Execution privileges
Arguments
Notes
Return values
Additional information
Defining the configuration definition file for the submit job execution environment (jpqsetup.conf)

Format

jpqimport
     -dt isam
     -ci name-of-configuration-definition-file-for-submit-job-execution-environment
     [-mh logical-host-name]
     [-dp name-of-database-storage-directory]

To Page Top

Description

Collectively defines the job execution environment (job execution agent, queues, and execution-locked resources) using the configuration definition file for the submit job execution environment (jpqsetup.conf).

If you want to execute a job on another host agent, you must define the job execution agent in the job execution environment.

In addition, you must create queues in the following cases:

When you want to use purpose-specific queues to accept jobs registered (submitted) from clients
When you want to distribute execution of jobs
When you want to accept jobs from JP1/NQSEXEC and JP1/OJE for VOS3

To Page Top

Execution privileges

In Windows: Administrators privileges

In UNIX: Superuser privileges

To Page Top

Arguments

`-dt isam`

Specify the type of the database used in the job execution environment.

isam

ISAM-based database

`-ci` `name-of-configuration-definition-file-for-submit-job-execution-environment`

Specify the name of the configuration definition file for submit job execution environment (jpqsetup.conf) to be used.

You can specify 1 to 511 characters (bytes).

If you specify only the file name (jpqsetup.conf) for the -ci option, it is assumed that the file (jpqsetup.conf) exists in the current directory when the command is executed. Therefore, if the file (jpqsetup.conf) does not actually exist in the current directory, the command will end in an error.

To execute the command regardless of whether the file jpqsetup.conf exists in the current directory, specify the full path of the file jpqsetup.conf for the -ci option.

For details on how to define the configuration definition file for the submit job execution environment, see Defining the configuration definition file for the submit job execution environment (jpqsetup.conf), below.

`-mh` `logical-host-name`

Specify the logical host name.

You can specify 1 to 255 characters (bytes).

If you omit this option, the system assumes the physical host name.

Specify this option first.

`-dp` `name-of-database-storage-directory`

Specify the name of the directory that will contain the ISAM files used as the database in the job execution environment.

You can specify 1 to 511 characters (bytes).

If you omit this option, the system assumes the directory name defined as the database storage directory for the job execution environment during environment setting (configuration).

To Page Top

Notes

The job execution environment collectively defined by using this command is used for QUEUE jobs and submit jobs.

Further, job execution environment settings are not used by queueless jobs.
If this command is used to define all execution environment settings for submit jobs at one time, old information is not overwritten with the new information. Before you re-create the database of the execution environment for submit jobs, always stop JP1/AJS3 and delete or back up the database that has been created. If you choose to delete the database, delete all files contained in the directory to be specified in the -dp option (the job execution environment database storage directory specified during environment setup).

In Windows, delete these files by a program such as Explorer.

In UNIX, delete these files with the rm command.
Use the character set for JP1/AJS3 operation as the character sets^# used in the file specified by the -ci option.

#

It refers to the character set specified by the AJSCHARCODE environment setting parameter.
When you specify a database storage directory name in the -dp option, you must also make this specification during environment setup.

Specify a database storage directory name in the DatabasePath environment setting parameter.
If you execute this command when JP1/AJS3 is running on the same logical host, an error occurs.
Depending on the contents of the configuration definition file for the submit job execution environment, the collective definition processing for the job execution environment might take several tens of minutes.
When you re-create the job execution environment, you must delete the standard output file and standard error output file for the remaining job. If you re-create the job execution environment after executing a large number of jobs, it may take a longer time for command execution because of the processing for deleting these files.
Be careful if you decrease the maximum number of job execution agents, queues, or execution-locked resources that can be defined in the common definition information before you use this command to add or delete these items. If you do this, you might be unable to collectively import the job execution environment settings by using the jpqimport command from the configuration definition file for the submit job execution environment exported by the jpqexport command. For example, assume that there is an environment where the maximum number of agents that can be defined is set to 30 in the common definition information. In addition, assume that an agent ID whose ID is 100 has been specified in the configuration definition file for the submit job execution environment. In this situation, if you execute the jpqimport command to import the configuration definition file, the command results in an error.

If this error occurs, correct the configuration definition file for the submit job execution environment so that the defined ID numbers for agents, queues, and execution-locked resources do not exceed their maximum values set during environment setup. Then re-execute the jpqimport command.
The system handles lines beginning with a # as a comment. Place the # at the very beginning of a comment line. Placing # after a parameter causes an error.
If you omit the -mh option, the system does not reference environment variable JP1_HOSTNAME. To enable operation on the logical host, do not omit this option.

To Page Top

Return values

0	Normal end
1	The specified argument is invalid.
130	The configuration definition information file for submit job execution or its path is not found.
132	The contents of the configuration definition information file for submit job execution are inappropriate.
133	You do not have the privilege (are not authorized) to access the configuration definition information file for submit job execution.
135	The system cannot create a database because there are insufficient system resources.
136	The database is already created.
137	The database storage directory is missing.
138	You do not have the privilege (are not authorized) to access the database.
140	You do not have Administrators privileges (in Windows) or superuser privilege (in UNIX) to collectively define the job execution environment.
141	Environment settings or the logical host name is inappropriate.
142	The manager host is running on the same logical host.
145	There is insufficient memory.
146	Free disk space is insufficient.
147	An internal factor error occurred.
149	The system cannot perform processing because the database size exceeds 2 gigabytes.
150	The database cannot be connected.
151	RDAREA is invalid or RDAREA does not exist.
153	The command cannot be executed.

To Page Top

Additional information

When you want to change the configuration definition for the job execution environment by adding or deleting job execution agents, queues, or execution-locked resources, use any of the following methods:
- Stop the JP1/AJS3 service and then recreate the database for job execution environment with this command. If you are executing a remote job, also stop the JP1/AJS3 service on the remote host.
- Without stopping the job operation, change the configuration definition for job execution environment with any of the following commands:
  
  jpqagtadd: Adds an agent.
  
  jpqagtdel: Deletes an agent.
  
  jpqagtalt: Changes the attribute of an agent.
  
  jpqagtlink: Links a queue and its agents and then changes the priority of the destination agents.
  
  jpqagtunlink: Unlinks a queue and its agents.
  
  jpqqueadd: Adds a queue.
  
  jpqquedel: Deletes a queue.
  
  jpqquealt: Changes the attributes of a queue.
  
  jpqqueopen: Opens a queue.
  
  jpqqueclose: Closes a queue.
  
  jpqresadd: Adds an execution-locked resource.
  
  jpqresdel: Deletes an execution-locked resource.
You can use aliases to create several agents on a single manager host. Before you do this, make sure that the aliases can be resolved into addresses (the ping command is terminated normally).

To Page Top

Defining the configuration definition file for the submit job execution environment (jpqsetup.conf)

Define the following three items in the configuration definition file for submit job execution:

Agent definition
Queue definition
Execution-locked resource definition

The following explains the definition of each item.

Agent definition

Format

$agent $agent-ID {agent-host-name|$system}
[exec_jobs time-to-start-setting-for-the-number-of-concurrent-jobs time-to-stop-setting-for-the-number-of-concurrent-jobs number-of-concurrent-jobs]...
def_queue $default-queue-ID
[max_jobs maximum-number-of-jobs-in-queue]
[warn_jobs warning-value-on-number-of-jobs-in-queue]
[queue_ent {open|close}]
[queue_exit {open|close}]
[connect $agent-ID priority]...
$end

Arguments

$agent $ agent-ID {agent-host-name|$system}

Specify the name of the agent host responsible for job execution.

$agent: Fixed
$agent-ID: Specify an agent ID in the $an format (where n is a unique value in the manager host (a value other than 0)). For n, specify a value less than or equal to the number of defined agents specified at environment setting. (For example, if 256 agents are defined, specify a value that is less than or equal to 256 for n. Specifying a value that is greater than or equal to 257 will result in an error.)
agent-host-name: Character string of up to 255 bytes
$system: Job execution agent on the manager host

exec_jobs time-to-start-setting-for-the-number-of-concurrent-jobs time-to-stop-setting-for-the-number-of-concurrent-jobs number-of-concurrent-jobs

Specify the number of concurrent jobs. If you omit this option, the system assumes 0 for the number of concurrent jobs for a day.

Specifying the number of concurrent jobs enables you to limit the number of jobs that can be concurrently executed by this agent host. You can apply this limit to standard jobs (UNIX, PC, and QUEUE jobs), action jobs, and custom jobs. If the number of jobs that you attempt to execute concurrently reaches the specified number of concurrent jobs, those jobs that exceed the limit will be queued until another job has finished.

If the number of concurrent jobs is 0, no jobs can be executed. If you want to execute jobs, specify 1 or a greater value.

time-to-start-setting-for-the-number-of-concurrent-jobs: Specify the time to start setting for the number of concurrent jobs in the hhmm format. You can specify 00 to 23 (hours) for hh and 00 or 30 (minutes) for mm.
time-to-stop-setting-for-the-number-of-concurrent-jobs: Specify the time to stop setting for the number of concurrent jobs in the hhmm format. You can specify 00 to 23 (hours) for hh and 00 or 30 (minutes) for mm.
number-of-concurrent-jobs: Specify a value from 0 to 4,294,967,295.

def_queue $default-queue-ID

Specify the default queue ID.

The default queue is required when you execute a job by specifying an agent host name. Specifying an agent host name as the job submission or execution destination causes the job to be submitted to the default queue of the agent host.

$default-queue-ID: Specify the default queue ID in the $qn format (where n is a unique value (a value other than 0) for all the default queue and non-default queue IDs in the manager host). For n, specify a value less than or equal to the number of defined queues specified at environment setting. (For example, if 256 queues are defined, specify a value less than or equal to 256 for n. Specifying a value greater than or equal to 257 will result in an error.)

max_jobs maximum-number-of-jobs-in-queue

Specify the maximum number of jobs that can be accumulated in the default queue. If you omit this option, the system assumes 4,294,967,295. Note, however, that despite this setting, if the number of jobs remaining in the queue equals the value for maximum number of jobs in the system, job submission will fail.

This setting also includes the number of jobs that are actually being executed. The number of jobs is the sum of the values of QUEUING and EXECUTING displayed by the jpqqueshow command with the -q option specified.

maximum-number-of-jobs-in-queue: Specify a value from 1 to 4,294,967,295.

warn_jobs warning-value-on-number-of-jobs-in-queue

Specify a warning value indicating that the number of jobs in the default queue is nearing the maximum number of jobs that can be accumulated in the default queue. If you omit this option, the system assumes 4,294,967,295. This setting (including the default value) is for the number of jobs in the default queue, including the jobs that are being executed. When you specify the -ah option in the jpqqueshow command to check, the number of jobs includes the jobs of both QUEUING and EXECUTING.

When the number of jobs reaches the warning value, the warning message KAVU4516-W is output to the integrated trace log.

warning-value-on-number-of-jobs-in-queue: This value must be no more than the maximum number of jobs that can be queued and must be in the range from 1 to 4,294,967,295.

queue_ent {open|close}

Specify the status of the queue entrance of the default queue for jobs. If the entrance is closed, no jobs can be put into the default queue. If you omit this option, the system assumes open.

open: Opens the queue entrance.
close: Closes the queue entrance.

queue_exit {open|close}

Specify the status of the exit of the default queue for jobs. If the exit is closed, jobs are accumulated in the queue and are not executed. If you omit this option, the system assumes open.

open: Opens the queue exit.
close: Closes the queue exit.

connect $agent-ID priority

Specify the ID of the agent host to be connected to the default queue. You can specify several agent host IDs. If you omit this option, you cannot execute jobs in which agent host names are specified.

$agent-ID: Specifies the ID of the agent host to be connected in the $an format.
priority: Specifies a value from 1 to 16 (the lowest priority is 1 and the highest priority is 16). Jobs are executed in descending order of priority.

$end

Specifies the end of the agent information.

$end: Fixed

Example of coding:

$agent $a1 $system
exec_jobs 0000 0730 10
exec_jobs 0730 2000 1
exec_jobs 2000 0000 5
def_queue $q1
max_jobs 10
warn_jobs 5
queue_ent open
queue_exit open
connect $a1 1
$end
 
$agent $a2 agent1
exec_jobs 0000 0000 10
def_queue $q2
max_jobs 10
warn_jobs 5
queue_ent open
queue_exit open
connect $a1 1
connect $a2 2
$end

Queue definition

Format

$queue $queue-ID queue-name
[max_jobs maximum-number-of-jobs-in-queue]
[warn_jobs warning-value-on-number-of-jobs-in-queue]
[queue_ent {open|close}]
[queue_exit {open|close}]
[connect $agent-ID priority]...
$end

Arguments

$queue $ queue-ID queue-name

Specify a queue name. Note that agent names are not case sensitive, but that queue names are.

$queue: Fixed
$queue-ID: Specify the queue ID in the $qn format (where n is a unique value (a value other than 0) for all default queue IDs and non-default queue IDs in the manager host). For n, specify a value that is less than or equal to the number of defined queues specified at environment setting. (For example, if 256 queues are defined, specify a value less than or equal to 256 for n. Specifying a value greater than or equal to 257 will result in an error.)
queue-name: Character string of up to 63 bytes

max_jobs maximum-number-of-jobs-in-queue

Specify the maximum number of jobs that can be accumulated in the queue. If you omit this option, the system assumes 4,294,967,295. Note, however, that, despite this setting, if the number of jobs remaining in the queue equals the value for maximum number of jobs in the system, job submission will fail.

maximum-number-of-jobs-in-queue: Specify a value from 1 to 4,294,967,295.

warn_jobs warning-value-on-number-of-jobs-in-queue

Specify a warning value indicating that the number of jobs in the queue nears the maximum number of jobs that can be accumulated in the queue. If you omit this option, the system assumes 4,294,967,295.

When the number of jobs reaches the warning value, the warning message KAVU4516-W is output to the integrated trace log.

warning-value-on-number-of-jobs-in-queue: This value must be no more than the maximum number of jobs that can be queued and must be in the range from 1 to 4,294,967,295.

queue_ent {open|close}

Specify the status of the queue entrance for jobs. If the entrance is closed, no jobs can be put into the default queue. If you omit this option, the system assumes open.

open: Opens the queue entrance.
close: Closes the queue entrance.

queue_exit {open|close}

Specify the status of the queue exit for jobs. If the exit is closed, jobs are accumulated in the queue and are not executed. If you omit this option, the system assumes open.

open: Opens the queue exit.
close: Closes the queue exit.

connect $agent-ID priority

Specify the ID of the agent host to be connected to the queue. You can specify several agent host IDs. If you omit this option, you cannot execute those jobs that specify queue names.

$agent-ID: Specifies the ID of the agent host to be connected in the $an format.
priority: Specifies a value from 1 to 16 (the lowest priority is 1 and the highest priority is 16). Jobs are executed in descending order of priorities.

$end

Specifies the end of queue information.

$end: Fixed

Example of coding:

$queue $q3 queue1
max_jobs 10
warn_jobs 5
queue_ent open
queue_exit close
connect $a1 1
connect $a2 2
$end

Execution-locked resource definition

Format

$res $execution-locked-resource-ID execution-locked-resource-name
$end

Arguments

$res $ execution-locked-resource-ID execution-locked-resource-name

Specify an execution-locked resource name.

$res: Fixed
$execution-locked-resource-ID: Specify the execution-locked resource ID in the $rn format (where n is a unique value in the manager host (value other than 0)). For n, specify a value less than or equal to the number of defined execution-locked resources specified at environment setting. (For example, if 256 execution-locked resources are defined, specify a value less than or equal to 256 for n. Specifying a value greater than or equal to 256 will result in an error.)
execution-locked-resource-name: Character string of up to 63 bytes

$end

Specifies the end of execution-locked resource information.

$end: Fixed

Example of coding:

$res $r1 DAT_System
$end
 
$res $r2 Temp_File01
$end

To Page Top