SSubmitJob function

The SSubmitJob function submits a request to KCM Core using TCP/IP sockets as a communication mechanism.

BOOL WINAPI SSubmitJob (
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
void  (*Progress) (TCHAR *)  // callback for progress messages
);

The SSubmitJob function has the following parameters:

• Host

  Pointer to a null-terminated string that contains the name of the server running KCM Core. You can specify the name 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. You can specify the port either in a numerical format or as a Service name resolved through available Service databases.

• JobID

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

• Sync

  Specifies whether 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 SSubmitJob function returns when KCM Core has queued the request. When the Sync parameter is TRUE, the SSubmitJob 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.

• Progress

  Pointer to a callback function called by SSubmitJob whenever the server sends back a progress message. This progress message is passed as parameter to the Progress function.

  SSubmitJob ignores NULL progress messages.

If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. The buffer indicated by Result contains an error message explaining the cause of the failure.

The string passed to the Progress function is a static buffer and is released by the SSubmitJob function after the Progress function returns.

SSubmitJob sends 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.