beginNamedQueryTransaction requires undocumented 'project' argument in gateway scope

Ignition Early Access
1

The documentation for system.db.beginNamedQueryTransaction fails to mention that an argument for ‘project’ is required when running in the gateway scope.

Code:

database = 'DB'
isolation = system.db.READ_COMMITTED
timeout = 1000
project = 'global'
	
tx_query = system.db.beginTransaction(database, isolation, timeout)
tx_namedQuery_noProject = system.db.beginNamedQueryTransaction(database, isolation, timeout)
tx_namedQuery_project = system.db.beginNamedQueryTransaction(project, database, isolation, timeout)

Results in Gateway Scope:

'12425fc9-7d1a-4f24-b494-c5f4c242efc1'
None
'ba8fc790-ea64-4dd0-abc3-0c96a1a606f2'

Results in Client/Designer Scope:

Traceback (most recent call last):
  File "<input>", line 8, in <module>
TypeError: expected at most 3 arguments, got 4

The documentation in question: https://docs.inductiveautomation.com/display/DOC80/system.db.beginNamedQueryTransaction

Additional questions:

  1. Why is the project name required at all to begin a named query transaction?

  2. What’s the logic behind the differences in named query functions between gateway/client scopes? It would make everything simpler if ‘project’ was an optional parameter in the client scope.

1 Like
2

Thanks for catching the documentation issue – I’ll give that dept a heads up.

As to your other questions…

  1. Named queries are a project resource – you could have a named query with the same path in multiple projects. When you begin a transaction, we need to know what project that transaction belongs to in order to send that info to the correct named query execution manager. In the designer/client we know the name of the project, but in the gateway you need to tell us.

  2. If you could put project as a parameter in the client scope it would imply you could run named queries from other projects in that client, which you can’t do (except via something like a sendRequest() or a tag or other non-project route).

If you need the same named query in multiple projects, you can use inheritance. Doesn’t solve the problem of trying to reuse the same script in both gateway and client scope – you would need to check the scope you’re in and run the appropriate version of the function.

1 Like
3

I think this is the source of some confusion. In the gateway, you know the project when the caller is a gateway event script. You don't know the project when called from a tag event. The corresponding scripting functions in system.db.* that have a datasource argument should have been the model for the named query functions. These functions take an optional datasource in client and gateway project scopes, but the argument is mandatory in gateway non-project scope. Arguably, with v8's new global scripting project, it could be optional there, too.

The project argument for named queries should have been optional for gateway project scopes, and mandatory for gateway non-project scope. (Again, arguably optional in v8 by using the global scripting project.) Whether it should be allowed for client scopes (I think it should) is not relevant for the gateway cases.

The function signature in the gateway (with the project argument first) complicates the situation, but I think it should be changed. It is the one part of Ignition that does not intuitively fall back to the caller's project as needed.

2 Likes