Revision Methods

Overview

A revision represents the executable code of a module. A module might contain zero or more revisions. More than one revision of a given module can be executed concurrently by different callers, or at different times by the same caller. Passing in zero for a revision number gets the latest revision of the specified module.

For example, caller A might rely on specific behavior in revision 3 of module X. You might set up caller B to always use the latest version of module X. To execute the desired code, caller A would specify the ID of module X and revision 3:

revision = 3;
rc = tk.execute(userCtx, moduleX, revision, methodName, args);

Caller B would specify the same module ID and revision zero:

revision = 0;
rc = tk.execute(userCtx, moduleX, revision, methodName, args);

Revision numbers are monotonically increasing values starting at 1. Revisions can be created and deleted. However, revision numbers are never reused. This behavior prevents the code of a revision from unexpectedly changing out from under a caller. Once a revision has been deleted, attempts to execute or query that revision receive a result code indicating the revision was not found.

Parameter Descriptions

Some of the revision-specific methods, such as getStepInputs() and getStepOutputs(), return instances of the public class tksfParmdef, which stands for parameter definition. Each tksfParmdef instance describes one parameter of a C function or DS2 package method. tksfParmdef contains the following member variables, along with getters and setters for each:

public int 		index;  // parameter position (zero-based)
	public String 	name;	  // parameter name
	public sftype 	type;	  // parameter type
	public int		dim;	  // if array, dimension; ignored otherwise
	public int		size;	  // if varchar, max length; ignored otherwise

The parameter type member variable, sftype, is defined as the following enumeration, which represents the Java data types that are supported by SAS Micro Analytic Service:

