function batch_set

6.x batch.module batch_set($batch)
5.x batch.module batch_set($batch)

Create a new batch process.


$batch: This is an array containing everything we need to know about the batch we are creating. The non-required fields will be substituted with default values if left out.

  • operation :[REQUIRED] an array containing the callback function to execute plus any arguments. Ex: "operation" => array('my_function_to_call', array($arg1, $arg2))
  • finished_callback : an array containing the callback function and args to call once we are finished with the batch. Ex: "finished_callback" => array('my_finished_function', array($arg1, $arg2)) Generally, this field is optional. Since batches are usually set up in a form's submit handler, the default behavior is to go to whatever the form's destination was. You can override that here, however.
  • title : A title to display to the user while the batch is running. Ex: 'title' => t('Processing Batch...')
  • progress_message : A message to be displayed while the batch runs. It may use replacement patterns: @current, @total, @percent. Ex: 'progress_message' => 'Processed @current out of @total.' // Do NOT run through t()! It will be done at run time.
  • file : An optional file system path to a file where the batch's operation and/or finished functions reside. Ex: "file" => menu_get_module_path("my_example") . "/"
  • success_message : An optional message which will display to the user when the batch is complete. Ex: "The process is now complete."
  • display_percent : boolean, default FALSE. If set to TRUE, display percentage value in progress bar.

Return value

$batch_id - the id from batch_queue table for this batch.

5 calls to batch_set()
admin_process_all_definitions_form_submit in modules/admin/
Actually perform the refreshing of definitions.
batch_test_form_submit in modules/batch/
engagements_mass_sms_form_submit in modules/engagements/engagements.module
Our submit function. Our main task is simply to set off a batch routine.
stats_report_major_students_progress_form_submit in modules/stats/
Our submit handler. We will be setting up a new batch process.
system_confirm_db_updates_form_submit in modules/system/system.module
Perform the actual hook_update calls here, send the user to a completed page.


modules/batch/batch.module, line 301


function batch_set($batch) {
  global $user;

  if (!isset($batch ["title"])) {
    $batch ["title"] = t("Processing Batch...");
  if (!isset($batch ["progress_message"])) {
    $batch ["progress_message"] = t("Processed @current out of @total.");
  if (!isset($batch ["display_percent"])) {
    $batch ["display_percent"] = FALSE;

  // Add to the database
  $ser_batch = serialize($batch);

  $token = batch_get_token();
  db_query("INSERT INTO batch_queue (token, created, batch_data)
            VALUES ('?', '?', '?') ", $token, time(), $ser_batch);
  $batch_id = db_insert_id();

  // Set a session variable so we are aware of this batch process's existence, so we can call it from system's handle_form_submit if necessary.
  $_SESSION ["fp_batch_id"] = $batch_id;

  // Return back the $bid for the next function to work with.
  return $batch_id;