SSubmitJob

The SSubmitJob function submits a request to ITP/Server using TCP/IP sockets as 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

);

Parameters

Host

Pointer to a null-terminated string that contains the name of the server running ITP/Server. 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 numerical format or as a service name that is 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 will return as soon as the request has been queued for processing.
TRUE	The function will wait until the request has been processed by ITP/Server.

Parameters

Pointer to a null-terminated list of string pointers. Every string pointer in this list points to a parameter that is passed with the job to ITP/Server. 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 ITP/Server will substitute the default value (or generate 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.

Length

Size of the buffer indicated by Result in characters.

Progress

Pointer to a callback function that is 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.

Return values

When the Sync parameter is FALSE, the SSubmitJob function returns when ITP/Server has queued the request. When the Sync parameter is TRUE, the SSubmitJob function returns when ITP/Server has finished servicing the request.

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.

Remarks

The Length parameter contains the size of the Result buffer in characters, not bytes.

The error message that is 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.

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

The SSubmitJob will 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.