Contents Developing Java Clients  

CORBA Interface IFormatService

A service that performs data conversion using SAS formats and informats.

Definition

CORBA Module SAS

IFormatService Description

This component provides operations for enumerating the formats and informats that are available in a Workspace and for using those formats and informats to convert data.

The EnumerateFormats method lists formats and informats that are available in the Workspace. It provides numerous ways to filter the list, including by data type, by category (such as date or currency), and by name matching.

After the desired set of formats has been identified, you must load them via Load. This method returns format IDs that can then be used in the formatting calls.

There are three formatting and three informatting operations. Each supports a different data type: numeric, character, or datetime. These methods support the conversion of a two-dimensional array of data values in a single call. Numeric and datetime formatting handle SAS missing values. All of the methods provide detailed failure information for any individual conversion operation that fails.

Clients Unload formats when finished with them.

The three formatting operations follow similar conventions in the use of their parameters. The input values should be presented in a two-dimensional array that represents tabular data (such as values from a SAS data set or from an SQL result set). The columns in this array represent a specifc field or variable. All items in a given column use the same format.

For numeric or datetime formatting, missing value indicators can also be specified for each data item using a separate two-dimensional array, or a zero-sized array can be used to accept the missing value indications that are transmitted within the floating point data itself.

The formats to be used for each column of data must have been loaded previously (see Load) and are indicated by an array of format IDs. Because an ID represents a format independent of the width and decimals (w.d), additional input arrays are available to specify them.

Because data formatting can sometimes fail, the formatting operations include four output array parameters whose elements describe each individual warning or error that occurred during formatting. These four output arrays are all the same length. Corresponding elements in each array refer to the same failure. If these arrays are zero length, then there were no errors or warnings.

The three informatting methods are analogous in their use of parameters, although the input arrays are always strings, whereas the output arrays are the conversion type (numeric, datetime or character string). For conversions to numeric or datetime, missing value indicators are returned.

CORBA Definitions
 exception InvalidID  
 exception WrongType  
 enum IFType  Indicates format or informat.
 enum ImplType  The implementation of the format.
 enum DTType  Used for controlling the handling of date and time values in a particular formatting operation.
 enum FormattingMethod  When known, the formatting or informatting method call that the format or informat is compatible with.
 enum NameMatchOp  The way to use the name filtering string when enumerating formats.
 attribute Parent  
 attribute SearchPath  Search path for formats or informats implemented by PROC FORMAT. This is the equivalent of the FMTSEARCH SAS system option.
 attribute YearCutoff  Year cutoff for determining the century of two-digit year values.
 method EnumerateFormats  Given filtering criteria to search for formats and informats, returns an enumerator component which can list those that matched the filter.
 method Load  Load formats and informats to obtain IDs that can be used in other formatting calls.
 method Unload  Unload the indicated formats to free up server resources.
 method FormatNumericValues  Given a list of specific formats, format a two-dimensional array of doubles that contains one column for each specified format and one row for each observation.
 method FormatDateTimeValues  Given a list of specific formats, format a two-dimensional array of datetime values that contains one column for each specified format and one row for each observation.
 method FormatCharacterValues  Given a list of specific formats, format a two-dimensional array of strings that contains one column for each specified format and one row for each observation.
 method InformatNumericValues  Given a list of specific informats, convert a two-dimensional array of strings where there is one column for each specified informat and one row for each observation. The result is a a two-dimensional array of doubles.
 method InformatDateTimeValues  Given a list of specific informats, convert a two-dimensional array of strings where there is one column for each specified informat and one row for each observation. The result is a a two-dimensional array datetime values.
 method InformatCharacterValues  Given a list of specific informats, convert a two-dimensional array of formatted strings where there is one column for each specified informat and one row for each observation. The result is a a two-dimensional array of unformatted strings.


