16.5.8.Connection Variables in IRI Classes

Writing function-based IRI class is overkill when the IRI can in principle be made by a sprintf_iri but the format should contain some context-specific data, such as host name used for the dynamic renaming of local IRIs . Format strings offer a special syntax for that cases. %{varname}U acts as %U but the function sprintf will take the value from client connection variable varname , not from list of arguments. Similarly, sprintf_inverse will not return fragment that match to %{varname}U in the vector of other fragments; instead it will get the value from connection environment and ensure that it matches the fragment of input; mismatch between printed and actual value of variable will means that the whole string do not match the format.

SPARQL optimizer knows about this formatting feature and sometimes it makes more deductions from occurrence of %{varname}U than from occurrence of plain %U , so this notation may be used in option ( returns ...) when appropriate. Of course, the optimizer has no access to the actual value of connection variable because it may vary from run to run or may change between the compilation and the run, but the value is supposed to be persistent during any single query run so %{myvariable}U in one place is equal to %{myvariable}U in other.

Connection variables are set by connection_set and some of them have default values that are used if not overridden by application:

  • URIQADefaultHost

    is for default host as it is specified in Virtuoso configuration file. Note, however, that it will be escaped when printed so if it contains colon and port number then the colon is escaped. In addition, there are special variables that match dynamic renaming of local IRIs more accurately.

  • WSHost

    is for host and port as it is used by current client connection for dynamic renaming. The colon before port will be escaped.

  • WSHostName

    is for host name only, without port, as it is used by current client connection for dynamic renaming.

  • WSHostPort

    is for port part of host IRI. That is string, not integer. The only real use of the variable is in formats like

    http://%{WSHostName}U:%{WSHostPort}U/...

    .

It is inconvenient to write different format strings for different cases. Two most common policies are different host names for default HTTP port of a publicly available service and different non-default ports for one or more host names of an intranet installation; these two approaches are almost never used in a mix. So declaration of IRI classes may use shorthand ^{DynamicLocalFormat}^ in format strings that is expanded either to http://%{WSHost}U or to http://%{WSHostName}U:%{WSHostPort}U/... , depending on absence or presence of port number in the value of DefaultHost parameter of URIQA section of configuration file.

[Note] Note

^{DynamicLocalFormat}^ is for IRI class declarations only and is not expanded in any other place, so it is useful sometimes to create an IRI class with empty argument list in order to get "almost constant" IRIs calculated without writing special procedures.