2.1.2 Designing executable files
JP1/AJS3 processes work tasks based on executable files, such as batch files and shell scripts. This section identifies the considerations involved in designing executable files to carry out work tasks.
When designing executable files, consider the following points:
- Organization of this subsection
(1) Use a format supported by JP1/AJS3
Processing cannot be automated in JP1/AJS3 unless it complies with a supported executable file format. The following table lists the types of executable files that can be used with JP1/AJS3.
|
Host type |
Supported executable files |
|---|---|
|
Windows host |
|
|
UNIX host |
|
(2) Define one command per executable file
We recommend that you define only one command in each executable file.
Dividing work task processing in this way allows you to see which processing ends normally and which does not. Because you can identify the specific process that caused a work task to terminate abnormally, you can then either rerun the work task from that process, or rerun just the process that ended abnormally.
(3) Choose processing that does not generate on-screen messages or require a response
JP1/AJS3 runs executable files in the background. Therefore, do not use an executable file that displays a window or message and then waits for a user response. However, JP1/AJS3 can use executable files if, for example, the Yes button is automatically selected on a displayed message dialog box and the process proceeds.
(4) Choose processing that outputs a return code
JP1/AJS3 judges whether processing has ended normally or abnormally based on the return code of the executable file. Therefore, create executable files whose return codes reflect the processing result.
- For processing by batch file:
-
Use the jp1exec or jp1exit command to ensure that the executable programs in the batch file output return codes that reflect the processing result. To enable analysis of the cause when a command ends abnormally, ensure that the return code that caused the abnormal end is output unaltered.
For details on the jp1exit and jp1exec commands, see 3. Commands Used for Normal Operations in the manual JP1/Automatic Job Management System 3 Command Reference.
- For processing by shell script:
-
With shell scripts, ensure that a return code that reflects the processing result is output, as in the following example:
: RC=$? exit $RC
Set the threshold values that determine the ranges for end with warning or abnormal end results.
(5) Choose processing with a short execution time
If the execution time for a single process is too long, you might not be able to determine whether the work task is proceeding normally, or processing has stopped due to an error of some kind. As a guide, make sure that no individual process takes longer than two hours.
(6) Use meaningful file and folder names
We recommend that you create a naming convention for executable files and the folders and directories where executable files are saved. Using consistent names with work tasks, processes, and other elements used with JP1/AJS3 makes it easier to manage work tasks as a whole. One effective method is to define a set of identifiers that indicate work task names, process names, processing cycles, execution locations, and so on.
One-byte alphanumeric characters, multi-byte characters and the following symbols can be used in the names of work tasks and processes used with JP1/AJS3.
! # $ % + @ - (hyphen) . (period) _ (underscore)
Note that some symbols have special meanings in command interpreters such as UNIX shells. Because symbols might cause unpredictable results, avoid using them for work task and process names.
In addition, do not use the following characters or symbols:
-
Periods (.) or at marks (@) at the beginning of work task or process names
-
Machine-dependent characters
(7) Save executable files on the host where the processing is to be executed
Save the executable files (such as commands and batch files) on the host where you intend the processing to be executed.
(8) Other points
-
When specifying commands and input or output files in executable files, specify an absolute path including the folder names.
-
To enable analysis of the cause when a command ends abnormally, output an arbitrary message to the standard error output by, for example, using an echo command. It is useful for this message to include information such as the cause of the error and how to recover from it, the work task name, and notes on rerunning the work task. You can view these messages in the Execution Result Details dialog box in JP1/AJS3 - View. For details about the Execution Result Details dialog box, see 12.3.39 Execution Result Details dialog box in the JP1/Automatic Job Management System 3 Operator's Guide.
-
As a general rule, if you use environment variables, you should define them in the executable file.
-
When using a shell script, declare the shell used at the head of the file. For details about the supported shells, also see 2.5.3 OS user environment when a job is executed in the JP1/Automatic Job Management System 3 System Design (Configuration) Guide.