SSubmitJobEx4 and SSubmitJobEx5 functions

The SSubmitJobEx4 and SSubmitJobEx5 functions submit a request to KCM Core using TCP/IP sockets as a communication mechanism. Compared to the SSubmitJob function, these functions add support for the ExchangeData and ValidateFileName callback APIs and for specifying KCM Core session IDs. The two functions provide the same functionality, except that the callback functions for SSubmitJobEx4 use the cdecl calling convention while the callback functions for SSubmitJobEx5 use the stdcall calling convention.

These functions replace the older SSubmitJobEx, SSubmitJobEx2, and SSubmitJobEx3 functions which are still available as a convenience, but deprecated. As these older functions should not be used in new installations, their functionality is not described in this guide.

BOOL WINAPI SSubmitJobEx4 (
TCHAR      *Host,	     // pointer to host
TCHAR      *Port,	     // pointer to port
TCHAR      *JobID,	     // pointer to Job Identifier
BOOL        Sync,	     // wait for request to finish
TCHAR     **Parameters,  // parameter list, starting with
                         // the name of the requested Service
TCHAR      *Result,	     // buffer for result text
int         Length,	     // size of buffer
SUBMITJOB4 *Extended     // extended parameters
);
BOOL WINAPI SSubmitJobEx5 (
TCHAR      *Host,	     // pointer to host
TCHAR      *Port,	     // pointer to port
TCHAR      *JobID,	     // pointer to Job Identifier
BOOL        Sync,	     // wait for request to finish
TCHAR     **Parameters,  // parameter list, starting with
                         // the name of the requested Service
TCHAR      *Result,	     // buffer for result text
int         Length,	     // size of buffer
SUBMITJOB5 *Extended     // extended parameters
);

The functions have the following parameters:

• Host

  Pointer to a null-terminated string that contains the name of the server running KCM Core. The name can be specified either in (IPv4) Internet Protocol dotted address notation (a.b.c.d) or as a resolvable host name.

• Port

  Pointer to a null-terminated string that contains the name of the port to connect to. The port can be specified either in a numerical format or as a Service name resolved through any available Service databases.

• JobID

  Pointer to a null-terminated string that contains the Job Identifier for the job.

• Sync

  Specifies whether or not the function should wait until the job has been serviced. This parameter can have one of the following values:

  Value	Meaning
  FALSE	The function returns as soon as the request has been queued for processing.
  TRUE	The function waits until the request has been processed by KCM Core.

  When the Sync parameter is FALSE, the SSubmitJobEx4 function returns when KCM Core has queued the request. When the Sync parameter is TRUE, the SSubmitJobEx4 function returns when KCM Core has finished servicing the request.

• Parameters

  Pointer to a null-terminated list of string pointers. Every string pointer in this list points to a parameter passed with the job to KCM Core. The first parameter should be the name of the requested Service. For all parameters, the meaning of the empty string ("") is that the parameter is not passed at all, and KCM Core substitutes the default value or generates an error if no default value has been specified.

  If Parameters is NULL, no parameters are passed with the job.
• Result

  Pointer to a buffer that receives an error message if the submission of the job or the processing of the job failed. The error message placed in the Result buffer on failure will be truncated if the buffer is too small. A size of at least 1024 characters is advised.

• Length

  Size of the buffer indicated by Result in characters, not bytes.

• Extended

  Pointer to a SUBMITJOB4 (for SSubmitJobEx4) or SUBMITJOB5 (for SSubmitJobEx5) data structure that holds additional parameters to the function.

The string passed to the Progress function is a static buffer and will be released by the SSubmitJobEx4/ SSubmitJobEx5 function after the Progress function returns.

The SSubmitJobEx4 and SSubmitJobEx5 functions send the name of the user logged on at the workstation as the User of the job.

QuickInfo

Header: Declared in s_api.h.

Import Library: Use sock_api.lib.

Unicode: Implemented as both Unicode and ASCII.