batch.queue.setParameterValue(...)

Sepasoft MES Module Suite

queue.setParameterValue(...)

Assigns a new value to a batch control recipe parameter on a running queue entry, identified either by a BatchQueueEntry or by batch ID. The gateway resolves the friendly path, converts display values to internal representations where applicable, and routes the change through batch execution notifications so the active phase logic can accept or reject the update. Use this from gateway scripts, client scripts, batch Script phases, or UI automation when programmatic writes are allowed for the target parameter.

Syntax

Copy Code
Python
system.mes.batch.queue.setParameterValue(batchQueueEntry, path, value)
system.mes.batch.queue.setParameterValue(batchQueueEntry, path, value, changedBy)
system.mes.batch.queue.setParameterValue(batchID, path, value)
system.mes.batch.queue.setParameterValue(batchID, path, value, changedBy)

Arguments may also be passed by keyword (batchQueueEntryOrBatchID, path, value, changedBy).

Parameters

Parameter

Type

Required

Description

batchQueueEntry

BatchQueueEntry object

Required (one overload)

The queue entry whose parameter should be updated. Must be present on the gateway batch queue and running.

batchID

String

Required (one overload)

The batch ID string; the gateway resolves it to a BatchQueueEntry. Must not be blank.

path

String

Required

Full parameter path in batch path notation (procedure, unit procedure, operation, step, and parameter). See Location / Paths.

value

Object

Required

Value to assign. Must be a Serializable type compatible with the parameter’s configured datatype. For some well-known parameters (for example State_Number, Command), the gateway applies additional conversion and notification handling.

changedBy

String

Optional

Operator or source identity recorded with the change (audit/history). May be omitted or empty.

Return Value

Type

Description

None

On success, the parameter is updated (or the appropriate command/state notification is handled). No value is returned.

Location / Paths

Paths follow the /Procedure/Unit_Procedure/Operation:Step.Parameter pattern.

The procedure segment may be abbreviated as {} (for example /{}.Parameter,
/{}:Step.Parameter,
/{}/Unit_Procedure.Parameter,
/{}/Unit_Procedure:Step.Parameter,
/{}/Unit_Procedure/Operation.Parameter,
/{}/Unit_Procedure/Operation:Step.Parameter).

The path must reference a valid parameter on the control recipe; invalid paths cause an IllegalArgumentException.

Scope / Availability

  • Registered on system.mes.batch.queue (Sepasoft Batch / MES).

  • Gateway: Executes locally in BatchExecutionManager against the running batch queue.

  • Designer / Client: BatchClientQueueScript delegates to the production RPC proxy (same behavior against the connected gateway).

  • Batch Script phases: Scripts receive batchID and stepPath and may call this function to update parameters on related steps (see BatchScriptAction).

Excluded / Edge Cases

  • MES runtime — checkMESSystemStarted() runs first; if the MES system is not started, the call fails with IllegalStateException.

  • Running batch required — Unlike getParameterValue, the queue entry must be running (assertQERunning). If not running → IllegalStateException (“batch queue entry is not running”).

  • Missing queue entry — BatchQueueEntry is null → IllegalArgumentException. Blank batchID → IllegalArgumentException. Unknown batch ID or entry not on the gateway queue → BatchQueueEntryNotFoundException.

  • Invalid value type — After internal conversion, if the value is not Serializable → Exception (“value is not a valid data type”).

  • Phase rejection — For typical parameters, the gateway sends a SET_PARAMETER_VALUE notification to the phase owning the step. If the phase cannot apply the value, the notification may carry an Exception or return message, which is rethrown to the caller.

  • State_Number — Sets equipment/state via EXTERNAL_STATE_CHANGE; the target phase must allow external state changes. If the notification is not handled → Exception (“Set state was not handled…”).

  • Command — Sends COMMAND_CHANGE to the step’s command handling (not a generic parameter write).

  • Friendly values — Parameters that define a value-to-internal converter (for example enumerated display names) are converted before the notification is sent.

  • Idle or held batches — Cannot set parameters on entries that are not actively running; use queue commands or other APIs to start execution first.

Example Usage

Minimal example

Copy Code
Python
entry = system.mes.batch.queue.getEntry("BATCH-001")
system.mes.batch.queue.setParameterValue(entry, "/{}/Mixing:Heat.Target_Temperature", 72.5)

Complex example

Copy Code
Python
batchID = "BATCH-2026-0142"
operator = system.security.getUsername()
paramPath = "/{}/Equipment:Phase1.State_Number"
newState = 3  # integer state number; gateway maps to BatchStateTypes

try:
	if system.mes.batch.queue.isQueueEntryRunning(batchID):
		system.mes.batch.queue.setParameterValue(
			batchID,
			paramPath,
			newState,
			changedBy=operator
		)
		displayState = system.mes.batch.queue.getParameterValueAsString(
			batchID,
			"/{}/Equipment:Phase1.State"
		)
		system.util.getLogger("BatchControl").info(
			"Batch %s state after set: %s" % (batchID, displayState)
		)
	else:
		system.util.getLogger("BatchControl").warn(
			"Batch %s is not running; cannot set parameter" % batchID
		)
except Exception, ex:
	system.util.getLogger("BatchControl").error(
		"Failed to set parameter on %s: %s" % (batchID, ex)
	)

Related Functions

Sepasoft MES Module Suite