16.2.8 Job Net Execution API/EE [Windows]

This section explains the job net execution API/EE (JSNetStartEx).

Synopsis

#include "f3csbNetStartEx.h"
int JSNetStartEx (char *project,
           char *netname,
           char *text,
           int kind,
           char *parm,
           int action,
           int system_num);

Description

With the features of job net execution API/EE, you can:

Start up a job net from a user application
Output a desired message (event) at job net startup time
Pass a desired parameter to the job
Wait to start up a job net by connecting to the job net startup queue when the same job net has already been running

Parameters

project

Specify the project name of the project that has job nets to be manipulated. As for the specifiable project name, the API execution user must be able to use the project of that name.

This can be omitted if there is only one project having the job net that the API execution user can use. In this case, NULL must be specified.

netname

Specify the name of a job net to be started up. This cannot be omitted.

text

Specify the string to be output to the event log with up to 256 bytes. If NULL is specified, the message won't be output to the event log.

kind

Specify the type of the messages to be output to the event log. The following three types are available to choose from. If the text parameter is NULL, this parameter will be ignored.

LOG_INFO:: Message at information level (message identifier:10000)

LOG_WARN:: Message at warning level (message identifier:10001)

LOG_ERR:: Message at error level (message identifier:10002)

parm

Specify the parameter string to be passed to the job with up to 512 bytes.

The parameters specified in all the jobs in the job net to be started up will be passed.

action

Specify the actions to take when the job net specified in the netname parameter is already running. The instructions and their meaning are shown below:

ACT_QUE: Connects to the job net startup queue.

ACT_NO: Cancels the startup request.

system_num

Specify operating target subsystem number using a range of 0 to 9.

Return Values

Return Value	Meaning	Action
0	The startup request was accepted normally, and the job net started up.	-
1	Connected to the job net startup queue (when ACT_QUE is specified), because the job net was already running.	-
2	The startup request was cancelled (when ACT_NO is specified), because the job net was already running.	-
-1	The project name specified in the project parameter is either illegal or no such project name exists.	Set the correct project name.
-2	The job net name specified in the netname parameter is either illegal or no such job net name exists.	Set the correct job net name.
-3	The message type specified in the kind parameter is illegal.	Set the correct message type.
-4	The operation was illegal for executing of the job net specified in the action parameter.	Set the correct action.
-5	The character string specified in the text parameter is too long.	The character string specified as the text parameter can be no more than 256 bytes long.
-6	The character string specified in the parm parameter is too long.	The character string specified as the param parameter can be no more than 512 bytes long.
-7	The job net could not be started because it has been in Paused or Disabled. Cancel the Paused or Disabled for the job net and re-execute. Otherwise, the job net could not be started because it is subordinate to a group.	Take one of the following measures and then perform the operation again: Check the status of the job net. Remove the job net from the group.
-8	The job net could not be started because the startup processing was congested. Wait for a while and re-execute it.	Wait a few moments and attempt the operation again.
-9	Either the Jobscheduler service is not running or the job net execution API function is disabled. Enable the job net execution API function and start up the Jobscheduler service, then re-execute.	Take one of the following measures and then perform the operation again: Start the Jobscheduler service. Reset the startup parameter of the Jobscheduler service and then restart the Jobscheduler service.
-10	The Jobscheduler service is carrying out shutdown procedures. Start the Jobscheduler service after the procedures have stopped, then re-execute.	After the Jobscheduler service has stopped, restart the Jobscheduler service and then attempt the operation again.
-20	Failed to accept the job net startup request. Refer to the event log for details and re-execute after removing the cause of the error.	Use the error details output to the event log to remove the cause of the problem and then attempt the operation again.

Required Files

The following files are required to use the job net execution API shown above:

[Windows x86]

LIB:: f3csbNetStartEx.lib

INCLUDE:: f3csbNetStartEx.h

[Windows x64]

LIB:: f3csbNetStartEx_x64.lib

INCLUDE:: f3csbNetStartEx_x64.h

These files are stored under "MpWalker.JM\lib" and "MpWalker.JM\include" where Systemwalker Operation Manager was installed.

Program Example

Below is an example program of the job net execution API/EE:

#include <windows.h>
#include <stdio.h>
#include <stdlib.h>
#include "f3csbNetStartEx.h"

void main()
{
    int ret;

    ret = JSNetStartEx("user1",           // project name
                       "net001",          // jobnet name
                       "net001 start.",   // messages for event log
                       LOG_INFO,          // kind of event log : information
                       "-d c:\\data -x",  // parameters for jobs
                       ACT_QUE,           // if jobnet is running, that is queued.
                       1);                // sub system number
    if (ret == 0) {
        printf("jobnet(net001) is started.\n");
    }
    else if (ret == 1) {
        printf("jobnet(net001) is queued, because now running.\n");
    }
    else if (ret < 0) {
        printf("ERROR: return code = %d\n", ret);
        exit(1);
    }
    exit(0);
}