As previously discussed, code is published to SAS Micro Analytic Service by calling newRevision(), which returns a revision number greater than zero upon successful compilation. When a revision number less than or equal to zero is returned, a revision was not created. In this case, messages output by the compiler during the failed compilation attempt can be retrieved by calling getCompilerMessages() with the module context ID.

Note: Compiler messages from the most recent call to newRevision() are maintained by the module context. Therefore, if newRevision() fails to create a revision, the compiler message can still be retrieved. Each call to newRevision() overwrites any previously saved compiler messages.

When a revision has been created, its methods can be executed repeatedly. To execute a method, call execute(), passing in the module context ID, revision number (or zero for latest revision), method name, and method arguments.

Note: The method name is also referred to as an entry point.

rc = tk.execute(userCtx, moduleCtx, revisionNumber, "myMethod", args);

Revision numbers are assigned by SAS Micro Analytic Service. The first revision number is always 1. Subsequent revisions are assigned numbers 2, 3, 4, and so on. Revision numbers are never reused. Therefore, if four revisions of a module have been created and revision 3 is deleted, the next revision number assigned is 5 (3 is never reused). Specifying zero for revision number gets the latest revision.

Note: If you know the number of the revision that you want to execute, always pass that number to execute() rather than zero. Passing in zero specifies the latest revision, and causes SAS Micro Analytic Service to look up the latest revision number. This lookup takes time and can be bypassed altogether by passing in the explicit, nonzero revision number.

Java Data Types

Here are the Java scalar data types supported by SAS Micro Analytic Service:

String
Character
Long
Integer
Double

The following Java array types are supported:

String[]
long[]
int[]
double[]

Method Arguments

Method arguments, including input and output parameters, are passed to SAS Micro Analytic Service as a com.sas.mas.tksfValues Java object.

tksfValues p = new tksfValues(numArgsTotal, numInputs);

The first parameter to the tksfValues constructor is the total number of arguments, including both inputs and outputs. The second parameter specifies the number of input arguments of the method.

Note: Before calling execute(), all method arguments, including outputs, must be set on the tksfValues instance. Output arguments are set by calling the setOut<type> methods of tksfValues.

Output arguments must be set for two reasons:

DS2 passes output arguments by reference. Therefore, the correct types must be allocated in order to receive the output values. Because DS2 follows this pass-by-reference convention, SAS Micro Analytic Service follows the same convention regardless of the programming language.
SAS Micro Analytic Service supports method overloading. When overloaded methods are used, the method signature (list of input and output parameters and their types) is used to select the correct method to execute. Because a method signature includes both input and output parameters, the output parameter types must be set in tksfValues.

In DS2, when two or more methods in the same package have the same name, those methods are said to be overloaded. Each module constitutes a separate namespace. Therefore, two DS2 methods that have the same name, but are in different packages, are not considered overloaded. Similarly, two C functions with the same name, but in different C modules, will not have a name conflict.

Note: The C language does not support method overloading. Syntax errors occur if two C functions with the same name exist in the source code of the same C module.

DS2 in_out parameters are treated strictly as output. This convention is necessary to support the REST interface, which does not support true in/out arguments.

When you are coding in DS2 or C, all input arguments must be positioned before any output arguments. Failure to do so causes your method to malfunction. SAS Micro Analytic Service might not detect this error because the DS2 compiler does not carry this restriction.

Note: Arrays are always passed by reference in DS2, regardless of whether the in_out keyword is specified. However, SAS Micro Analytic Service treats arrays without the in_out keyword as input and arrays with the in_out keyword as output, as long as all inputs precede outputs in the method signature.

Incorrect:

method solve(double tempRate, in_out int finalRate, int custId);

Correct:

method solve(double tempRate, int custId, in_out int finalRate);

tksfValues provides methods for setting and getting arguments, including methods that enable the use of explicit or implicit argument indices and methods that support missing values. These methods are described in the sections that follow.

Argument Setter Methods

Overview

Use the setter methods to prepare input and output arguments before calling execute(). Output variables, of the correct types, must be set before calling execute(). Here are the reasons:

Output variables are passed by reference. Therefore, variables must exist to receive the output values.
DS2 supports method overloading (two or more methods having the same name but different signatures). The entire signature must be reflected in the arguments list to allow selection of the correct same-named method.
TKG does not supply metadata for C functions. Therefore, the data type must be set for every argument, including the output arguments.

Setters with an Implicit Index

Use the tksfValues methods below to set the values of input arguments.

Arguments are positional and referenced by a zero-based index. These methods use implied indexes. The first setter method call uses index 0, the next index 1, and so on.

public void setString(String value);
public void setChar(Character value);
public void setLong(Long value);
public void setInt(Integer value);
public void setDouble(Double value);
public void setStringArray(String[] value);
public void setLongArray(long[] value);
public void setIntArray(int[] value);
public void setDoubleArray(double[] value);

Setters with an Explicit Index

Use the tksfValues methods below to set the values of input arguments.