Java Classes
 IFormatServiceHelper  Used to manipulate the IFormatService type
 IFormatServiceHolder  Used to process the IFormatService type as an out parameter
 InvalidID  
 InvalidIDHelper  Used to manipulate the InvalidID type
 InvalidIDHolder  Used to process the InvalidID type as an out parameter
 WrongType  
 WrongTypeHelper  Used to manipulate the WrongType type
 WrongTypeHolder  Used to process the WrongType type as an out parameter
 IFType  Indicates format or informat.
 IFTypeHelper  Used to manipulate the IFType type
 IFTypeHolder  Used to process the IFType type as an out parameter
 IFTypeSeqHelper  Used to manipulate one dimensional arrays of the IFType type
 IFTypeSeqHolder  Used to process one dimensional arrays of the IFType type as an out parameter
 VariableArray2dOfIFTypeHelper  Used to manipulate two dimensional arrays of the IFType type
 VariableArray2dOfIFTypeHolder  Used to process two dimensional arrays of the IFType type
 ImplType  The implementation of the format.
 ImplTypeHelper  Used to manipulate the ImplType type
 ImplTypeHolder  Used to process the ImplType type as an out parameter
 ImplTypeSeqHelper  Used to manipulate one dimensional arrays of the ImplType type
 ImplTypeSeqHolder  Used to process one dimensional arrays of the ImplType type as an out parameter
 VariableArray2dOfImplTypeHelper  Used to manipulate two dimensional arrays of the ImplType type
 VariableArray2dOfImplTypeHolder  Used to process two dimensional arrays of the ImplType type
 DTType  Used for controlling the handling of date and time values in a particular formatting operation.
 DTTypeHelper  Used to manipulate the DTType type
 DTTypeHolder  Used to process the DTType type as an out parameter
 DTTypeSeqHelper  Used to manipulate one dimensional arrays of the DTType type
 DTTypeSeqHolder  Used to process one dimensional arrays of the DTType type as an out parameter
 VariableArray2dOfDTTypeHelper  Used to manipulate two dimensional arrays of the DTType type
 VariableArray2dOfDTTypeHolder  Used to process two dimensional arrays of the DTType type
 FormattingMethod  When known, the formatting or informatting method call that the format or informat is compatible with.
 FormattingMethodHelper  Used to manipulate the FormattingMethod type
 FormattingMethodHolder  Used to process the FormattingMethod type as an out parameter
 FormattingMethodSeqHelper  Used to manipulate one dimensional arrays of the FormattingMethod type
 FormattingMethodSeqHolder  Used to process one dimensional arrays of the FormattingMethod type as an out parameter
 VariableArray2dOfFormattingMethodHelper  Used to manipulate two dimensional arrays of the FormattingMethod type
 VariableArray2dOfFormattingMethodHolder  Used to process two dimensional arrays of the FormattingMethod type
 NameMatchOp  The way to use the name filtering string when enumerating formats.
 NameMatchOpHelper  Used to manipulate the NameMatchOp type
 NameMatchOpHolder  Used to process the NameMatchOp type as an out parameter
 NameMatchOpSeqHelper  Used to manipulate one dimensional arrays of the NameMatchOp type
 NameMatchOpSeqHolder  Used to process one dimensional arrays of the NameMatchOp type as an out parameter
 VariableArray2dOfNameMatchOpHelper  Used to manipulate two dimensional arrays of the NameMatchOp type
 VariableArray2dOfNameMatchOpHolder  Used to process two dimensional arrays of the NameMatchOp type


Java Interfaces
 IFormatService  A service that performs data conversion using SAS formats and informats.


Java Interface IFormatService

A service that performs data conversion using SAS formats and informats.

Package com.sas.iom.SAS

IFormatService Description
This component provides operations for enumerating the formats and informats that are available in a Workspace and for using those formats and informats to convert data.

The EnumerateFormats method lists formats and informats that are available in the Workspace. It provides numerous ways to filter the list, including by data type, by category (such as date or currency), and by name matching.

After the desired set of formats has been identified, you must load them via Load. This method returns format IDs that can then be used in the formatting calls.

There are three formatting and three informatting operations. Each supports a different data type: numeric, character, or datetime. These methods support the conversion of a two-dimensional array of data values in a single call. Numeric and datetime formatting handle SAS missing values. All of the methods provide detailed failure information for any individual conversion operation that fails.

Clients Unload formats when finished with them.

The three formatting operations follow similar conventions in the use of their parameters. The input values should be presented in a two-dimensional array that represents tabular data (such as values from a SAS data set or from an SQL result set). The columns in this array represent a specifc field or variable. All items in a given column use the same format.

For numeric or datetime formatting, missing value indicators can also be specified for each data item using a separate two-dimensional array, or a zero-sized array can be used to accept the missing value indications that are transmitted within the floating point data itself.

The formats to be used for each column of data must have been loaded previously (see Load) and are indicated by an array of format IDs. Because an ID represents a format independent of the width and decimals (w.d), additional input arrays are available to specify them.

Because data formatting can sometimes fail, the formatting operations include four output array parameters whose elements describe each individual warning or error that occurred during formatting. These four output arrays are all the same length. Corresponding elements in each array refer to the same failure. If these arrays are zero length, then there were no errors or warnings.

The three informatting methods are analogous in their use of parameters, although the input arrays are always strings, whereas the output arrays are the conversion type (numeric, datetime or character string). For conversions to numeric or datetime, missing value indicators are returned.

public interface IFormatService
extends org.omg.CORBA.Object

Method Summary

 IFormatEnumerator EnumerateFormats ( IFType[] IFTypesFilter , NameMatchOp op , java.lang.String nameFilterString , BaseType[] baseTypesFilter , ImplType[] implTypesFilter , java.lang.String keyword , FormattingMethod[] formattingMethodsFilter , org.omg.CORBA.IntHolder numFound )
throws ( GenericError );

Given filtering criteria to search for formats and informats, returns an enumerator component which can list those that matched the filter.

 void Load ( IFType[] IFTypes , java.lang.String[] names , IntSeqHolder IDs , StringSeqHolder failureMessages )