// Supported data types
	public enum sftype {
		string_t,
		char_t,
		long_t,
		double_t,
		int_t,
		stringArray_t,
		charArray_t,
		longArray_t,
		doubleArray_t,
		intArray_t

Method Descriptions

Here are the available revision methods:

newRevision

int newRevision(long moduleContext,
     java.lang.String sourceCode,
     java.lang.String description,
     java.lang.String[] CEntryPoints,
     java.util.EnumSet<TkLight.RevisionOptions> options)

The source code is compiled into executable form and, if it is successful, a revision number is assigned by SAS Micro Analytic Service. Revisions are uniquely identified by module context ID and revision number. Once created, a revision can be executed many times.

If source code compilation fails during newRevision(), the revision is not created, and any compiler warning or error messages are maintained by the owning module context until the next time newRevision() is called for the given module context.

Note: For DS2 packages, the parent module context displayName is assigned the DS2 package name (given in the source code) when the first revision of that module context is successfully created. After the first revision is created, the name cannot be changed. Attempts to create a revision of a DS2 module with a different package name than the original revision result in an error.

Note: DS2 packages containing non-void methods or methods with DS2 package arguments are treated as private and are not returned in queries for methods. It is permissible to include private methods, and private methods do not produce errors as long as the code is valid. For more information, see Public and Private Methods and Packages.

Parameters

moduleContext - The opaque handle returned from newModuleContext().

sourceCode - The string containing the source code (must match language of original source code).

description - User-supplied text.

CEntryPoints - If C code, this refers to the names of the entry points (functions) to make available externally.

Return

revisionNumber - The new revision number.

deleteRevision

void deleteRevision(long moduleContext,
                    int revision)

Deletes the module revision that is specified by module context and revision number.

Parameter

moduleContext - The opaque handle returned from newModuleContext().

getCompilationMessages

java.lang.String[]
getCompilationMessages(long moduleContext)

Retrieves any compiler diagnostic messages from the latest compilation (newRevision call) of the given module context.

Note: Only compilation messages from the most recent compilation, per module context, are retained.

Parameter

moduleContext - The opaque handle returned from newModuleContext().

Return

An array of strings containing compiler diagnostic messages.

revisionIsValid

boolean revisionIsValid(long moduleContext,
                        int revision)

Returns True if the revision is valid, False if otherwise.

Parameters

moduleContext - The opaque handle returned from newModuleContext().

revision - The revision number returned from newRevision().

Return

Boolean - True if the revision is valid, and False if otherwise.

getStepIDs

java.lang.String[] getStepIDs
(long moduleContext, int revision)

Retrieves the IDs of steps (DS2 package methods or C functions) contained by the revision.

Parameters

moduleContext - The opaque handle returned from newModuleContext().

revision - The revision number returned from newRevision().

Return

The string array containing a list of step IDs (DS2 package method names or C function names).

getStepDescription

java.lang.String getStepDescription
(long moduleContext, int revision, java.lang.String stepId)

Retrieves the step description.

Parameters

moduleContext - The opaque handle returned from newModuleContext().

revision - The revision number returned from newRevision().

stepId - The name of the DS2 package method or C function.

Return

The description of the step.

getStepInputs

java.util.ArrayList<tksfParmdef> getStepInputs
(long moduleContext, int revision, java.lang.String stepId)

Retrieves the step input arguments.

Parameters

moduleContext - The opaque handle returned from newModuleContext().

revision - The revision number returned from newRevision().

stepId - The name of the DS2 package method or C function.

Return

An ArrayList of parameter definitions. For more information, see Parameter Descriptions.

getStepInputs

java.util.ArrayList<tksfParmdef> getStepInputs
(long moduleContext, int revision, java.lang.String stepId, int index)

Retrieves step input arguments for an overloaded method, at a zero-based index.

Note: This method is valid only for DS2, which supports method overloading.

Note: Overloaded methods are methods within a DS2 package that have the same name.

Parameters

moduleContext - The opaque handle returned from newModuleContext().

revision - The revision number returned from newRevision().

stepId - The name of the DS2 package method or C function.

index - The zero-based index of the overloaded method.

Return

An ArrayList of parameter definitions. For more information, see Parameter Descriptions.

getStepOutputs

java.util.ArrayList<tksfParmdef> getStepOutputs
(long moduleContext, int revision, java.lang.String stepId)

Retrieves the step output arguments.

Parameters

moduleContext - The opaque handle returned from newModuleContext().

revision - The revision number returned from newRevision().

stepId - The name of the DS2 package method or C function.

Return

An ArrayList of parameter definitions. For more information, see Parameter Descriptions.

getStepOutputs

java.util.ArrayList<tksfParmdef> getStepOutputs
(long moduleContext, int revision, java.lang.String stepId, int index)

Retrieves the step output arguments for an overloaded method, at a zero-based index.

Note: This method is valid only for DS2, which supports method overloading.

Note: Overloaded methods are methods within a DS2 package that have the same name.

Parameters

moduleContext - The opaque handle returned from newModuleContext().

revision - The revision number returned from newRevision().

stepId - The name of the DS2 package method or C function.

index – The zero-based index of the overloaded method.

Return

An ArrayList of parameter definitions. For more information, see Parameter Descriptions.

getOverloadedStepCount

int getOverloadedStepCount(long moduleContext,
                           int revision,
                           java.lang.String stepID)

Retrieves the number of overloaded steps matching the given step ID.

Note: This method is valid only for DS2, which supports method overloading.

Note: Overloaded methods are methods within a DS2 package that have the same name.

Parameters

moduleContext - The opaque handle returned from newModuleContext().

revision - The revision number returned from newRevision().

stepId - The name of the DS2 package method or C function.

Return

The number of overloaded steps (DS2 package methods having the same name).

isOverloaded

boolean isOverloaded(long moduleContext,
                     int revision,
                     java.lang.String stepID)

Retrieves the number of overloaded steps matching the given step ID.

Note: This method is valid only for DS2, which supports method overloading.

Note: Overloaded methods are methods within a DS2 package that have the same name.

Parameters

moduleContext - The opaque handle returned from newModuleContext().

revision - The revision number returned from newRevision().

stepId - The name of the DS2 package method or C function.

Return

True, if the method is overloaded, False otherwise.

getRevisionCreationDateTime

java.util.Date getRevisionCreationDateTime
(long moduleContext, int revision)

Gets the revision creation datetime.

Parameters

moduleContext - The opaque handle returned from newModuleContext().

revision - The revision number returned from newRevision().

Return

The creation datetime in SAS form (GMT seconds since 1960).