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
   
   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.
      
      
3. Use the JobObject
   1. The code below demonstrates three different ways of creating and interacting with new 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

       
   2. Kill all processes associated with a Job:
      
      Job.CloseAll()
      
   3. Get information about the a Job:
      
      Job.GetInformation(jo:JobObjectBasicAccountingInformation)
      
      ! The job information is now stored in Job.basicAccounting

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.