throws ( GenericError );

Load formats and informats to obtain IDs that can be used in other formatting calls.

 void Unload ( int[] IDs )
throws ( InvalidID, GenericError );

Unload the indicated formats to free up server resources.

 void FormatNumericValues ( int[] IDs , int[] widths , int[] decimals , double[][] values , octet[][] missings , VariableArray2dOfStringHolder formattedValues , IntSeqHolder exceptionRowIndices , IntSeqHolder exceptionColumnIndices , BooleanSeqHolder exceptionIsError , StringSeqHolder exceptionMessages )
throws ( InvalidID, WrongType, GenericError );

Given a list of specific formats, format a two-dimensional array of doubles that contains one column for each specified format and one row for each observation.

 void FormatDateTimeValues ( int[] IDs , DTType[] dateTimeTypes , int[] widths , int[] decimals , long[][] values , octet[][] missings , VariableArray2dOfStringHolder formattedValues , IntSeqHolder exceptionRowIndices , IntSeqHolder exceptionColumnIndices , BooleanSeqHolder exceptionIsError , StringSeqHolder exceptionMessages )
throws ( InvalidID, WrongType, GenericError );

Given a list of specific formats, format a two-dimensional array of datetime values that contains one column for each specified format and one row for each observation.

 void FormatCharacterValues ( int[] IDs , int[] widths , java.lang.String[][] values , VariableArray2dOfStringHolder formattedValues , IntSeqHolder exceptionRowIndices , IntSeqHolder exceptionColumnIndices , BooleanSeqHolder exceptionIsError , StringSeqHolder exceptionMessages )
throws ( InvalidID, WrongType, GenericError );

Given a list of specific formats, format a two-dimensional array of strings that contains one column for each specified format and one row for each observation.

 void InformatNumericValues ( int[] IDs , int[] widths , int[] decimals , java.lang.String[][] inputValues , VariableArray2dOfDoubleHolder values , VariableArray2dOfOctetHolder missings , IntSeqHolder exceptionRowIndices , IntSeqHolder exceptionColumnIndices , BooleanSeqHolder exceptionIsError , StringSeqHolder exceptionMessages )
throws ( InvalidID, WrongType, GenericError );

Given a list of specific informats, convert a two-dimensional array of strings where there is one column for each specified informat and one row for each observation. The result is a a two-dimensional array of doubles.

 void InformatDateTimeValues ( int[] IDs , DTType[] dateTimeTypes , int[] widths , java.lang.String[][] inputValues , VariableArray2dOfLongHolder values , VariableArray2dOfOctetHolder missings , IntSeqHolder exceptionRowIndices , IntSeqHolder exceptionColumnIndices , BooleanSeqHolder exceptionIsError , StringSeqHolder exceptionMessages )
throws ( InvalidID, WrongType, GenericError );

Given a list of specific informats, convert a two-dimensional array of strings where there is one column for each specified informat and one row for each observation. The result is a a two-dimensional array datetime values.

 void InformatCharacterValues ( int[] IDs , int[] widths , java.lang.String[][] inputValues , VariableArray2dOfStringHolder values , IntSeqHolder exceptionRowIndices , IntSeqHolder exceptionColumnIndices , BooleanSeqHolder exceptionIsError , StringSeqHolder exceptionMessages )
throws ( InvalidID, WrongType, GenericError );

Given a list of specific informats, convert a two-dimensional array of formatted strings where there is one column for each specified informat and one row for each observation. The result is a a two-dimensional array of unformatted strings.


CORBA Exception InvalidID

Description

Java Class InvalidID

public class InvalidID

java.lang.Object
  |
  +--java.lang.Throwable
        |
        +--java.lang.Exception
              |
              +--org.omg.CORBA.UserException
                    |
                    +--com.sas.iom.SAS.IFormatService_1_0Package.InvalidID

CORBA Exception WrongType

Description

Java Class WrongType

public class WrongType

java.lang.Object
  |
  +--java.lang.Throwable
        |
        +--java.lang.Exception
              |
              +--org.omg.CORBA.UserException
                    |
                    +--com.sas.iom.SAS.IFormatService_1_0Package.WrongType

CORBA Enum IFType

Indicates format or informat.

Description

Usage

Member Description
IFTypeFormat   
IFTypeInformat   

Java Class IFType

public class IFType

java.lang.Object
  |
  +--com.sas.iom.SAS.IFormatService_1_0Package.IFType

CORBA Enum ImplType

The implementation of the format.

Description

Usage

Member Description
ImplTypeSASInstalled  This format or informat is provided by the SAS System. This includes formats implemented in UWF load modules and informats implemented in UWI load modules.  
ImplTypePROCFormat  This format or informat was created by PROC FORMAT.  

Java Class ImplType

public class ImplType

java.lang.Object
  |
  +--com.sas.iom.SAS.IFormatService_1_0Package.ImplType

CORBA Enum DTType

