16.3.15 Job List Information Acquisition API/EE [Windows]This section explains the job list information acquisition API/EE (Mp_ListJob_Ex).
Synopsis
#include "f3cuapi.h"
long Mp_ListJob_Ex (char *rhost,
long mode,
struct Mp_JOBINF_1 *jobinf[ ],
char *userforadmin,
int system_num)Description
This API obtains a list of job information in Systemwalker Operation Manager EE. It obtains the information on all the jobs that are owned by the user who issued this function. If a system administrator (users belonging to the Administrators group) issued this function, then all the job information on every server that exist on the server where Systemwalker Operation Manager is installed is gathered. However, when userforadmin is specified, only the information on the jobs that are owned by the corresponding user will be obtained.
Parameters
rhost
Specify NULL here.
mode
Specify one of the following process modes. After GETJOB, you must always specify FREEJOB.
Obtains the job list information.
Frees the area that was used for the job list information obtained by GETJOB.
jobinf[ ]
Specify the area address to which the address of the job information structure (Mp_JOBINF_1) array will be notified.
Specify the area address to which the address of the job information structure array was notified in GETJOB. After issuing GETJOB and until the issuing of FREEJOB, you should not change the contents of the area.
userforadmin
Specify this parameter when a system administrator (users belonging to the Administrators group) obtains only the users' jobs status. Specify the owner name of the obtained job. If the owner name is not specified, NULL should be specified.
system_num
Specify operating target subsystem number using a range of 0 to 9.
Return Values
Return Value | Meaning | Action |
|---|---|---|
0 | The relevant job does not exist. | - |
1 or greater | The job information list was obtained successfully. The number of jobs was returned. | - |
-1 | A system error occurred. | Collect "Job Execution Control" information with the maintenance information collection tool and contact a Fujitsu SE. |
-1000 or less | Processing was aborted because an error was detected in Job Execution Control. Error messages can be obtained using the error message acquisition API. | Use the error message acquisition API to obtain the error message and take whatever action is required. |
Caution
When the argument is pointing to an invalid address, this function ends abnormally, and no operations will be defined.
Format of the Job Information Structure (Mp_JOBINF_1)
The following is the format of the job information structure:
This structure is defined in the INCLUDE file "f3cuapi.h".
typedef struct _Mp_JOBINF_1{
char jobname[]; /* job name */
char jobhost[]; /* submission source host name */
long jobno; /* job number */
char user[]; /* job owner and user */
char queue[]; /* queue name */
long jobtype; /* job type */
long status; /* job status */
char comment[]; /* comment entered during the submission process */
}Mp_JOBINF_1
Following provides the explanations about each item.
The job name is set.
The submission source host name is set.
The job number is set.
The job owner and user are set.
The queue name is set.
The job type is set. The following types can be set for a job:
Value | Type |
|---|---|
1 | Demand job |
2 | Schedule job |
The job status is set. The following statuses can be set for a job:
Value | Status |
|---|---|
1 | Waiting for execution |
2 | Execution on hold |
3 | Executing |
4 | Output on hold |
The comment specified during the submission process is set.
Program Example
Below is an example program of the job list information acquisition API/EE:
#include <windows.h>
#include <stdio.h>
#include "f3cuapi.h"
int main (int argc, char **argv)
{
Mp_JOBINF_1 *jobinf = 0;
Mp_JOBINF_1 *jinf = 0;
long mode;
long idx;
long rtn = 0;
char errmsg[256+1];
int system_num;
/*
* initialization working area
*/
memset(errmsg, 0x00, sizeof(errmsg));
mode = GETJOB;
/*
* call Mp_ListJob_Ex() API
*/
system_num = 0;
rtn = Mp_ListJob_Ex (NULL, mode, &jobinf, NULL, system_num);
/*
* check return code of Mp_ListJob_Ex() API
*/
if (rtn == -1) {
printf ("GetLastError() is %d.\n", GetLastError());
return (1);
} else if (rtn <= -1000) {
printf ("Error code is %d.\n", rtn);
Mp_GetMJESerror (errmsg);
printf ("errmsg = %s\n", errmsg);
return (1);
} else if (rtn == 0) {
printf ("Job is nothing.\n", rtn);
return (0);
}
jinf = jobinf;
printf("job name jobno user name status\n");
for (idx = 0; idx < rtn; idx++) {
printf("%20.20s %5.5d %20.20s ",
jinf->jobname, jinf->jobno, jinf->user);
switch(jinf->status) {
case 1 :
printf("waiting ");
break;
case 2 :
printf("holding ");
break;
case 3 :
printf("running ");
break;
case 4 :
printf("outhold ");
break;
}
printf("\n");
jinf++;
}
mode = FREEJOB;
/*
* call Mp_ListJob_Ex() API
*/
Mp_ListJob_Ex (NULL, mode, &jobinf, NULL, system_num);
return(0);
}