|
Job Admin DLL Overview |
  
|
|
Job Admin DLL Overview |
|
The Job Admin function library (F7JOBADM.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 F7JOBADM.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 a single entry point. All job functions are performed by passing a function name and up to three parameters to this entry point. An integer result is returned.
typedef int (*FFCB_JA)(char*,char*,char*,int);
FFCB_JA job_entry;
HANDLE hjobadm = 0;
hjobadm = LoadLibrary("F7JOBADM.DLL");
if (hjobadm) job_entry = (FFCB_JA)GetProcAddress(hjobadm,"JobDllEntry");
...
char function[64]; // function name, see list below
char parm1[256]; // first parameter, terminated '\0'
char parm2[256]; // second parameter, terminated '\0'
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. 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.
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 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 F7JOBADM.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 F7JOBADM.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 F7JOBADM.DLL to be called from any application or script which can call a COM object.
This interface is implemented in F7JOBADMCOM.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 F7JOBADM.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 F7JOB
{
public class F7JobadmWrapper
{
[DllImport("F7JOBADM.DLL", EntryPoint="JobDllEntry")]
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);
}
}
}
Topic url: http://www.copia.com/support/refmanual/index.html?jobadmindlloverview.htm