Used for controlling the handling of date and time values in a particular formatting operation.

Description

Usage

Member Description
DTTypeDate   
DTTypeTime   
DTTypeDateTime   

Java Class DTType

public class DTType

java.lang.Object
  |
  +--com.sas.iom.SAS.IFormatService_1_0Package.DTType

CORBA Enum FormattingMethod

When known, the formatting or informatting method call that the format or informat is compatible with.

Description
When known, the formatting or informatting method call that the format or informat is compatible with. When the method is <>, the user must know enough about the format to select the correct method. Only one of these values is associated with a given format or informat.

Usage

Member Description
FormattingMethodNumeric  Identifies formats that work with FormatNumericValues and informats that work with InformatNumericValues.  
FormattingMethodDateTime  Identifies formats that work with FormatDateTimeValues and informats that work with InformatDateTimeValues.  
FormattingMethodCharacter  Identifies formats that work with FormatCharacterValues and informats that work with InformatCharacterValues.  
FormattingMethodUnknown  The SAS System does not know enough about the format or informat to determine which formatting or informatting method you should use.  
FormattingMethodNone  This format or informat processes binary data or data that is otherwise incompatible with any of the three formatting methods.  

Java Class FormattingMethod

public class FormattingMethod

java.lang.Object
  |
  +--com.sas.iom.SAS.IFormatService_1_0Package.FormattingMethod

CORBA Enum NameMatchOp

The way to use the name filtering string when enumerating formats.

Description

Usage

Member Description
NameMatchOpAll  The format or informat name must match the entire filter string.  
NameMatchOpBeginning  The filter string must match the beginning of the format or informat name.  
NameMatchOpBeginningDollarOptional  The filter string must match the beginning of the format or informat name, but the dollar sign that is used at the beginning of character formats or informats is excluded from the comparison. Do not pass a dollar sign in the matching string.  
NameMatchOpContains  The filter string can be contained anywhere in the format or informat name.  

Java Class NameMatchOp

public class NameMatchOp

java.lang.Object
  |
  +--com.sas.iom.SAS.IFormatService_1_0Package.NameMatchOp

CORBA Attribute Parent (readonly)

Description
Navigate back to Parent.

Usage

Java Method Parent

public IUtilities Parent ();


CORBA Attribute SearchPath

Search path for formats or informats implemented by PROC FORMAT. This is the equivalent of the FMTSEARCH SAS system option.

Description

Usage

Java Method SearchPath

public java.lang.String SearchPath ();
public void SearchPath ( java.lang.String SearchPath );


CORBA Attribute YearCutoff

Year cutoff for determining the century of two-digit year values.

Description
Year cutoff for determining the century of two-digit year values. This attribute controls the YEARCUTOFF SAS System option for the workspace. The option and this attribute are two equivalent ways to set this value.

If you are processing two-digit year values, it is important that you consider the implied range of years for your application and set this value accordingly.

Usage

Java Method YearCutoff

public short YearCutoff ();
public void YearCutoff ( short YearCutoff );


CORBA Method EnumerateFormats

Given filtering criteria to search for formats and informats, returns an enumerator component which can list those that matched the filter.

Description
This call returns an enumerator which lists formats and informats available to the Workspace. Numerous filtering criteria are available to locate subsets of interest.

When the filtering criteria are arrays, you can supply a zero length array to indicate that you do not want to filter (restrict items) based on that criterion. Otherwise, the array elements represent target values to return.

Selected formats or informats must match all criteria specified by parameters to this call. If a format or informat does not match even one of the criteria, then it will not be included in the enumerator.

Usage

Java Method EnumerateFormats

public IFormatEnumerator EnumerateFormats (

    IFType[] IFTypesFilter ,
    NameMatchOp op ,
    java.lang.String nameFilterString ,
    BaseType[] baseTypesFilter ,
    ImplType[] implTypesFilter ,
    java.lang.String keyword ,
    FormattingMethod[] formattingMethodsFilter ,
    org.omg.CORBA.IntHolder numFound 
    )
    throws (
            GenericError
    );

Parameter Details

Parameter Direction Type Description
IFTypesFilter  in  IFType[]  An array of IFType values. Specify a zero-length array to get both formats and informats. Specify a single-element array to obtain one or the other.  
op  in  NameMatchOp  This parameter is a constant from the NameMatchOp enumeration. It controls the way the EnumerateFormats::nameFilterString parameter will be used. To avoid any name matching, specify NameMatchOpContains with an empty (zero-length) string for the EnumerateFormats::nameFilterString.  
nameFilterString  in  java.lang.String  A string used to match format and informat names according to the EnumerateFormats::op parameter.  
baseTypesFilter  in  BaseType[]  This parameter is an array of BaseType values, which is used to filter formats by data type. Specify a zero-length array to get both character and numeric formats. Specify a single-element array to obtain one or the other.  
implTypesFilter  in  ImplType[]  This parameter is an array of ImplType values, which is used to filter by implementation type. Specify a zero-length array to get both SAS installed and PROC FORMAT formats and informats. Specify a single-element array to obtain one or the other.  
keyword  in  java.lang.String  SAS installed formats can have descriptive keywords to help categorize their intended function. These keywords provide more specific categorizations than the numeric versus character distinction known to the SAS Language. The following keywords have already been standardized:
   num - numbers
   curr - currency
   char - character
   date - date without time-of-day specificity
   datetime - both date and time
   time - time of day (without indication of any particular day)
