Public and Private Methods and Packages

Overview

Private methods and packages are SAS Micro Analytic Service concepts, rather than DS2 features.
SAS Micro Analytic Service can host public DS2 packages and private DS2 packages. Private DS2 packages have fewer restrictions on the DS2 features that can be used than public packages have. Although a private DS2 package cannot be called directly, it can be called by another DS2 package. Private DS2 packages are useful as utility functions, as solution-specific built-in functions, or for solution infrastructure. See your SAS solution documentation for a description of the solution-specific built-in functions that you can use when authoring custom DS2 modules.
A public DS2 package can contain private methods, as long as it contains at least one public method. Any method that does not conform to the rules for public methods is automatically treated as private. Private methods are allowed and do not produce errors if they contain correct DS2 syntax. Private methods are not callable externally. Therefore, they do not show up when querying the list of methods within a package. However, they can be called internally by other DS2 package methods. Here are several typical uses of private methods:
  • Small utility functions that return a single, non-void, result.
  • Methods containing DS2 package arguments. These are not callable externally.

Public Method Rules

Public methods must conform to the following rules:
  • The return type must be void. Rather than using a single return type, public methods can return multiple outputs, where each output argument specifies the in_out keyword in the method declaration. Non-void methods are treated as private.
  • Arguments that are passed by reference (meaning ones that specify in_out) are treated as output only. True update arguments are not supported by public methods. This restriction results in more efficient parameter marshaling and supports all interface layers, including REST.
  • Input arguments must precede output arguments in the method declaration. It is permissible for a method to have only inputs or only outputs. However, if both are present, all inputs must precede the outputs.
  • DS2 packages might not be passed as arguments in public methods. The presence of a DS2 package argument results in the method becoming private.
  • The VARARRAY statement might not be present in the argument list of a public method. VARARRAY is a DS2 statement, not a data type. The presence of VARARRAY in a methods argument list causes the method to become private.
  • For a full list of data types that can be used as public method arguments, see Supported DS2 Data Types.

Public Method Example

The example below illustrates a valid public method. It has a void return type (no RETURNS clause), uses only publicly supported data types, and treats in_out arguments as output only.
method quickSortStep (int lowerIndex, int higherIndex, in_out double numbers[10]);

      dcl int i;
      dcl int j;
      dcl int pivot;
      dcl double temp;

      i = lowerIndex;
      j = higherIndex;

      /* Calculate the pivot number, taking the pivot as the
       * middle index number. */
      pivot = numbers[ceil(lowerIndex+(higherIndex-lowerIndex)/2)];

      /* Divide into two arrays */
      do while (i <= j);
            /**
             * In each iteration, identify a number from the left side that
             * is greater than the pivot value. Also identify a number 
             * from the right side that is less than the pivot value.
             * Once the search is done, then exchange both numbers.
             */
            do while (numbers[i] < pivot);
              i = i+1;
            end;
            do while (numbers[j] > pivot);
                j = j-1;
            end;
            if (i <= j) then do;
                temp = numbers[i];
                numbers[i] = numbers[j];
                numbers[j] = temp;

                /* Move the index to the next position on both sides. */
                i = i+1;
                j = j-1;
            end;
        end;

        /* Call quickSort recursively. */
        if (lowerIndex < j) then do;
            quickSortStep(lowerIndex, j, numbers);
        end;
        if (i < higherIndex) then do;
            quickSortStep(i, higherIndex, numbers);
        end;
  end;
Here is another example of a public method that illustrates the use of the HTTP package calling out to a web service using a POST request and then getting a response.
  method httppost( nvarchar(8192) url,
                   nvarchar(67108864) payload,
                   in_out nvarchar respbody,
                   in_out int hstat, in_out int rc );
    declare package http h();
    rc = h.createPostMethod( url );
    if rc ne 0 then goto Exit;
    rc = h.setRequestContentType( 'application/json;charset=utf-8' );
    if rc ne 0 then goto Exit;
    rc = h.addRequestHeader( 'Accept', 'application/json' );
    if rc ne 0 then goto Exit;
    rc = h.setRequestBodyAsString( payload );
    if rc ne 0 then goto Exit;
    rc = h.executeMethod();
    if rc ne 0 then goto Exit;
    hstat = h.getStatusCode();
    if hstat lt 400 then h.getResponseBodyAsString( respbody, rc );
    else respbody = '';
    Exit:
    h.delete();
  end;

Private Method Example

The example below generates a private method in SAS Micro Analytic Service. It has a non-void return type. That is, it has a RETURNS clause in the declaration, which specifies a single integer return value.
method isNull(double val) returns int;
  return null(val) OR missing(val);
end;

Method Overloading

SAS Micro Analytic Service supports method overloading. In DS2, when two or more methods in the same package have the same name, those methods are said to be overloaded. 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, any output parameter types must always be set in tksfValues before executing the method.
Note: Each module constitutes a separate namespace and corresponds to one DS2 package. Therefore, two DS2 methods with the same name, in different modules, are not considered overloaded.
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. Therefore, only DS2 package methods can be overloaded in SAS Micro Analytic Service 1.3.
Note: SAS Micro Analytic Service 1.3 supports one Python script per module. Therefore, method overloading is not applicable to Python.
The following functions enable you to query information about overloaded methods. For more information about these methods, see Java Interface Reference.
getStepInputs()
The version of getStepInputs() that takes an index parameter retrieves descriptions of the input parameters of the overloaded method indicated by name and index value. That is, you can use getStepInputs() to query the input arguments for overloaded method 1, 2, 3, and so on. To do this, specify 1, 2, 3, and so on, for the index value.
getStepOutputs()
works similarly to getStepInputs(), but retrieves descriptions of the specified method's output parameters.
getOverloadedStepCount()
returns the number of overloaded methods that exist in the specified module having the specified name.
isOverloaded()
returns True if the specified method is overloaded and False if not.