CapeSoft OddJob

Introduction

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:

• Run a process (like batch files and external exes) asynchronously from within your app and monitor the output (think of FTPing files via an external FTP client)?
• Handle scripting languages (like PHP scripts) synchronously or asynchronously?
• Run a user interface to control your service (and bypass UAC)?

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.

In addition OddJob provides a new string handling class called StringTheory. This provides dynamic memory allocation, string handling and manipulation, convertion between string and cstring data types, base64 encoding and decoding, and much more.

Add OddJob to your application in a few Easy Steps!

1. Add the global and local extension
   
   1. Add the Global Extension:
      Global -> Extensions -> Insert -> Activate CapeSoft OddJob.
      For Multi-DLL apps - do this in the main exe application.
      
   2. Add the Local extension to the procedure that you wish to use OddJob in.
      This adds a JobObject object to the procedure.
      
      
      
2. Add code to initialise and kill the object
   
   Initialising the object passing a Job name is option. You can call Init without specifying a Job name, in which case the object will be initialised, 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. Initialise 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.
      
      
      

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 ?', , , , , , , 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 sychronising 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 seperate 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

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 Global Extension template:

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.