Additional keywords may be added in the future. A single format or informat can be labeled with more than one keyword.  
formattingMethodsFilter  in  FormattingMethod[]  An array of FormattingMethod values. Specify a zero-length array to avoid filtering on this criterion. Otherwise, specify an element that contains the appropriate enumeration value for each formatting method to select on.

For some formats (such as user-written formats), the SAS System does not have enough information to know which formatting methods will work. In other cases, such as for formats like IB4, that process binary data, none of the formatting method calls can be used (those formats are not supported via this interface).

For example, if you want to list only formats and informats that are known to work with the operations in this interface, then you would provide a three-elements array with the values: FormattingMethodNumeric, FormattingMethodCharacter, and FormattingMethodDateTime  

numFound  out  org.omg.CORBA.IntHolder  The number of formats selected.  


CORBA Method Load

Load formats and informats to obtain IDs that can be used in other formatting calls.

Description
Given two matching input arrays of IFType and name, attempt to load those formats or informats and return an ID array of the same length as the input arrays. Unsuccessful loads are indicated with an ID value of -1.

An array of failure messages is returned. There is one element for each failure (-1 value) in the IDs array.

The same name may be loaded more than once. The same ID will be returned each time for the same name. Names may be aliases and also return the same code. Formats should be unloaded subsequently by ID. If an ID is returned more than once by Load, it should be passed more than once to Unload.

You must specify the format names without w and d values. For example, "dollar" is correct, but "dollar8" and "dollar8.2" are not. The names may either be well known format and informat names from the SAS Language, or may be discovered through EnumerateFormats.

Usage

Java Method Load

void Load (

    IFType[] IFTypes ,
    java.lang.String[] names ,
    IntSeqHolder IDs ,
    StringSeqHolder failureMessages 
    )
    throws (
            GenericError
    );

Parameter Details

Parameter Direction Type Description
IFTypes  in  IFType[]  An array to distinguish whether the item to be loaded is a format or an informat.  
names  in  java.lang.String[]  An array of names of formats and informats to be loaded.  
IDs  out  IntSeqHolder  An array of IDs returned by the load function.  
failureMessages  out  StringSeqHolder  An array of messages explaining each load failure.  


CORBA Method Unload

Unload the indicated formats to free up server resources.

Description
Every loaded format should be unloaded.

The same name may be loaded more than once. The same ID will be returned each time for the same name. Names may be aliases and also return the same code. Formats should be subsequently unloaded by code. If a code is returned more than once by Load, it should be passed more than once to Unload.

Usage

Java Method Unload

void Unload (

    int[] IDs 
    )
    throws (
            InvalidID,
            GenericError
    );

Parameter Details

Parameter Direction Type Description
IDs  in  int[]  An array of IDs that specify previously loaded formats that should now be unloaded.  


CORBA Method FormatNumericValues

Given a list of specific formats, format a two-dimensional array of doubles that contains one column for each specified format and one row for each observation.

Description
Convert double-precision floating-point values to string form using SAS numeric formats.

See IFormatService Description for an explanation of conventions for the parameters of formatting operations.

Date and time formats may also be used with this method if the values are supplied as double-precision floating-point using the standard SAS encoding (seconds since midnight, January 1, 1960). The WrongType exception is raised only when a character format or any informat is provided.

Usage

Java Method FormatNumericValues

void FormatNumericValues (

    int[] IDs ,
    int[] widths ,
    int[] decimals ,
    double[][] values ,
    octet[][] missings ,
    VariableArray2dOfStringHolder formattedValues ,
    IntSeqHolder exceptionRowIndices ,
    IntSeqHolder exceptionColumnIndices ,
    BooleanSeqHolder exceptionIsError ,
    StringSeqHolder exceptionMessages 
    )
    throws (
            InvalidID,
            WrongType,
            GenericError
    );

Parameter Details

Parameter Direction Type Description
IDs  in  int[]  The IDs of the formats to be used for each column of data.  
widths  in  int[]  The widths (w) to be used for each column of data. This is an array of the same size as the FormatNumericValues::IDs parameter.

Passing -1 indicates that the format's default should be used. Passing a zero-length array requests that all columns use the default width.  

decimals  in  int[]  The "decimals" (d) to be used for each column of data. This is an array of the same size as the FormatNumericValues::IDs parameter. Many formats do not use "decimals". For such formats, this parameter is ignored.

Passing -1 indicates that the informat's default should be used. Passing a zero length array requests that all columns use the default decimals.  