These methods use explicit indexes and set the value of the input argument at the zero-based index position that is given.

public void setString(int index, String value);
public void setChar(int index, Character value);
public void setLong(int index, Long value);
public void setInt(int index, Integer value);
public void setDouble(int index, Double value);
public void setStringArray(int index, String[] value);
public void setLongArray(int index, long[] value);
public void setIntArray(int index, int[] value);
public void setDoubleArray(int index, double[] value);

Missing Value Setters with an Implicit Index

Use the tksfValues methods below to set the values of input arguments to missing.

Arguments are positional and referenced by a zero-based index. These methods use implied indexes. The first setter method call uses index 0, the next index 1, and so on.

The argument to the array setters (dim) specifies the size of the one-dimensional array. Each element of the array is set to a missing value.

public void setMissingString();
public void setMissingChar();
public void setMissingLong();
public void setMissingInt();
public void setMissingDouble();
public void setMissingStringArray(int dim);
public void setMissingLongArray(int dim);
public void setMissingIntArray(int dim);
public void setMissingDoubleArray(int dim);

Missing Value Setters with an Explicit Index

Use the tksfValues methods below to set the values of input arguments to missing.

These methods use explicit indexes, and set the value of the input argument at the zero-based index position given.

The argument to the array setters (dim) specifies the size of the one-dimensional array. Each element of the array is set to a missing value.

public void setMissingString(int index);
public void setMissingChar(int index);
public void setMissingLong(int index);
public void setMissingInt(int index);
public void setMissingDouble(int index);
public void setMissingStringArray(int index, int dim);
public void setMissingLongArray(int index, int dim);
public void setMissingIntArray(int index, int dim);
public void setMissingDoubleArray(int index, int dim);

Output Setters with an Implicit Index

Use the tksfValues methods below to set the type of an output argument (and to set its value to missing) before calling execute().

Arguments are positional and referenced by a zero-based index. These methods use implied indexes. The first setter method call uses index 0, the next index 1, and so on.

The argument to the array setters (dim) specifies the size of the one-dimensional array. Each element of the array is set to a missing value.

public void setOutString();
public void setOutChar();
public void setOutLong();
public void setOutInt();
public void setOutDouble();
public void setOutStringArray(int dim);
public void setOutLongArray(int dim);
public void setOutIntArray(int dim);
public void setOutDoubleArray(int dim);

Output Setters with an Explicit Index

Use the tksfValues methods below to set the type of an output argument, and to set its value to missing, before calling execute().

These methods use explicit indexes, and set the value of the input argument at the zero-based index position given.

The argument to the array setters (dim) specifies the size of the one-dimensional array. Each element of the array is set to a missing value.

public void setOutString(int index);
public void setOutChar(int index);
public void setOutLong(int index);
public void setOutInt(int index);
public void setOutDouble(int index);
public void setOutStringArray(int index, int dim);
public void setOutLongArray(int index, int dim);
public void setOutIntArray(int index, int dim);
public void setOutDoubleArray(int index, int dim);

Argument Getter Methods

Overview

Use the getter methods to retrieve results after calling execute(). A return code of zero from execute() indicates successful execution.

tksfValues provides methods for retrieving method output values, and for checking to see whether an output argument has been set to missing.

Similar to the getter methods, setter methods use either implicit or explicit indices.

Missing Value Check

The following method can be used to see whether a given output argument contains a missing value. isMissing() checks the argument at the given zero-based position for missing, regardless of the arguments data type.

public boolean isMissing(int ndx);

Getters with an Implicit Index

Use the tksfValues methods below to get the values of output arguments.

Note: The first output argument often follows one or more input arguments. Therefore, in order to use implicit indices to retrieve output values, it is often necessary to call setIndex() before calling the first getter method. setIndex() sets the implicit zero-based index to the given value, enabling the first getter method (with implicit index) to retrieve the first output argument.

public void setIndex(int ndx);

Arguments are positional and referenced by a zero-based index. These methods use implied indexes. The first getter method call uses index 0, the next index 1, and so on.

public String getString();
public Character getChar();
public Long getLong();
public Integer getInt();
public Double getDouble();
public String[] getStringArray();
public long[] getLongArray();
public int[] getIntArray();
public double[] getDoubleArray();

Getters with an Explicit Index

Use the tksfValues methods below to get the values of output arguments.

These methods use explicit indexes and get the value of the output argument at the zero-based index position given.

public String getString(int pos);
public Character getChar(int pos);
public Long getLong(int pos);
public Integer getInt(int pos);
public Double getDouble(int pos);
public String[] getStringArray(int pos);
public long[] getLongArray(int pos);
public int[] getIntArray(int pos);
public double[] getDoubleArray(int pos);

Miscellaneous tksfValues Methods

Use clear() to reset all argument values in the tksfValues instance and to set the implicit index to zero.

public void clear();

Use the following methods to retrieve the total number of arguments and the number of input arguments, respectively, of the tksfValues instance:

public int getSize();
	public int getInputCount();