The Job Admin function library (CF9JOBADM.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. For special purposes the DLL functions may also be invoked from Windows command files using the JOBCALL program, and through scripting.
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 CF9JOBADM.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("CF9JOBADM.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
 | Always check the return value of every function you call. The possible error codes are listed or linked from the reference documentation for each function. |
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 CF9JOBADM.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 CF9JOBADM.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 CF9JOBADM.DLL to be called from any application or script which can call a COM object.
This interface is implemented in CF9JOBADMCOM.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 CF9JOBADM.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 CF9JOB
{
public class CF9JobadmWrapper
{
[DllImport("CF9JOBADM.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.
Scripting Interface (call job functions from an infobox)
The functions in CF9JOBADM.DLL can be called directly from an infobox. The main purpose of this feature is to allow scripting to be used to provision job owners and job instances more easily for new jobs. For details of how to call the interface, see the Job Admin Scripting topic.
