16.2.10 Job Net Start Time Change API/EE

This section explains the job net start time change API/EE (Mp_JobschCtlStartTimeEx).

Synopsis

[Windows]

#include "f3csbJobschControlEx.h"
int Mp_JobschCtlStartTimeEx (
       int mode,
       struct jobsch_start_time *get_time,
       struct jobsch_start_time *before_time,
       struct jobsch_start_time *set_time,
       char *project_name,
       char *jobnet_name,
       int system_num) ;

[UNIX]

#include "jobschapiex.h"
int Mp_JobschCtlStartTimeEx (
        int mode,
        struct jobsch_start_time *get_time,
        struct jobsch_start_time *before_time,
        struct jobsch_start_time *set_time,
        char *project_name,
        char *jobnet_name,
        int system_num) ;

Description

This API enables functions for obtaining or changing the job net start time to be used from a C language interface in Systemwalker Operation Manager EE.

The start time acquisition process stores the start time of the specified job net in the area specified by the get_time parameter.

The start time change process changes the start time of the specified job net to the value specified by the set_time parameter and then the modified start time and startup day information are used to reschedule the scheduled startup date/time.

Parameters

mode

Specify the operation mode of this API. This option cannot be omitted.

0:: Obtains the start time. The before_time and set_time parameters will be ignored. To use this mode, the API must be executed by a user with the reference right (or a higher right) for the project to which the job net belongs.

1:: Changes the start time. The get_time parameter will be ignored. To use this mode, the API must be executed by a user with the update or change right for the project to which the job net belongs.

get_time

Specify the area of the jobsch_start_time structure that will obtain the start time. NULL is specified if this parameter is omitted. This parameter cannot be omitted if 0 is specified for the mode parameter. If this API terminates normally when 0 is specified for the mode parameter, the acquisition result will be stored in the structure. Refer to the explanation of the time parameter of the jobsch_start_time structure for more information about the value that is stored.

before_time

Specify the pre-change startup time. Refer to the explanation for the "time" parameter in the "jobsch_start_time" structure for the value to be specified. NULL is specified if this parameter is omitted. This parameter cannot be omitted if 1 is specified for the mode parameter. The specified start time type and start time are compared with the start time type and start time specified for the job net, and the start time is changed only if these values match. In the event of a mismatch, the API will return an error.

set_time

Specify the start time to be set. Refer to the time parameter in the jobsch_start_time structure for the value to be specified. NULL is specified if this parameter is omitted. This parameter cannot be omitted if 1 is specified for the mode parameter.

project_name

Specify the name of the project to which to the job net to be manipulated belongs. Only the names of projects that can be used by the user running the API can be specified. This parameter can be omitted if only one of the projects that can be used by the user running the API has job nets registered with it. NULL is specified if this parameter is omitted.

jobnet_name

Specify the name of the job net to be manipulated. This parameter cannot be omitted.

system_num

Specify the subsystem to be operated as a number between 0 and 9. This parameter cannot be omitted.

Return Values

Return Value	Meaning	Action
0	Normal termination.	-
4	The pre-change start time of the specified job net does not match.	Specify the same start time type and start time as the job net to be changed in before_time.
8	The execution conditions of the job net to be obtained do not specify a start time. Or, the execution conditions of the specified job net differ from the start time type to be changed.	Specify a job net with a specified start time as the job net to be obtained. When changing the start time, specify the same type in set_time as the start time of the relevant job net.
12	The specified job net belongs to a group.	Specify a job net that does not belong to a group.
16	The status of the specified job net is either "executing", "warning" or "end delayed". The specified job net is running.	Perform the operation again after the status of the job net has changed.
24	The job net is using a different character encoding from that used by Systemwalker.	Ensure that the execution environment of the program invoking the API uses the same character encoding as that used by Systemwalker.
28	The Jobscheduler service/daemon is not running.	Start the Jobscheduler service/daemon and perform the operation again.
32	There is an error in the parameter specifications or the user privileges, or the specified project or job net does not exist.	Take whichever of the following actions is necessary: Set the correct parameter (operation mode, start time, project name or job net name). Grant the executing user the correct project access privileges.
36	Fatal error occurred.	A system error may have occurred. Check the event log or syslog for any system abnormalities. If an error occurs, collect Jobscheduler information using the Maintenance Information Collection Tool, and then contact a Fujitsu SE. If none are found, the problem may only have been temporary, so perform the operation again.
40	The specified job net is being manipulated or changed.	Perform the operation again after the status of the job net has changed.

Format of the jobsch_start_time structure

The format of the jobsch_start_time structure is as follows:

struct jobsch_start_time {
     int type;
     char rsv1[4];
     char time[128];
     char rsv2[24];
} ;

type:

The following table lists the values that indicate the different start time types.

