Description
Puts a hold on a batch job, preventing it from being executed until the hold is released. To apply a BATCH_USER_HOLD to the job, the caller must own the job. To apply a BATCH_MGR_HOLD, the caller must have operator privileges.
Syntax
DWORD BatchJobHold(LPCTSTR jobid, DWORD holdtype);
Parameters
LPCTSTR jobid |
Specifies the unique job-identification string. |
DWORD holdtype |
Indicates the hold type, either BATCH_USER_HOLD or BATCH_MGR_HOLD, or both. |
Return Values
BATCH_ERROR_NO_SUCH_JOB |
The system could not find the named job. |
BATCH_ERROR_BAD_JOB_NAME |
The jobid was null or the syntax was incorrect. |
BATCH_ERROR_OWNER_ACCESS_DENIED |
The user is trying to place a user hold on the job, but does not own the job. |
BATCH_ERROR_OPERATOR_ACCESS_DENIED |
The user is trying to place an operator hold on the job, but does not have at least operator privilege. |
BATCH_ERROR_INVALID_HOLD |
An invalid hold was specified. |
BATCH_ERROR_JOB_IS_RUNNING |
The job is already running. |
Example Program
#include <iostream.h>
#include "batchapi.h"
#define MAX_LENGTH 25
void main()
{
char * pTemp;
LPCTSTR JobId;
DWORD HoldType,ReturnVal;
cout << " STARTING THE EXECUTION OF BATCHJOBHOLD API "<< endl;
pTemp = new char[MAX_LENGTH];
if (pTemp == NULL){
cout << "unable to allocate the memory.\n Exiting"<<endl;
exit(0);
}
cout << " Enter the Job id for which to get the info ";
cin >> pTemp;
JobId = (const char *)pTemp;
cout << "Enter the Job Hold type wanted"
<< " 0 for BATCH_USER_HOLD 1 for BATCH_MGR_HOLD, 2 for both " << endl;
cin >> HoldType;
switch (HoldType)
{
case 0 : // the hold type required is only Userhold
ReturnVal=BatchJobHold( JobId, BATCH_USER_HOLD);
break;
case 1: // the hold type required is only ManagerHold
ReturnVal=BatchJobHold( JobId, BATCH_MGR_HOLD);
break;
case 2: // the hold type required is both Userhold and MangerHold
ReturnVal=BatchJobHold( JobId, BATCH_USER_HOLD | BATCH_MGR_HOLD);
break;
default:
cout << " THE HOLD TYPE IS UNKNOWN" << endl;
}
switch(ReturnVal)
{
case BATCH_ERROR_NO_SUCH_JOB :
cout << " The system could not find the named job. " << endl;
break;
case BATCH_ERROR_BAD_JOB_NAME :
cout << " The jobid was null or the syntax was incorrect. " << endl;
break;
case BATCH_ERROR_OWNER_ACCESS_DENIED :
cout << " The user is trying to place an user hold on the job, but does not own the job." << endl;
break;
case BATCH_ERROR_OPERATOR_ACCESS_DENIED :
cout << " The user is trying to place an operator hold on the job, but does not have at least operator privilege. " << endl;
break;
case BATCH_ERROR_INVALID_HOLD :
cout << " An invalid hold was specified. " << endl;
break;
case BATCH_ERROR_JOB_IS_RUNNING :
cout << " The job is already running. " << endl;
break;
default:
cout << "SUCCESSFUL HOLD OF THE REQUESTED JOB " << endl;
}
cout << " FINISHED THE EXECUTION OF BATCHJOBHOLD API "<< endl;
delete [] pTemp;
}