The Job Admin function library (CF8JOBADM.DLL) can be called directly by user applications. The interface is subject to change, and it is advised that you should contact Copia before starting development of applications which use this API directly. A good knowledge of Windows application programming is required to use this API and Copia support extends only to advice on the operation of the DLL functions. The DLL functions may also be invoked from Windows command files using the JOBCALL program.

When starting to use the Job Admin DLL, you can use the DLLTEST program to exercise any of the functions in the library.  DLLTEST allows you to enter parameters manually, call the API function, and see the returned results.

If any application which uses (directly or indirectly) MSMQ operations via the CF8JOBADM.DLL, you must call the job function DLLClose immediately before you terminate your application.  It is strongly recommended that you do this for all applications, whether or not they use MSMQ functions.

'C' Function Prototype and Call Syntax

The DLL has three entry points for different parameter type encodings. All job functions are performed by passing a function name and up to three parameters to these entry points. An integer result is returned.

typedef int (*FFCB_JAA)(char*,char*,char*,int);   // system default encoding

typedef int (*FFCB_JA)(char*,char*,char*,int);            // UTF8

typedef int (*FFCB_JAU)(wchar_t*,wchar_t*,wchar_t*,int);  // UTF16

 

FFCB_JA job_entry;

FFCB_JAA job_entryA;

FFCB_JAU job_entryU;

HANDLE hjobadm = 0;

hjobadm = LoadLibrary("CF8JOBADM.DLL");

if (hjobadm) job_entryA = (FFCB_JAA)GetProcAddress(hjobadm,"JobDllEntryA");

if (hjobadm) job_entry = (FFCB_JA)GetProcAddress(hjobadm,"JobDllEntry");

if (hjobadm) job_entryU = (FFCB_JA)GetProcAddress(hjobadm,"JobDllEntryU");

...

#ifdef UNICODE

wchar_t function[64];   // function name, see separate list 

wchar_t parm1[256];     // first parameter, terminated (wchar_t)0

wchar_t parm2[256];     // second parameter, terminated (wchar_t)0

#else

char function[64];   // function name, see separate list 

char parm1[256];     // first parameter, terminated '\0'

char parm2[256];     // second parameter, terminated '\0'

#endif

int parm3;           // third parameter

int jres;            // job dll result

jres = (*(job_entry))(function,parm1,parm2,parm3);

Cautions

When calling the JobDllEntry API, the functions may write data into the passed parm1 and parm2 parameter buffers! Never pass literal constants and always allocate at least 256 bytes for these buffers (256 wide chars for UTF16). It is, however, valid to pass NULL for parm1 and/or parm2 and if the function requires a parameter it will be processed as if it were an empty string.  The System Default encoding entry point (JobDllEntryA) and the UTF8 entry point (JobDllEntry) are limited to approximately 256-byte parameters.  To be precise, the value must be converted to and from a maximum 256-character wchar_t buffer.

If you use the Unicode entry point (JobDllEntryU), then there is a job function MaxBuf which you may call to set a larger buffer size for values returned in parm2 from the Direct UJP Access function set.  You should call this function as the first job function you call, or immediately after dynamic load of the DLL, and it acts globally in the calling process.  You are still responsible for providing a large enough buffer when you call the direct access function.  Values larger than 256 are ignored for calls to JobDLLEntryA and JobDllEntry and the default remains 256.  Values less than 256 are always ignored.  The value is in wide characters.

It is very important that your application only uses the DLL to read and set job data. If you access files directly, for example by reading the job status (.JST) file to obtain information about the job, it can very severely disrupt the operation of CopiaFacts programs. In addition it makes it more likely that future changes and enhancements may break your application.

Be aware that inappropriate use of the Job Admin DLL can impair the performance and operation of the CopiaFacts job subsystem.

General Notes

An invalid function name string will result in a return value 999.

An exception in the function will result in a return value of 9999, and a description of the error will be passed back in parm1.

Failure to load the DLL or find the entry point, or a too-long passed value, will return 9998 or 9997.

The file extension on any passed job instance pathname is ignored, so you may pass any convenient extension in place of '.UJP'. The function will locate the appropriate job file(s) with the passed basename to perform the requested operation.

Visual Basic Interface

An interface is provided to allow CF8JOBADM.DLL to be called from Visual Basic. This interface is not supported by Copia and the JOBADMVB.DLL has not been tested by us; however it is known to work at specific customer sites.

To use the interface, copy JOBADMVB.DLL and CF8JOBADM.DLL to your VB working directory, and in VB, go to Project/References and browse to select JOBADMVB.DLL. You can then check the connections by writing code such as the following:

Private Sub Command1_Click()

Dim func As String

Dim parm1 As String * 256

Dim parm2 As String * 256

Dim parm3 As Integer

Dim res As Integer

func = "CreateInstance"

parm1 = "Default"

parm2 = ""

parm3 = 0

res = JobDllVB(func, parm1, parm2, parm3)

If res > 0 Then

  MsgBox Str$(res) + " " + parm1

Else

  MsgBox Str$(res)

End If

End Sub

COM Object

An interface is provided to allow CF8JOBADM.DLL to be called from any application or script which can call a COM object.

This interface is implemented in CF8JOBADMCOM.OCX, and is named JobOcxEntry.  The job function name and three parameters are the same as described above for the C interface described above. Use your normal compiler tools to generate a type library import files from the OCX.

.NET Interface

The functions in CF8JOBADM.DLL can also be called as unmanaged code from a .NET application.  The following C# code can be used to create the link from your application to the DLL:

using System;

using System.Text;

using System.Runtime.InteropServices;

 

namespace CF8JOB

{

 public class CF8JobadmWrapper

 {

         [DllImport("CF8JOBADM.DLL", EntryPoint="JobDllEntryU", CharSet = CharSet.Unicode)]

         private static extern int JobDllEntry( string func,

           StringBuilder parm1, StringBuilder parm2, int parm3);

 

         public int JobNetEntry(string func, StringBuilder parm1,

           StringBuilder parm2, int parm3)

         {

                 return JobDllEntry(func, parm1, parm2, parm3);

         }

 }

}

Be sure to set a suitable length for the parm1 and parm2 to allow the expected value to be returned.

Infobox Interface

The functions in CF8JOBADM.DLL can be called directly from an infobox.  The main purpose of this feature is to allow infobox logic to be used to provision job owners and job instances more easily for new jobs. Do not use infobox DLL calls to attempt to modify a file which may be open in COPIAFACTS.  At best this will fail, but it may have other unwanted side effects.

To use this interface, assign to variables as follows:

J_PARM1Assign the Parm1 value to this variable before calling the DLL.  The value will be truncated to 255 characters if longer.
J_PARM2Assign the Parm2 value to this variable before calling the DLL.  The value will be truncated to 255 characters if longer.
J_PARM3Assign the Parm3 value to this variable before calling the DLL.  The value will be converted to a decimal integer, and if it contains non-numeric characters the result is undefined.
JOB_DLL_CALLAssign the DLL function name to this variable to actually call the function.  The numeric result from the function is placed in the DLL_RESULT variable.  Depending on the function, the variables J_PARM1 and J_PARM2 may be set to new values, again truncated to 255 characters.