Batch Requests#

int GRBabortbatch(GRBbatch *batch)#

This function instructs the Cluster Manager to abort the processing of this batch request, changing its status to ABORTED. Please refer to the Batch Status Codes section for further details.

Return value:

A non-zero return value indicates that a problem occurred while aborting the batch request. Refer to the Error Codes table for a list of possible return values. Details on the error can be obtained by calling GRBgeterrormsg.

Arguments:

  • batch – The batch that will be aborted.

Example:
/* request to abort the batch */
error = GRBabortbatch(batch);
if (error) goto QUIT;
int GRBdiscardbatch(GRBbatch *batch)#

This function instructs the Cluster Manager to remove all information related to the batch request in question, including the stored solution if available. Further queries for the associated batch request will fail with error code DATA_NOT_AVAILABLE. Use this function with care, as the removed information can not be recovered later on.

Return value:

A non-zero return value indicates that a problem occurred while discarding the batch. Refer to the Error Codes table for a list of possible return values. Details on the error can be obtained by calling GRBgeterrormsg.

Arguments:

  • batch – The batch that will be discarded.

Example:
/* discard the batch object in the manager */
error = GRBdiscardbatch(batch);
if (error) goto QUIT;
int GRBfreebatch(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 the Error Codes table for a list of possible return values. Details on the error can be obtained by calling GRBgeterrormsg.

Arguments:

  • batch – The batch structure to be freed.

Example:
GRBfreebatch(batch);
int GRBgetbatch(GRBenv *env, const char *BatchID, GRBbatch **batchP)#

Given a BatchID, as returned by GRBoptimizebatch, and a Gurobi environment that can connect to the appropriate Cluster Manager (i.e., one where parameters CSManager, UserName, and ServerPassword have been set appropriately), this function returns a GRBbatch structure. With it, you can query the current status of the associated batch request and, once the batch request has been processed, you can query its solution. Please refer to the Batch Optimization section for details and examples.

Return value:

A non-zero return value indicates that a problem occurred while creating a GRBbatch structure. Refer to the Error Codes table for a list of possible return values. Details on the error can be obtained by calling GRBgeterrormsg.

Arguments:

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

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

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

Example:
/* create batch-object */
error = GRBgetbatch(env, BatchID, &batch);
if (error) goto QUIT;
GRBenv *GRBgetbatchenv(GRBbatch *batch)#

Retrieve the environment associated with a batch.

Return value:

The environment associated with the batch. A NULL return value indicates that there was a problem retrieving the environment.

Arguments:

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

Example:
GRBenv *env = GRBgetbatchenv(batch);
int GRBgetbatchintattr(GRBbatch *batch, const char *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 the Error Codes table for a list of possible return values. Details on the error can be obtained by calling GRBgeterrormsg.

Arguments:

  • batch – A batch structure, typically created by routine GRBgetbatch.

  • attrname – The name of an integer-valued batch attribute. Available attributes are listed and described in the Attributes section of this document.

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

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

Note that all Batch attributes are cached locally, and are only updated when you create a client-side batch object or when you explicitly update this cache (by calling the appropriate update function - GRBupdatebatch for C, update for Python, etc.).

int GRBgetbatchjsonsolution(GRBbatch *batch, char **jsonsolP)#

This function retrieves the solution of a completed batch request from a Cluster Manager. The solution is returned as a JSON solution string. For this call to succeed, the status of the batch request must be COMPLETED. Note further that the result file stored Cluster Manager side must be gzip-compressed and exactly one result file should be associated with this batch; for batches submitted programmatically through the API both will be the case. Please refer to the Batch Status Codes section for further details.

Return value:

A non-zero return value indicates that a problem occurred while querying the batch solution. Refer to the Error Codes table for a list of possible return values. Details on the error can be obtained by calling GRBgeterrormsg.

Arguments:

  • batch – The batch to query.

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

Important

On Windows, the string returned in buffP is allocated in a different heap from the calling program. You must call GRBfree to free it.

Example:
/* print JSON solution into string */
error = GRBgetbatchjsonsolution(batch, &jsonsol);
if (error) goto QUIT;
printf("JSON solution: %s\n", jsonsol);
int GRBgetbatchstrattr(GRBbatch *batch, const char *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 the Error Codes table for a list of possible return values. Details on the error can be obtained by calling GRBgeterrormsg.

Arguments:

  • batch – A batch structure, typically created by routine GRBgetbatch.

  • attrname – The name of a string-valued batch attribute. Available attributes are listed and described in the Attributes section of this document.

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

Example:
/* query the last error message */
error = GRBgetbatchstrattr(batch, "BatchErrorMessage", &errorMsg);
if (error) goto QUIT;

Note that all interface routines that return string-valued attributes are returning pointers into internal Gurobi data structures. The user should copy the contents of the pointer to a different data structure before the next call to a Gurobi library routine. The user should also be careful to never modify the data pointed to by the returned character pointer.

Note that all Batch attributes are cached locally, and are only updated when you create a client-side batch object or when you explicitly update this cache (by calling the appropriate update function - GRBupdatebatch for C, update for Python, etc.).

int GRBoptimizebatch(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 and can be used to query the status of this request (from this program or from any other). Once the request has completed, the BatchID can also be used to retrieve the associated solution. To submit a batch request, you must tag at least one element of the model by setting one of the VTag, CTag or QCTag attributes. For more details on batch optimization, please refer to the Batch 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 the Error Codes table for a list of possible return values. Details on the error can be obtained by calling GRBgeterrormsg.

Arguments:

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

  • BatchID – On success, the location in which the BatchID of the newly created batch request should be stored. The pointer must point to a string of length GRB_MAX_STRLEN+1 or more.

Example:
/* submit batch request to the Manager */
error = GRBoptimizebatch(model, BatchID);
if (error) goto QUIT;
int GRBretrybatch(GRBbatch *batch)#

This function instructs the Cluster Manager to retry optimization of a failed or aborted batch request, changing its status to SUBMITTED. Please refer to the Batch Status Codes section for further details.

Return value:

A non-zero return value indicates that a problem occurred while retrying the batch. Refer to the Error Codes table for a list of possible return values. Details on the error can be obtained by calling GRBgeterrormsg.

Arguments:

  • batch – The batch to retry.

Example:
/* retry the batch request */
error = GRBretrybatch(batch);
if (error) goto QUIT;
int GRBupdatebatch(GRBbatch *batch)#

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

Return value:

A non-zero return value indicates that a problem occurred while updating the batch request. Refer to the Error Codes table for a list of possible return values. Details on the error can be obtained by calling GRBgeterrormsg.

Arguments:

  • batch – The batch that will be updated.

Example:
/* update local attributes */
error = GRBupdatebatch(batch);
if (error) goto QUIT;
int GRBwritebatchjsonsolution(GRBbatch *batch, const char *filename)#

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

Return value:

A non-zero return value indicates that a problem occurred while writing the JSON solution string into the given filename. Refer to the Error Codes table for a list of possible return values. Details on the error can be obtained by calling GRBgeterrormsg.

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) goto QUIT;