Submission-time values

SPL supports submission-time values, which are arguments that are specified at the time of application launch.

For distributed executions that run on the Streams instance, these arguments are specified when you submit a job with the streamtool submitjob command or through other interfaces. For stand-alone execution, submission-time values are specified when you launch the generated stand-alone execution. These values can be accessed from within SPL code through the following submission-time value access functions:

rstring getSubmissionTimeValue(rstring name)
rstring getSubmissionTimeValue(rstring name, rstring default)
list<rstring> getSubmissionTimeListValue(rstring name)
list<rstring> getSubmissionTimeListValue(rstring name, list<rstring> default)

These functions can appear only in a composite operator scope within an SPL file, where an expression of the right type (matching the return type of the function) is expected. The first function, getSubmissionTimeValue, returns a value for a given name, as a string. A submission-time error results if the string passed as the name argument is not specified on the application launch command line at submission time. The second function, getSubmissionTimeValue returns a value for a given name, or a default value in case the name is not specified at submission time, as a string. All default values for the same name value within a composite must be identical. The third function getSubmissionTimeListValue returns a list of values for a given name, as a string list. It results in a submission-time error, if the name argument is not specified on the application launch command line at submission time. The name argument that is passed in to these functions must be a compile-time expression that can be evaluated.

Submission time values are specified as <name>=<value> on the application launch command line. The name part is an identifier, as in myParam. It matches the name parameter that is specified in calls that are made to the submission-time value access functions from within SPL code. Optionally, it is preceded by a composite operator name, as in MyOp.myParam. The composite operator name itself is optionally preceded by its namespace, as in my.nmspace::MyOp.myParam. The namespace can be partial, when a correct suffix of the full namespace is given, as in nmspace::MyOp.myParam. The composite operator names and namespaces provide a way of scoping the submission-time values. For instance, the call getSubmissionTimeValue("id") can appear inside the scope of two different composite operator definitions. Say OpA and OpB. In this case, two different values can be returned from the two getSubmissionTimeValue calls with the following command line: OpA.id=5 OpB.id=10. If a submission-time value access call matches more than one argument that is specified on the command line, an error is flagged at submission-time due to the ambiguity involved. The value part of the command-line argument can be any string. For submission time values that are accessed through the getSubmissionTimeListValue function, the value is a list of , separated strings, where the separator character cannot appear in the individual strings that are contained in the list. An example is given as follows:

# for standalone executions
./output/bin/standalone my.sample::OpA.message=HelloWorld OpB.names=foo,bar

# for distributed executions
streamtool submitjob -P my.sample::OpA.message=HelloWorld -P OpB.names=foo,bar <application-bundle-file>

  namespace my.sample;
  composite OpA { ...
     // getSubmissionTimeValue("message") == "HelloWorld"
     // getSubmissionTimeValue("value", "10") == "10"
  }
  composite OpB { ...
     // getSubmissionTimeListValue("names") == ["foo", "bar"]
  }

With corresponding SPL code casts, literal values (without type suffixes) are specified on the command line as a way of passing structured types as submission-time values. For instance:

./output/bin/standalone students='[{name="Mary", grade=100},{name="John", grade=90}]'

  namespace my.sample;
  type studentsT = list<tuple<rstring name, int32 grade>>;
  composite OpA { ...
     studentsT students = (studentsT) (getSubmissionTimeValue("students"));
  }

Submission-time values can also be supplied to distributed executions. You specify the '-P' argument to streamtool submitjob. These arguments can be supplied to a distributed execution as:

streamtool submitjob -P students='[{name="Mary", grade=100},{name="John", grade=90}]' output/Main.sab

(assuming Main is the main composite for the application.)