Value	Type
1	A job net with only one start time specified
2	A job net with multiple start times specified
3	A job net with an execution interval

rsv1:

Reserved. (Not used.)

time:

A character string that indicates the start time. The format of this parameter differs according to the start time type.

1: When the job net has only one start time specified

A 4-byte (5 bytes with the NULL character) string of the format "HHMM" (representing hours and minutes).

Example) "0900"

2: When the job net has more than one start time specified

A character string up to 29 bytes long (30 bytes including the NULL character) that is made up of 4-byte strings of the format "HHMM" (representing hours and minutes) separated by commas. (Six 4-byte strings + five commas + one NULL character = 30 bytes)

Example) "0900,1100,1300,1500,1700"

3: When the job net has an execution interval

A character string up to 13 bytes long (14 bytes including the NULL character) of the format "HHMM,HHMM,n" (representing start time, end time and execution interval).Each parameter is separated by a comma. The start and end times consist of 4-byte strings of the format "HHMM" (representing hours and minutes) and the execution interval in minutes is represented by a character string between one and three bytes long. The minimum execution interval is 1 and the maximum is 240 (minutes).

Example) "0900,1700,60"

rsv2:

Reserved. (Not used.)

Required Files

The following files are needed when using the Job Net Start Time Change API.

[Windows x86]

LIB:: Systemwalker Operation Manager installation directory\MpWalker.JM\lib\f3csbJobschControlEx.lib

INCLUDE:: Systemwalker Operation Manager installation directory\MpWalker.JM\include\f3csbJobschControlEx.h

[Windows x64]

LIB:: Systemwalker Operation Manager installation directory\MpWalker.JM\lib\f3csbJobschControlEx_x64.lib

INCLUDE:: Systemwalker Operation Manager installation directory\MpWalker.JM\include\f3csbJobschControlEx_x64.h

[Common to Solaris 32-bit and Linux x86]

LIB:: /opt/FJSVJOBSC/usr/lib/libjobschex.so

INCLUDE:: /opt/FJSVJOBSC/usr/include/jobschapiex.h

[Solaris 64-bit]

LIB:: /opt/FJSVJOBSC/usr/lib/libjobschex_64.so

INCLUDE:: /opt/FJSVJOBSC/usr/include/jobschapiex_64.h

[Linux x64]

LIB:: /opt/FJSVJOBSC/usr/lib/libjobschex_x64.so

INCLUDE:: /opt/FJSVJOBSC/usr/include/jobschapiex_x64.h

Privileges needed for execution

The executing user must be a system administrator or a user with permission to access the target project.

Cautions

The executing user must be a system administrator or a user with permission to access the target project.
This API is only valid for job nets with the execution conditions indicated by the start time in the jobsch_start_time structure.
The start time type cannot be changed.
The start time of a job net belonging to a group cannot be changed.
Programs that use this API must have the correct time zone setting.
This API will return an error if it is called by a program specified with a different locale from that in which Systemwalker Operation Manager is operating.

Program Example

A program that uses the job net start time change API is provided below.

#include <stdio.h>
#include <stdlib.h>
#include <time.h>
#include <locale.h>
#include <string.h>
#include "jobschapiex.h"

main ()
{
    int ret;
    char t_str[8];
    struct jobsch_start_time b_time, a_time;

    tzset ();
    setlocale (LC_ALL, "");

    memset(&b_time, 0x00, sizeof(b_time));

    ret = Mp_JobschCtlStartTimeEx (
                        0,         /* mode : GET       */
                        &b_time,   /* get start time   */
                        NULL,      /* NULL             */
                        NULL,      /* NULL             */
                        "test",    /* project name     */
                        "net1",    /* jobnet name      */
                        1);        /* sub system number*/
    if (ret == 0) {
        printf ("Start type is %d.\n", b_time.type);
        printf ("Start time is %s.\n", b_time.time);
    }
    else{
        printf ("ERROR: get return code = %d\n", ret);
        exit(1);
    }

    memset(&a_time, 0x00, sizeof(a_time));
    a_time.type = b_time.type;
    strcpy(a_time.time, b_time.time);
    strcat(a_time.time, ",1900");

    ret = Mp_JobschCtlStartTimeEx (
                        1,          /* mode : CHANGE    */
                        NULL,       /* NULL             */
                        &b_time,    /* before time      */
                        &a_time,    /* set time         */
                        "test",     /* project name     */
                        "net1",     /* jobnet name      */
                        1);         /* sub system number*/
    if (ret == 0) {
        printf ("Change type is %d.\n", a_time.type);
        printf ("Change time is %s.\n", a_time.time);
    }
    else{
        printf ("ERROR: set return code = %d\n", ret);
        exit(1);
    }

    exit(0);
}