> ### Creating a job instance

> When you want to create and run a Fathom job, you have several options. You can create a job that runs once or on a recurring basis. You can also create a template for a job and then run separate job instances based on the specifics you provide only once in the template.

> When you want to create a job for one-time or recurring use, or if you want to create a job based on an existing template, you create a job instance.

> To create a job instance:

> 1. Click Jobs from the menu bar. The Fathom Jobs page appears.
> 2. Choose one of the following options, depending on how you want to create the job:
> - To create a unique job not based on any template, click Create Job. The Job page appears.
> - To create a job from an existing job template, click Create Job from a Template. The Create Custom Job page appears. Choose one of the existing templates. The Job page for that template appears.
> 3. Complete the following fields:
> - Name — Define the job's name. You use the job name when you want to edit the job's properties or check on the job's status. Names cannot contain spaces or special characters.
> - Description — Provide a sentence or phrase that describes the job's purpose. (Optional, but recommended.)
> - Resources — Identify database resources to associate with a job or job action. When you create a job instance, you can associate with it zero or more databases.
> If you are creating a unique job, highlight the database you want to add from the list of available database resources, and click Add. The selected database displays in the Selected list. To remove a database that you do not want selected, highlight the database name in the Selected list and click Remove.

> If you are creating a job from a template and want to include a database, select the database from the list of Available Resources.

> Note: If you are using one of the predefined database maintenance job templates, you can choose only one database. If you are using a job template that you have defined, you can choose multiple databases.

> - User name — Provide the operating system user account. It is not necessarily the same as your Fathom user account name. If specified, the name must be a valid account on the server machine (or server domain) where the AdminServer and Fathom are running. On Windows 2000 and Windows NT platforms, the name can also include a domain.
> - Group — On supported UNIX platforms, identify the name of the group. A group is a collection of users who share the same privileges.
> - Password — Provide your password. If the value you entered in the User name field does not have an associated password, you must leave this field blank; otherwise, an error message is generated.
> - Command — Identify the command you want the job to perform.
> If you are creating a job instance from a template, it is possible that the command will be predefined for you. If you are creating a unique job, you can define any command that would typically execute from an OS shell, and you can include a full or relative place-name. You can also use environment variables such as `%DLC%` or `$DLC`.

> - Command parameters — Define the input parameter to the command. The list of parameters take the same format as from an OS shell. Additionally, you can use environment variables ($SHELL or %WINDIR%, for example) and Windows registry values (@SOFTWARE\PSC\FATHOM\3.0A\10.0B\FATHOMINIT, for example).
> - Working directory — Identify the command's current working directory. If you specify a directory, the directory must exist. This property defaults to the working directory defined at installation.
> - Input file — Identify the file used for read redirection with a job's command. This is typically used for any keyboard input the command might require.
> - Output file (stdout) — Identify the file to which any output written to `stdout` is routed. Fathom creates a default `stdout` filename based on the name of the job instance. However, you can change it. If you select the Append option, any new information will be added to the existing `stdout` file.
> - Output file (stderr) — Identify the file to which any output written to `stderr` is routed. Fathom creates a default `stderr` filename based on the name of the job instance. However, you can change it. If you select the Append option, any new information will be added to the existing `stderr` file.
> Note: When you create or edit a job, Fathom will prefill the `stdout` and `stderr` filenames for you if any of these fields are left blank. The filenames will be the same as the job name, with a different suffix. You can change the filename or remove it if you do not want to create the output files. Also, if you edit the job name, Fathom will not change the filenames to reflect the new job name. You should review these filenames before saving the page to ensure the job creates the expected output files.

> - Environment: name=value pairs — Define application-specific variables to be set in the process context of the task that runs to execute the specified job.
> If you are creating a job instance from a template, a name=value pair will be predefined for you.

> - Debug log file — Select this option to obtain diagnostic details that can help debug a job.
> For example, if you set this option and use the Run Now feature to run the job, a debug log file will be generated in the default working directory. The debug log file will be named based on the job name with a `.log` extension.

> Once you have submitted the job, Fathom makes debug trace file data available. See the "Viewing job history" section for details.

> - Indicate if the job can be used as an action — Select this option if you want the job to be available as a job action. As with other Fathom actions, such as an e-mail or log file action, you can set up job actions to automatically trigger in response to alerts.
> You can execute a job in response to these events:

> – An alert trigger.

> – An alert that has been cleared.

> – A schedule that is set up so that the job action occurs on a predetermined basis.

> - Completion Actions and Alerts — If you intend to set up actions and alerts for this job, click Edit. For more information about this page, see Step 4 in this procedure.
> 4. After you specify the job instance's properties (or accept the predefined properties, if you are using a template), you can do either of the following:
> - Define action and alert occurrences for the job as described in the "Setting up job completion actions and alerts" section.
> - Save the job. You can then run the job immediately, as described in the "Running a job immediately" section, or hold off until another time.

Copyright © 2004 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095