values  in  double[][]  A two-dimensional array of input values to be formatted (converted to string).  
missings  in  octet[][]  The NumericMissingIgnore indicates that the numeric data value itself is used to determine whether the value is missing or not missing. Use this approach either when your data will not contain missing values, or when it does contain them, but you are confident that they will be preserved correctly in your client environment and over your middleware transports. Passing a zero-length array is equivalent to passing an array filled with NumericMissingIgnore indicators.

If you want to supply missing values to the server, but your client programming environment or middleware transport configurations cannot be relied on to preserve them in the data, then you can use NumericMissingDot, NumericMissingUnderscore or a value in the range of the constants NumericMissingA through NumericMissingZ to indicate a missing value. When these are passed as values for elements in this array parameter, the corresponding value in the actual numeric data is ignored.

When using missing value indicators to identify missing values, you use NotMissing or NumericMissingIgnore for data elements that you want to be recognized as non-missing. These two values have the same effect for non-missing data. If, however, you pass a missing value in conjunction with the NotMissing indicator, then the missing will be scrubbed by the server and the data item will be treated as a regular (non-missing) zero.  

formattedValues  out  VariableArray2dOfStringHolder  A two-dimensional array that returns the strings created by the formatting process.  
exceptionRowIndices  out  IntSeqHolder  This parameter gives the row index for each error or warning. This, together with the column index, indicates which input value had problems.  
exceptionColumnIndices  out  IntSeqHolder  The input column index for each formatting warning or error. This together with the row index will indicate which input value had problems.  
exceptionIsError  out  BooleanSeqHolder  A warning versus failure indicator for each formatting warning or error.  
exceptionMessages  out  StringSeqHolder  A message describing each formatting warning or error.  


CORBA Method FormatDateTimeValues

Given a list of specific formats, format a two-dimensional array of datetime values that contains one column for each specified format and one row for each observation.

Description
Convert client datetime values to string form using SAS numeric formats.

See IFormatService Description for an explanation of conventions for the parameters of formatting operations.

Usage

Java Method FormatDateTimeValues

void FormatDateTimeValues (

    int[] IDs ,
    DTType[] dateTimeTypes ,
    int[] widths ,
    int[] decimals ,
    long[][] values ,
    octet[][] missings ,
    VariableArray2dOfStringHolder formattedValues ,
    IntSeqHolder exceptionRowIndices ,
    IntSeqHolder exceptionColumnIndices ,
    BooleanSeqHolder exceptionIsError ,
    StringSeqHolder exceptionMessages 
    )
    throws (
            InvalidID,
            WrongType,
            GenericError
    );

Parameter Details

Parameter Direction Type Description
IDs  in  int[]  The IDs of the formats to be used for each column of data.  
dateTimeTypes  in  DTType[]  The input value is first converted to a SAS numeric value in datetime format (seconds since 12:00 a.m. January 1, 1960). For each column of data, the DTType is then considered. If the DTType is DTTypeDateTime, no further conversion is needed.

If the DTType is DTTypeDate, the SAS datetime is converted into a SAS date value (number of days since January 1, 1960). Any excess hours and minutes are ignored (they are truncated, not rounded).

