Asterisk HASH and ARRAY: structure dialplan state without hiding scope

Choose keyed state or positional assignment deliberately

HASH(hashname,hashkey) is Asterisk's named associative-array function: in two-argument mode it gets and sets a value for one key. ARRAY(var1,var2,...) is different. It assigns a comma-delimited value list to a corresponding list of ordinary variable names; it is not a readable keyed container.

Use HASH when later logic addresses values by key. Use ARRAY only when the producer and consumer share one explicit positional contract. Record the hash name or variable names, writer, channel, priority and value grammar before adding branches.

Keep HASH reads and writes explicit

Write one entry with a function assignment such as Set(HASH(route,region)=north) and read it as ${HASH(route,region)}. Preserve the exact hash name and key spelling; variable names are case-sensitive, and dynamically constructed names need the same normalized input at write and read.

The HASH reference says its single-argument assignment mode works only when assigned from a function defined by func_odbc. Do not substitute Set(HASH(name)=...) for ordinary two-argument writes or assume that an ODBC row and a manually constructed comma list have the same shape.

Snapshot keys before an iteration can mutate them

HASHKEYS(hashname) returns the current keys as a comma-delimited list. The Asterisk reference expressly warns that adding keys while iterating changes later HASHKEYS results. Capture one returned list into a separate variable before the loop, retain the observation point and process that fixed snapshot.

SHIFT(listvar) can remove and return the first item from a comma-delimited variable. Use it on the snapshot, not on a fresh HASHKEYS call at each iteration. The documentation does not promise a semantic key order, so business priority belongs in explicit data or dialplan logic rather than enumeration order.

Define delimiter and blank-value policy

HASHKEYS and ARRAY both use comma-delimited text at their boundary. Define whether keys or values may contain commas, whether blank is valid, how cardinality is checked and what fallback applies before passing external data into either function. ARRAY maps positions; a reordered or differently sized producer can assign the wrong meaning without changing a variable name.

A blank HASH read is not enough operational evidence to decide whether the intended writer ran, the constructed key matched or an intentionally blank value was stored. Preserve the intended key list, write path and branch result rather than inventing an existence test the reviewed HASH reference does not document.

Treat channel ownership and inheritance as separate design choices

Asterisk stores ordinary variables in the respective channel structure. One underscore inherits a variable to the next created child and removes the prefix there; two underscores retain recursive inheritance. Setting any prefixed or unprefixed form replaces the other form.

Prove the actual channel and child-creation timing for every snapshot or ARRAY target. Do not assume that a named HASH, a snapshot variable and its keys automatically become global or persistent, or that copying one snapshot reproduces later mutations. Use AstDB or an external owner only when persistent or cross-call state is the explicit requirement.

Clear at the intended lifecycle boundary and test the shape

ClearHash(hashname) clears all keys from the named hash. Place it only where the lifecycle requires a full reset; it is not a selective delete and should not be used as a generic recovery step on an unfamiliar name. Preserve the pre-clear key snapshot and the owner that authorized the reset without logging sensitive values.

In an authorized test path, exercise two distinct keys, one valid blank policy, a stable iteration snapshot, a key added after that snapshot, one ARRAY assignment and the intended cleanup. Verify the later dialplan branch separately. This guide is documentation-derived; no PBX, hash, channel or call was tested.

Validate a delimited record before ARRAY or HASH assignment

Use the dialplan input guide to prove delimiter, field count and selected content before writing structured channel state.