Batch Requests#

intGRBabortbatch(GRBbatch*batch)#

This function instructs the Cluster Manager to abort the processing ofthis batch request, changing its status to ABORTED. Please refer to theBatch Status Codes section for furtherdetails.

Return value:

A non-zero return value indicates that a problem occurred while aborting the batch request.Refer to theError Codes tablefor a list of possible return values. Details on the error can be obtainedby callingGRBgeterrormsg.

Arguments:

• batch – The batch that will be aborted.

Example:

/* request to abort the batch */error=GRBabortbatch(batch);if(error)gotoQUIT;

intGRBdiscardbatch(GRBbatch*batch)#

This function instructs the Cluster Manager to remove all informationrelated to the batch request in question, including the stored solutionif available. Further queries for the associated batch request will failwith error codeDATA_NOT_AVAILABLE. Use thisfunction with care, as the removed information can not be recoveredlater on.

Return value:

A non-zero return value indicates that a problem occurred while discarding the batch. Refer to theError Codes tablefor a list of possible return values. Details on the error can be obtainedby callingGRBgeterrormsg.

Arguments:

• batch – The batch that will be discarded.

Example:

/* discard the batch object in the manager */error=GRBdiscardbatch(batch);if(error)gotoQUIT;

intGRBfreebatch(GRBbatch*batch)#

Free a batch structure and release the associated memory.

Return value:

A non-zero return value indicates that a problem occurred while freeing the batch. Refer to theError Codes tablefor a list of possible return values. Details on the error can be obtainedby callingGRBgeterrormsg.

Arguments:

• batch – The batch structure to be freed.

Example:

GRBfreebatch(batch);

intGRBgetbatch(GRBenv*env,constchar*BatchID,GRBbatch**batchP)#

Given aBatchID, as returned byGRBoptimizebatch, and a Gurobi environment thatcan connect to the appropriate Cluster Manager (i.e., one whereparametersCSManager,UserName, andServerPassword have been setappropriately), this function returns aGRBbatch structure. With it, you can querythe current status of the associated batch request and, once the batchrequest has been processed, you can query its solution. Please refer totheBatch Optimization section for detailsand examples.

Return value:

A non-zero return value indicates that a problem occurred while creating aGRBbatch structure.Refer to theError Codes tablefor a list of possible return values. Details on the error can be obtainedby callingGRBgeterrormsg.

Arguments:

• env – The environment in which the new batch structure should becreated.

• BatchID – ID of the batch you want to access.

• batchP – The location in which the pointer to the batch structureshould be placed.

Example:

/* create batch-object */error=GRBgetbatch(env,BatchID,&batch);if(error)gotoQUIT;

GRBenv*GRBgetbatchenv(GRBbatch*batch)#

Retrieve the environment associated with a batch.

Return value:

The environment associated with the batch. ANULLreturn value indicates that there was a problem retrieving theenvironment.

Arguments:

• batch – The batch from which the environment should be retrieved.

Example:

GRBenv*env=GRBgetbatchenv(batch);

intGRBgetbatchintattr(GRBbatch*batch,constchar*attrname,int*valueP)#

Query the value of an integer-valued batch attribute.

Return value:

A non-zero return value indicates that a problem occurred while querying the attribute. Refer to theError Codes tablefor a list of possible return values. Details on the error can be obtainedby callingGRBgeterrormsg.

Arguments:

• batch – A batch structure, typically created by routineGRBgetbatch.

• attrname – The name of an integer-valued batch attribute. Availableattributes are listed and described in theAttributes section of this document.

• valueP – The location in which the current value of the requestedattribute should be placed.

Example:

/* query the last error code */error=GRBgetbatchintattr(batch,"BatchErrorCode",&errorCode);if(error||!errorCode)gotoQUIT;

Note that all Batch attributes arecached locally, and are only updated when you create a client-side batchobject or when you explicitly update this cache (by calling theappropriate update function -GRBupdatebatch forC,update forPython, etc.).

intGRBgetbatchjsonsolution(GRBbatch*batch,char**jsonsolP)#

This function retrieves the solution of a completed batch request from aCluster Manager. The solution is returned as aJSON solutionstring. For this call to succeed, the status of the batchrequest must be COMPLETED. Note further that the result file storedCluster Manager side must be gzip-compressed and exactly one result fileshould be associated with this batch; for batches submittedprogrammatically through the API both will be the case. Please refer totheBatch Status Codes section for furtherdetails.

Return value:

A non-zero return value indicates that a problem occurred while querying the batch solution.Refer to theError Codes tablefor a list of possible return values. Details on the error can be obtainedby callingGRBgeterrormsg.

Arguments:

• batch – The batch to query.

• jsonsolP – The location in which the pointer to the newly createdJSON string should be placed.

Important

On Windows, the string returned inbuffP is allocated in a differentheap from the calling program. You must callGRBfree to free it.