Use of DTTypeTime with this call is discouraged because it requires an intermixing of client datetime encoding and SAS time-of-day conventions. When you use The SAS DTTypeTime, the input datetime is converted into a SAS time value (number of days since January 1, 1960) Any excess hours and minutes are ignored (they are truncated not rounded). Time-of-day value is computed as elapsed time since 12:00 a.m. January 1, 1960. Thus, for values less than 24 hours, you should generally specify (in the client's native datetime encoding) some time on the day of January 1, 1960. It is more consistent to use the FormatNumericValues in these cases because then both the datetime encoding and the time of day would use SAS conventions.  

widths  in  int[]  The widths to be used for each column of data. This is an array of the same size as the FormatDateTimeValues::IDs parameter.

Passing -1 indicates that the informat's default should be used. Passing a zero-length array requests that all columns use the default width.  

decimals  in  int[]  The decimals (d) to be used for each column of data. This is an array of the same size as the FormatDateTimeValues::IDs parameter. Many formats do not use "decimals". For such formats, this parameter is ignored.

Passing -1 indicates that the format's default should be used. Passing a zero-length array requests that all columns use the default width.  

values  in  long[][]  A two-dimensional array of input values to be formatted (converted to string).  
missings  in  octet[][]  A zero-sized array (either or both dimensions) indicates that missing values are indicated by the floating point data itself. See NumericMissingIgnore for a discussion of how missing value indicators can be used to specify missing values.  
formattedValues  out  VariableArray2dOfStringHolder  A two-dimensional array that returns the strings created by the formatting process.  
exceptionRowIndices  out  IntSeqHolder  This parameter gives the row index for each error or warning. This, together with the column index, indicates which input value has problems.  
exceptionColumnIndices  out  IntSeqHolder  The input column index for each formatting warning or error. This together with the row index will indicate which input value had problems.  
exceptionIsError  out  BooleanSeqHolder  A warning versus failure indicator for each formatting warning or error.  
exceptionMessages  out  StringSeqHolder  A message that describes each formatting warning or error.  


CORBA Method FormatCharacterValues

Given a list of specific formats, format a two-dimensional array of strings that contains one column for each specified format and one row for each observation.

Description
Convert raw character string values to formatted character string values using SAS character formats.

See IFormatService Description for an explanation of conventions for the parameters of formatting operations.

Usage

Java Method FormatCharacterValues

void FormatCharacterValues (

    int[] IDs ,
    int[] widths ,
    java.lang.String[][] values ,
    VariableArray2dOfStringHolder formattedValues ,
    IntSeqHolder exceptionRowIndices ,
    IntSeqHolder exceptionColumnIndices ,
    BooleanSeqHolder exceptionIsError ,
    StringSeqHolder exceptionMessages 
    )
    throws (
            InvalidID,
            WrongType,
            GenericError
    );

Parameter Details

Parameter Direction Type Description
IDs  in  int[]  The IDs of the formats to be used for each column of data.  
widths  in  int[]  The widths (w) to be used for each column of data. This is an array of the same size as the FormatCharacterValues::IDs parameter.

Passing -1 indicates that the format's default should be used. Passing a zero-length array requests that all columns use the default width.  

values  in  java.lang.String[][]  A two-dimensional array of input values to be formatted (converted to string).  
formattedValues  out  VariableArray2dOfStringHolder  A two-dimensional array that returns the strings created by the formatting process.  
exceptionRowIndices  out  IntSeqHolder  This parameter gives the row index for each error or warning. This, together with the column index, indicates which input value has problems.  
exceptionColumnIndices  out  IntSeqHolder  This parameter gives the row index for each error or warning. This, together with the column index, indicates which input value has problems.  
exceptionIsError  out  BooleanSeqHolder  A warning versus failure indicator for each formatting warning or error.  
exceptionMessages  out  StringSeqHolder  A message that describes each formatting warning or error.  


CORBA Method InformatNumericValues

Given a list of specific informats, convert a two-dimensional array of strings where there is one column for each specified informat and one row for each observation. The result is a a two-dimensional array of doubles.

Description
Convert character string values to double-precision floating-point (SAS numeric) values using SAS numeric informats.

See IFormatService Description for an explanation of conventions for the parameters of informatting operations.

Usage

Java Method InformatNumericValues

void InformatNumericValues (

    int[] IDs ,
    int[] widths ,
    int[] decimals ,
    java.lang.String[][] inputValues ,
    VariableArray2dOfDoubleHolder values ,
    VariableArray2dOfOctetHolder missings ,
    IntSeqHolder exceptionRowIndices ,
    IntSeqHolder exceptionColumnIndices ,
    BooleanSeqHolder exceptionIsError ,
    StringSeqHolder exceptionMessages 
    )
    throws (
            InvalidID,
            WrongType,
            GenericError
    );

Parameter Details

Parameter Direction Type Description
IDs  in  int[]  The IDs of the informats to be used for each column of data.  
widths  in  int[]  The widths (w) to be used for each column of data. This is an array of the same size as the InformatNumericValues::IDs parameter.

Passing -1 indicates that the informat's default should be used. Passing a zero length array requests that all columns of data get the default width.  

decimals  in  int[]  The decimals (d) to be used for each column of data. This is an array of the same size as the InformatNumericValues::IDs parameter. Many informats do not use "decimals". For such informats, this parameter is ignored.

Passing -1 indicates that the informat's default should be used. Passing a zero length array requests that all columns of data get the default decimals.  

inputValues  in  java.lang.String[][]  A two-dimensional array of strings to be converted to floating point.  
values  out  VariableArray2dOfDoubleHolder  A two-dimensional array of output values from the informatting operation.  
missings  out  VariableArray2dOfOctetHolder  Some client programming environments do not give convenient access to missing value indicators within a numeric (floating point) data value. Some middleware environments might not translate SAS missing values properly in cross-architecture data translations. For these reasons, IOM calls that return numeric values typically return an extra missing value indication for each value.

NotMissing indicates that the value is not missing. NumericMissingDot indicates the numeric (dot) missing. The underscore special missing is indicated by NumericMissingUnderscore. The A-Z special missings are indicated by values in the range between NumericMissingA and NumericMissingZ (inclusive).  

exceptionRowIndices  out  IntSeqHolder  This parameter gives the row index for each error or warning. This, together with the column index, indicates which input value has problems.  
exceptionColumnIndices  out  IntSeqHolder  This parameter gives the row index for each error or warning. This, together with the column index, indicates which input value has problems.  
exceptionIsError  out  BooleanSeqHolder  A warning versus failure indicator for each formatting warning or error.  
exceptionMessages  out  StringSeqHolder  A message that describes each formatting warning or error.  


CORBA Method InformatDateTimeValues

Given a list of specific informats, convert a two-dimensional array of strings where there is one column for each specified informat and one row for each observation. The result is a a two-dimensional array datetime values.

Description
Convert character string values to datetime values using SAS datetime informats.

See IFormatService Description for an explanation of conventions for the parameters of informatting operations.

Usage

Java Method InformatDateTimeValues

void InformatDateTimeValues (

    int[] IDs ,
    DTType[] dateTimeTypes ,
    int[] widths ,
    java.lang.String[][] inputValues ,
    VariableArray2dOfLongHolder values ,
    VariableArray2dOfOctetHolder missings ,
    IntSeqHolder exceptionRowIndices ,
    IntSeqHolder exceptionColumnIndices ,
    BooleanSeqHolder exceptionIsError ,
    StringSeqHolder exceptionMessages 
    )
    throws (
            InvalidID,
            WrongType,
            GenericError
    );

Parameter Details

Parameter Direction Type Description
IDs  in  int[]  The IDs of the informats to be used for each column of data.  
dateTimeTypes  in  DTType[]  A date, time or datetime informat produces a SAS numeric value. The interpretation of that value as a SAS date, SAS datetime, or SAS time, depends on the particular format being used. The client must specify which interpretation to expect of the informat (because this information is not, in general, defined to the SAS System).

If the DTType is DTTypeDateTime or DTTypeDate, then the output value is converted to a datetime in the client's format.

Use of the DTTypeTime with this call is discouraged because it requires an intermixing of client datetime encoding and SAS time-of-day conventions. When you use the SAS DTTypeTime, the SAS time is converted to a native datetime as an offset from January 1, 1960. Thus, for values less than 24 hours, the resultant datetime is some time on the day of January 1, 1960. In most client environments, time of day is not stored relative to January 1, 1960, therefore, it would be more consistent to use the InformatNumericValues in these cases because then both the datetime encoding and the time of day would use SAS conventions (seconds since 12:00 a.m. January 1, 1960).  

widths  in  int[]  The widths (w) to be used for each column of data. This is an array of the same size as the InformatDateTimeValues::IDs parameter.

Passing -1 indicates that the informat's default should be used. Passing a zero-length array requests that all columns use the default width.  

inputValues  in  java.lang.String[][]  A two-dimensional array of strings to be converted to datetime.  
values  out  VariableArray2dOfLongHolder  A two-dimensional array of output values from the informatting operation.  
missings  out  VariableArray2dOfOctetHolder  See NumericMissingIgnore for a discussion of how missing value indicators are returned.  
exceptionRowIndices  out  IntSeqHolder  This parameter gives the row index for each error or warning. This, together with the column index, indicates which input value has problems.  
exceptionColumnIndices  out  IntSeqHolder  The input column index for each formatting warning or error. This together with the row index indicates which input value has problems.  
exceptionIsError  out  BooleanSeqHolder  A warning versus failure indicator for each formatting warning or error.  
exceptionMessages  out  StringSeqHolder  A message describing each formatting warning or error.  


CORBA Method InformatCharacterValues

Given a list of specific informats, convert a two-dimensional array of formatted strings where there is one column for each specified informat and one row for each observation. The result is a a two-dimensional array of unformatted strings.

Description
Convert formatted character string values to unformatted character string values using SAS character informats.

See IFormatService Description for an explanation of conventions for the parameters of informatting operations.

Usage

Java Method InformatCharacterValues

void InformatCharacterValues (

    int[] IDs ,
    int[] widths ,
    java.lang.String[][] inputValues ,
    VariableArray2dOfStringHolder values ,
    IntSeqHolder exceptionRowIndices ,
    IntSeqHolder exceptionColumnIndices ,
    BooleanSeqHolder exceptionIsError ,
    StringSeqHolder exceptionMessages 
    )
    throws (
            InvalidID,
            WrongType,
            GenericError
    );

Parameter Details

Parameter Direction Type Description
IDs  in  int[]  The IDs of the informats to be used for each column of data.  
widths  in  int[]  The widths (w) to be used for each column of data. This is an array of the same size as the FormatCharacterValues::IDs parameter.

Passing -1 indicates that the informat's default should be used. Passing a zero-length array requests that all columns use the default width.  

inputValues  in  java.lang.String[][]  A two-dimensional array of formatted strings to be converted to unformatted strings.  
values  out  VariableArray2dOfStringHolder  A two-dimensional array of output values from the informatting operation.  
exceptionRowIndices  out  IntSeqHolder  This parameter gives the row index for each error or warning. This, together with the column index, indicates which input value has problems.  
exceptionColumnIndices  out  IntSeqHolder  The input column index for each formatting warning or error. This together with the row index indicates which input value has problems.  
exceptionIsError  out  BooleanSeqHolder  A warning versus failure indicator for each formatting warning or error.  
exceptionMessages  out  StringSeqHolder  A message that describes each formatting warning or error.  


Contents Developing Java Clients