CapeSoft.Com
Clarion Accessories
OddJob
Documentation
CapeSoft Logo

CapeSoft OddJob
Documentation

Download Latest Version History
Installed Version Latest Version

Introduction

Please Note: OddJob requires StringTheory

OddJob provides a set of classes and templates for running and managing processes from within your application (executables, batch files etc.).

Oddjob will easily help you:
OddJob also allows you to pass data to started processes and retrieve data from them. You use it to send and receive data via the StdIn and StdOut of any started process, and OddJob works excellently with NetTalk to communicate with processes via TCP/IP.

OddJob also provides the ability to pass data to a started process (via the Standard Input as well as on the command line), which allows command line applications to be run and data passed to them, as well as retrieving the result back from the process. This opens up a huge number of command line tools to your application, from simple command line clients, to command line server, compilers and even batch files.

We strongly recommend starting with the example applications, which are described below in the Example section.

Jobs and Features

Not only can you run, monitor, terminate and manage any processes that you start, you can also group them into Jobs.

A Job allows groups of processes to be managed as a unit. Job objects are nameable, securable, sharable objects that control attributes of the processes associated with them.

Operations performed on the job object affect all processes associated with the job object. If you have used applications such as Google Chrome or Internet Explorer then you will have experienced Jobs in action, as each tab creates a new process that is a member of the same Job.

This allows tasks normally performed by threads to be performed by processes, providing improved stability and isolation.

Using CapeSoft OddJob

Add OddJob to your application in a few Easy Steps!

  1. If this is a Multi-App system, then add the OddJob global extension to the data (root) DLL. On the Multi-DLL tab in this app tick on both options (This is part of a Multi-DLL program and Export OddJob classes from this DLL.)
    If this app is not part of a Multi-DLL system then skip this step
  2. In the app where you want to create and use an OddJob object, add the global extension to the app. If this is part of a Multi-DLL solution then go tothe Multi-DLL tab and only tick the first option on (This is part of a Multi-DLL program)
  3. Add the Local extension to the procedure that you wish to use OddJob in.
    This adds a JobObject object to the procedure.

  4. Add code to initialize and kill the object

    Initializing the object passing a Job name is option. You can call Init without specifying a Job name, in which case the object will be initialized, but no Job will be created. This is useful when you want to use the functionality that doesn't require a JobObject (for example starting a process, enumerating processed on the machine, or killing a process).

    1. Initialize the object (for example before the window opens in ThisWindow.Init(), or at the start of the procedure).

      Job.Init('MyJob')

    2. Kill the object and clean up:

      Job.Kill()

      Note: You can also call Job.Kill(false) to clean up all memory and handles, but leave any processes in the job running. By default calling Kill will end all processes started, but by passing False to the method all processes will be left running and the Windows JobObject will remain until all processes have closed.

Using the JobObject

The code below demonstrates three different ways of creating and interacting with new processes

Starting Processes