Example:

/* print JSON solution into string */error=GRBgetbatchjsonsolution(batch,&jsonsol);if(error)gotoQUIT;printf("JSON solution: %s\n",jsonsol);

intGRBgetbatchstrattr(GRBbatch*batch,constchar*attrname,char**valueP)#

Query the value of a string-valued batch attribute.

Return value:

A non-zero return value indicates that a problem occurred while querying the attribute. Refer to theError Codes tablefor a list of possible return values. Details on the error can be obtainedby callingGRBgeterrormsg.

Arguments:

• batch – A batch structure, typically created by routineGRBgetbatch.

• attrname – The name of a string-valued batch attribute. Availableattributes are listed and described in theAttributes section of this document.

• valueP – The location in which the current value of the requestedattribute should be placed.

Example:

/* query the last error message */error=GRBgetbatchstrattr(batch,"BatchErrorMessage",&errorMsg);if(error)gotoQUIT;

Note that all interface routines that return string-valued attributesare returning pointers into internal Gurobi data structures. The usershould copy the contents of the pointer to a different data structurebefore the next call to a Gurobi library routine. The user should alsobe careful to never modify the data pointed to by the returned characterpointer.

Note that all Batch attributes arecached locally, and are only updated when you create a client-side batchobject or when you explicitly update this cache (by calling theappropriate update function -GRBupdatebatch forC,update forPython, etc.).

intGRBoptimizebatch(GRBmodel*model,char*BatchID)#

Submit a new batch request to the Cluster Manager. Returns the BatchID(a string), which uniquely identifies the job in the Cluster Manager andcan be used to query the status of this request (from this program orfrom any other). Once the request has completed, theBatchID canalso be used to retrieve the associated solution. To submit a batchrequest, you must tag at least one element of the model by setting oneof theVTag,CTag orQCTag attributes.For more details on batch optimization, please refer to theBatch Optimization section.

Note that this routine will process all pending model modifications.

Return value:

A non-zero return value indicates that a problem occurred while submit a batch request. Refer to theError Codes tablefor a list of possible return values. Details on the error can be obtainedby callingGRBgeterrormsg.

Arguments:

• model – The model to optimize in batch mode. Note that this routineonly reports whether the batch request ran into an error.

• BatchID – On success, the location in which theBatchID ofthe newly created batch request should be stored. The pointer must pointto a string of lengthGRB_MAX_STRLEN+1 or more.

Example:

/* submit batch request to the Manager */error=GRBoptimizebatch(model,BatchID);if(error)gotoQUIT;

intGRBretrybatch(GRBbatch*batch)#

This function instructs the Cluster Manager to retry optimization of afailed or aborted batch request, changing its status to SUBMITTED.Please refer to theBatch Status Codessection for further details.

Return value:

A non-zero return value indicates that a problem occurred while retrying the batch. Refer to theError Codes tablefor a list of possible return values. Details on the error can be obtainedby callingGRBgeterrormsg.

Arguments:

• batch – The batch to retry.

Example:

/* retry the batch request */error=GRBretrybatch(batch);if(error)gotoQUIT;

intGRBupdatebatch(GRBbatch*batch)#

All Batch attribute values are cached locally, so queries return thevalue received during the last communication with the Cluster Manager.This function refreshes the values of all attributes with the valuescurrently available in the Cluster Manager (which involves networkcommunication).

Return value:

A non-zero return value indicates that a problem occurred while updating the batch request.Refer to theError Codes tablefor a list of possible return values. Details on the error can be obtainedby callingGRBgeterrormsg.

Arguments:

• batch – The batch that will be updated.

Example:

/* update local attributes */error=GRBupdatebatch(batch);if(error)gotoQUIT;

intGRBwritebatchjsonsolution(GRBbatch*batch,constchar*filename)#

This function returns the stored solution of a completed batch requestfrom a Cluster Manager. The solution is returned in a gzip-compressedJSON file. The file name you provide must end with a .json.gz extension.The JSON format is described in theJSON solution format section. Note that for this call to succeed, the status ofthe batch request must be COMPLETED. Note further that the result filestored Cluster Manager side must be gzip-compressed and exactly oneresult file should be associated with this batch; for batches submittedprogrammatically through the API both will be the case. Please refer totheBatch Status Codes section for furtherdetails.

Return value:

A non-zero return value indicates that a problem occurred while writing the JSON solution stringinto the given filename. Refer to theError Codes tablefor a list of possible return values. Details on the error can be obtainedby callingGRBgeterrormsg.

Arguments:

• batch – The batch request from qhere to query its solution.

• filename – The name of the file in which to store the JSON solution.It must be a file name ending with the.json.gz extension.

Example:

/* save solution into a file */error=GRBwritebatchjsonsolution(batch,"batch-sol.json.gz");if(error)gotoQUIT;