## 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 specific 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 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 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 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 specific 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 , DateTime[][] 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 two-dimensional array of doubles.
void | InformatDateTimeValues ( int[] IDs , DTType[] dateTimeTypes , int[] widths , java.lang.String[][] inputValues , VariableArray2dOfDateTimeHolder 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 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 two-dimensional array of unformatted strings.

Java Class IFormatServiceHelper

public class IFormatServiceHelper

Description
Implementing class for methods (insert, extract, type, id, read, write, narrow) used to manipulate the IFormatService type.

    java.lang.Object
      |
      +--com.sas.iom.SAS.IFormatServiceHelper

Java Class IFormatServiceHolder

public class IFormatServiceHolder

Description
Implementing class for methods (_read, _write, _type) used to process the IFormatService type as an out parameter.

    java.lang.Object
      |
      +--com.sas.iom.SAS.IFormatServiceHolder

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

Java Class InvalidIDHelper

public class InvalidIDHelper

Description
Implementing class for methods (insert, extract, type, id, read, write) used to manipulate the InvalidID type.

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

Java Class InvalidIDHolder

public class InvalidIDHolder

Description
Implementing class for methods (_read, _write, _type) used to process the InvalidID type as an out parameter.

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

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

Java Class WrongTypeHelper

public class WrongTypeHelper

Description
Implementing class for methods (insert, extract, type, id, read, write) used to manipulate the WrongType type.

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

Java Class WrongTypeHolder

public class WrongTypeHolder

Description
Implementing class for methods (_read, _write, _type) used to process the WrongType type as an out parameter.

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

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

Java Class IFTypeHelper

public class IFTypeHelper

Description
Implementing class for methods (insert, extract, type, id, read, write) used to manipulate the IFType type.

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

Java Class IFTypeHolder

public class IFTypeHolder

Description
Implementing class for methods (_read, _write, _type) used to process the IFType type as an out parameter.

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

Java Class IFTypeSeqHelper

public class IFTypeSeqHelper

Description
Implementing class for methods (insert, extract, type, id, read, write) used to manipulate singly dimensioned arrays of IFType type.

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

Java Class IFTypeSeqHolder

public class IFTypeSeqHolder

Description
Implementing class for methods (_read, _write, _type) used to process singly dimensioned arrays of the IFType type as an out parameter.

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

Java Class VariableArray2dOfIFTypeHelper

public class VariableArray2dOfIFTypeHelper

Description
Implementing class for methods (insert, extract, type, id, read, write) used to manipulate doubly dimensioned arrays of IFType type.

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

Java Class VariableArray2dOfIFTypeHolder

public class VariableArray2dOfIFTypeHolder

Description
Implementing class for methods (_read, _write, _type) used to process doubly dimensioned arrays of the IFType type as an out parameter.

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

CORBA Enum ImplType

The implementation of the format.

Description

Usage

Member | Description
--- | ---
ImplTypeSASInstalled | This format or informat is provided by SAS. 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

Java Class ImplTypeHelper

public class ImplTypeHelper

Description
Implementing class for methods (insert, extract, type, id, read, write) used to manipulate the ImplType type.

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

Java Class ImplTypeHolder

public class ImplTypeHolder

Description
Implementing class for methods (_read, _write, _type) used to process the ImplType type as an out parameter.

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

Java Class ImplTypeSeqHelper

public class ImplTypeSeqHelper

Description
Implementing class for methods (insert, extract, type, id, read, write) used to manipulate singly dimensioned arrays of ImplType type.

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

Java Class ImplTypeSeqHolder

public class ImplTypeSeqHolder

Description
Implementing class for methods (_read, _write, _type) used to process singly dimensioned arrays of the ImplType type as an out parameter.

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

Java Class VariableArray2dOfImplTypeHelper

public class VariableArray2dOfImplTypeHelper

Description
Implementing class for methods (insert, extract, type, id, read, write) used to manipulate doubly dimensioned arrays of ImplType type.

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

Java Class VariableArray2dOfImplTypeHolder

public class VariableArray2dOfImplTypeHolder

Description
Implementing class for methods (_read, _write, _type) used to process doubly dimensioned arrays of the ImplType type as an out parameter.

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

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

Java Class DTTypeHelper

public class DTTypeHelper

Description
Implementing class for methods (insert, extract, type, id, read, write) used to manipulate the DTType type.

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

Java Class DTTypeHolder

public class DTTypeHolder

Description
Implementing class for methods (_read, _write, _type) used to process the DTType type as an out parameter.

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

Java Class DTTypeSeqHelper

public class DTTypeSeqHelper

Description
Implementing class for methods (insert, extract, type, id, read, write) used to manipulate singly dimensioned arrays of DTType type.

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

Java Class DTTypeSeqHolder

public class DTTypeSeqHolder

Description
Implementing class for methods (_read, _write, _type) used to process singly dimensioned arrays of the DTType type as an out parameter.

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

Java Class VariableArray2dOfDTTypeHelper

public class VariableArray2dOfDTTypeHelper

Description
Implementing class for methods (insert, extract, type, id, read, write) used to manipulate doubly dimensioned arrays of DTType type.

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

Java Class VariableArray2dOfDTTypeHolder

public class VariableArray2dOfDTTypeHolder

Description
Implementing class for methods (_read, _write, _type) used to process doubly dimensioned arrays of the DTType type as an out parameter.

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

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 FormattingMethodUnknown, 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 | SAS 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

Java Class FormattingMethodHelper

public class FormattingMethodHelper

Description
Implementing class for methods (insert, extract, type, id, read, write) used to manipulate the FormattingMethod type.

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

Java Class FormattingMethodHolder

public class FormattingMethodHolder

Description
Implementing class for methods (_read, _write, _type) used to process the FormattingMethod type as an out parameter.

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

Java Class FormattingMethodSeqHelper

public class FormattingMethodSeqHelper

Description
Implementing class for methods (insert, extract, type, id, read, write) used to manipulate singly dimensioned arrays of FormattingMethod type.

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

Java Class FormattingMethodSeqHolder

public class FormattingMethodSeqHolder

Description
Implementing class for methods (_read, _write, _type) used to process singly dimensioned arrays of the FormattingMethod type as an out parameter.

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

Java Class VariableArray2dOfFormattingMethodHelper

public class VariableArray2dOfFormattingMethodHelper

Description
Implementing class for methods (insert, extract, type, id, read, write) used to manipulate doubly dimensioned arrays of FormattingMethod type.

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

Java Class VariableArray2dOfFormattingMethodHolder

public class VariableArray2dOfFormattingMethodHolder

Description
Implementing class for methods (_read, _write, _type) used to process doubly dimensioned arrays of the FormattingMethod type as an out parameter.

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

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

Java Class NameMatchOpHelper

public class NameMatchOpHelper

Description
Implementing class for methods (insert, extract, type, id, read, write) used to manipulate the NameMatchOp type.

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

Java Class NameMatchOpHolder

public class NameMatchOpHolder

Description
Implementing class for methods (_read, _write, _type) used to process the NameMatchOp type as an out parameter.

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

Java Class NameMatchOpSeqHelper

public class NameMatchOpSeqHelper

Description
Implementing class for methods (insert, extract, type, id, read, write) used to manipulate singly dimensioned arrays of NameMatchOp type.

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

Java Class NameMatchOpSeqHolder

public class NameMatchOpSeqHolder

Description
Implementing class for methods (_read, _write, _type) used to process singly dimensioned arrays of the NameMatchOp type as an out parameter.

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

Java Class VariableArray2dOfNameMatchOpHelper

public class VariableArray2dOfNameMatchOpHelper

Description
Implementing class for methods (insert, extract, type, id, read, write) used to manipulate doubly dimensioned arrays of NameMatchOp type.

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

Java Class VariableArray2dOfNameMatchOpHolder

public class VariableArray2dOfNameMatchOpHolder

Description
Implementing class for methods (_read, _write, _type) used to process doubly dimensioned arrays of the NameMatchOp type as an out parameter.

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

CORBA Attribute Parent (readonly)

Description
Navigate back to Utilities.

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), SAS 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.

Example

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.

Example

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.

Example

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.

Example

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 ,
        DateTime[][] 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 | DateTime[][] | 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.

Example

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.

Example

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 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.

Example

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 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 ,
        VariableArray2dOfDateTimeHolder 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 SAS). 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 | VariableArray2dOfDateTimeHolder | 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.

Example

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 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.

Example