! declare a StringTheory object for getting the output from a process
output          StringTheory
  code

    ! Example1 : Start a new process
    Job.CreateProcess('', 'notepad.exe', '', '')


    ! Example 2: Call a process using cmd.exe (command), make it hidden, and store the output:
    Job.CreateProcess('takeaction.BAT', jo:SW_HIDE, false, , , , , output)


    ! Example 3: Call a process passing a command line parameter, and get the output of the process
    ! Save the output to file, and open it using the application associated with that file type.
    ! Display a message if an error occurs with the error information.
    if not Job.CreateProcess('grep.com ?',jo:SW_HIDE , , , , , , output) 
        Message('CreateProcess failed: ' & output.GetVal())
    else
        ! Save the returned data to disk, and display the error if it fails.
        if not output.SaveFile('output.txt')
            Message('Failed to save the output. Error ' & |
                     output.winErrorCode & ': ' & |
                     output.FormatMessage(output.winErrorCode))
        else
            ! Run a file (simply runs a program, opens a directory, or opens a file 
            !  using the default application associated with that file type.
            Job.ExecuteFile('output.txt')
        end
    end
Kill all processes associated with a Job

Job.CloseAll()

Get information about the a Job

Job.GetInformation(jo:JobObjectBasicAccountingInformation)

! The job information is now stored in Job.basicAccounting

How to call a command line application and get the output

This example demonstrates the best practice for calling applications on the command line. It retrieves the output for StdOut if any is written, but works equally well for applications that don't actually write anything to StdOut. It has the added benefit of essentially synchronizing the process class, as it reads from the output on a timer until the handle is close and the process is complete. In almost every case, when you call a command line application and need to retrieve output, a synchronous behaviour is desirable. Not that if you call this on a thread that display a user interface, the interface will be unresponsive while the StdOut pipe is being read from, as the read is handled on a separate Accept loop.

exitVal     long
st          StringTheory
commandLine string(512)
jo          Class(JobObject)   ! added by the template
            end
   CODE
			
    ! Build the command line
    commandLine = 'Dcdirdmp.exe -if dicomdir'   ! Add any additional parameters here
    st.Free() 

    ! CreateProcess(string pAppName, ushort pMode, byte pUseCmd=0, <string pPath>, |
    !              <string pMessage>, <string pTitle>, <*long pExitCode>, |
    !              <*StringTheory strData>, long noRead = 0, long noStore =0)
    jo.CreateProcess(commandLine, jo:SW_HIDE, 1, , , , exitVal, st)

    ! The exit value is stored in exitVal, and any output that 
    ! was sent to StdOut is stored in the st StringTheory object

Examples

Demo This is the main OddJob example application.

It enables you to run a batch file or exe and retrieve the output data. It also creates a job and allows you to add as many instances of Notepad to the job as desired, as well as listing information about the job and processes running on the machine. Any application can be added to a Job, regardless of whether it is an application that you have created, or an application such as Notepad from a third party.

Html Editor

This provides a simple HTML editor and demonstrates the use of NetTalk for inter process communication. NetTalk is required to compile this example. The HTML editor is a completely standalone application that is integrated with the example using a Job to control the process and NetTalk.

Note: The feHtmlEditor.app file does not need to be compiled, the shipped executable will be used by default, and it provides a standalone HTML editor that is fully integrated with the example application. In order to compile the actual editor executable NetTalk and FileExplorer are required.

The OddJob Templates

The Global Extension template:

There are no options for the Global extension.

The OddJob local extension template

Add this extension to a window procedure where you want to control any started processes. This window must exist as long as the processes are running, or at least as long as you are interacting with them in any way.

The local extension allows you to specify the type of object being used. By far the most common is the standard Job object, which provides the foundation for OddJob's functionality.

Version History

Download latest version here

Version 1.45 - 24 May 2021 Version 1.44 - 28 September 2020 Version 1.43 - 13 September 2018 Version 1.42 - 24 July 2018 Version 1.41 - 5 September 2017 Version 1.40 - 28 September 2016 Version 1.39 - 28 April 2015 Version 1.38 - 3 March 2015  Version 1.37 - 25 February 2015 Version 1.36 - 7 March 2014 Version 1.34 - 3 February 2014 Version 1.33 - 14 May 2013 Version 1.32 - 14 March 2013 Version 1.31 - 28 November 2011 Requires StringTheory 1.52 or later Version 1.30 - 09 September 2011 Version 1.29 - 29 June 2011 Version 1.28 - 9 April 2011 Version 1.27 - 13 December 2010 Version 1.26 - 16 September 2010 Version 1.26 - 16 September 2010 Version 1.25 - 15 June 2010 Version 1.24 - 01 June 2010 Version 1.23 - 01 June 2010 Version 1.22 - 26 May 2010 Version 1.21 - 17 May 2010 Version 1.20 - 17 May 2010 Version 1.10 - 06 April 2010 Version 1.03 - 20 October 2009 Version 1.02 - 20 October 2009 Version 1.01 - 12 October 2009 Version 1.00 - 11 August 2009