system.mes.batch.queue.getParameterValueAsString

Sepasoft MES Module Suite

getParameterValueAsString(...)

Reads the current value of a batch control recipe parameter as a human-readable String for a queue entry, identified either by a BatchQueueEntry or by batch ID. When the batch execution controller is active and the entry is loaded, the value comes from live execution state; otherwise it is read from persisted control logic on the gateway. The product documentation warns against calling this in a tight loop for performance reasons.

For performance reasons, this function should not be used for continuous polling of batch parameter values.

In version 3.81.12 SP2 and later:

Updated to not require a Batch to be running to get the value of a parameter.
- For parameters that have a Calculation Expression, if the Batch is not active, the last calculated value will be returned, if present, otherwise the Calculation Expression is returned.
Can accept either a batchQueueEntry or a BatchID.

Syntax

Copy Code

Python

system.mes.batch.queue.getParameterValueAsString(batchQueueEntry, path)
system.mes.batch.queue.getParameterValueAsString(batchID, path)

Parameters

Parameter	Type	Required	Description
batchQueueEntry	BatchQueueEntry	Required (one overload)	The queue entry whose parameter should be read. Must refer to an entry present on the gateway batch queue.
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.

Return Value

Type	Description
String	The parameter's current value is formatted as a human-readable string. For parameters with a calculation when the controller is not active and the entry is not loaded: returns the stored display value if present, otherwise the calculation expression string.

Location / Paths

Paths follow the /Procedure/Unit_Procedure/Operation:Step.Parameter pattern. The procedure segment may be abbreviated as {}.

Examples:

/{}.Parameter
/{}:Step.Parameter
/{}/Unit_Procedure.Parameter
/{}/Unit_Procedure:Step.Parameter
/{}/Unit_Procedure/Operation.Parameter
/{}/Unit_Procedure/Operation:Step.Parameter

The path must identify a valid parameter, not only a step or logic object.

Scope / Availability

Registered on system.mes.batch.queue (Sepasoft Batch / MES).
Gateway: Executes locally against the batch execution manager.
Designer / Client: BatchClientQueueScript delegates to the production RPC proxy (same behavior against the connected gateway).

Excluded / Edge Cases

MES runtime — checkMESSystemStarted() runs first; if the MES system is not started, the call fails.
Missing queue entry — BatchQueueEntry is null → IllegalArgumentException. batchID blank → IllegalArgumentException. Unknown batch ID → BatchQueueEntryNotFoundException. Entry not on the gateway queue (control recipe UUID not found) → BatchQueueEntryNotFoundException.
Invalid parameter path — Not a valid parameter path → IllegalArgumentException with the path in the message.
Idle vs running — If the queue entry is not loaded or the execution controller is not active, values are read from BatchControlLogic via the control recipe. If the controller is active and the entry is loaded, the value is resolved through friendlyPathToUUIDPath and the active batchExecutionController.
Display conversion — This function returns the display string. Use getParameterValue when code needs the raw configured datatype instead.
Polling — Repeated continuous reads are discouraged for performance (see bundled script description).

Example Usage

Minimal Example

Copy Code

Python

entry = system.mes.batch.queue.getEntry("BATCH-001")
displayValue = system.mes.batch.queue.getParameterValueAsString(
	entry,
	"/{}:Mixing.State"
)

Complex Example

Copy Code

Python

batchID = "BATCH-2026-0142"
logger = system.util.getLogger("BatchMonitor")

parameterPaths = {
	"state": "/{}:Mixing.State",
	"targetTemp": "/{}/Mixing:Heat.Target_Temperature"
}

try:
	for name, path in parameterPaths.items():
		displayValue = system.mes.batch.queue.getParameterValueAsString(batchID, path)
		logger.info("Batch %s %s = %s" % (batchID, name, displayValue))
except Exception, ex:
	logger.error("Failed to read batch parameter: %s" % ex)

Related Functions

system.mes.batch.queue.getParameterValue(batchQueueEntry, path) / (..., batchID, path) — Reads the current raw parameter value using the parameter's configured datatype.
system.mes.batch.queue.setParameterValue(batchQueueEntry, path, value, changedBy) / (..., batchID, path, value, changedBy) — Writes a parameter value.
system.mes.batch.queue.getEntry(batchID) — Retrieves the BatchQueueEntry used with the object overload.
system.mes.batch.queue.getParameterOptions(batchQueueEntry, path) / (..., batchID, path) — Lists valid linked-object options for supported searchable sub-parameters.

Accessing Recipe Level Parameter Example

In this batch there is a Recipe, or called Procedure, level parameter that we would like to read. The parameter is called "MatSerialNum_B".

Copy Code

Python

##Identify or retrieve the Batch ID, typically from a tag, on-screen component, or user selection.
batchID = 'BatchID_12345'

##Define the path to the parameter.  Note carefully the syntax.
path = "/Hot Chocolate Powder.MatSerialNum_B"

##Retrieve the Batch Queue Entry based upon the unique Batch ID.
bqe = system.mes.batch.queue.getEntry(batchID)

##Call the function to the get the parameter value.
val = system.mes.batch.queue.getParameterValueAsString(bqe, path)

Accessing Phase Level Parameter Example

In this batch there is a Unit Procedure with a phase with a parameter that we would like to read. The parameter is called "LotId_A".

Copy Code

Python

##Identify or retrieve the Batch ID, typically from a tag, on-screen component, or user selection.
batchID = 'BatchID_12345'

##Define the path to the parameter.  Note carefully the syntax.

##Note that the Procedure Level (the "Hot Chocolate Powder" Recipe), then the Unit Procedure ("P2"), then the Phase ("UP2"), 

##then finally the  Parameter ("LotId_A") are listed in the path. Note the colon after the Unit Procedure level.
path = "/Hot Chocolate Powder/P2:UP2.LotId_A"

##Retrieve the Batch Queue Entry based upon the unique Batch ID.
bqe = system.mes.batch.queue.getEntry(batchID)

##Call the function to the get the parameter value.
val = system.mes.batch.queue.getParameterValueAsString(bqe, path)

Sepasoft MES Module Suite