Defining object classes to match corresponding specialized data types in a relational database

[0002] 1. Field of the Invention

[0003] The present invention relates generally to computerized methods for accessing databases, and in particular, to a method for defining object classes to match corresponding specialized data types stored in a relational database.

[0004] 2. Description of Related Art

[0005] It is well known in the art to use database management systems, such as IBM's DB2™ relational database management system (RDBMS), to manage computerized databases. Currently, there is a need to access such databases using object-oriented application programs.

[0006] Object-oriented programming has become increasingly popular among software developers, because it offers the benefits of increased application program portability, interoperability, and interchangeability. Object-oriented programming techniques also reduce development risk and software development costs, and can extend the life cycle of the final product to prevent premature obsolescence.

[0007] An industry-consensus standard interface definition for interoperable object-oriented software, known as the Common Object Request Broker Architecture (CORBA), has been defined. CORBA simplifies the development and deployment of distributed systems software in several ways. First, CORBA defines a distributed environment using an object-oriented paradigm that hides differences between programming languages, operating systems, and object locations. Second, CORBA's object-oriented approach allows diverse types of implementations to inter-operate at the same level, hiding idiosyncrasies, and supporting reuse.

[0008] A central component of CORBA is an Object Request Broker (ORB), which functions as a communications infrastructure, transparently transceiving object requests across distributed heterogeneous computing environments. This is accomplished through a well-defined interface called the Interface Definition Language (IDL). Further details regarding CORBA and IDL are set forth in “The Essential CORBA, Systems Integration Using Distributed Objects,” by Thomas V. Mobray and Ron Zahavi, 1995, which publication is incorporated by reference herein.

[0009] Class libraries are available to support object-oriented programming environments such as CORBA. These class libraries allow users to generate application programs using previously-defined classes.

[0010] Some existing class libraries include classes for manipulating specialized data types such as date, decimal, duration, time, and timestamp data types. However, these class libraries do not specifically match the semantics of specialized data types retrieved from relational databases. The semantics of these specialized data types are available only through calls to a relational database management system. Thus, object-oriented application programs cannot access and manipulate specialized type data values from relational databases according to the object-oriented programming paradigm.

[0011] Therefore, there is a need in the art for technologies that access existing relational databases using object-oriented techniques. Moreover, such technologies should minimize the need for developing new application programs.

[0012] To overcome the limitations in the prior art described above, and to overcome other limitations that will become apparent upon reading and understanding the present specification, the present invention discloses a method, apparatus, and article of manufacture for defining object classes to match corresponding specialized data types stored in a relational database. An object-oriented application program may create an instance of a class for the purpose of representing data in a relational table that comprise a specialized data type. The attributes and behavior of the specialized data type in the database are preserved, where appropriate, in the corresponding class, and are available to the application program.

[0013] Various advantages and features of novelty, which characterize the invention, are pointed out with particularity in the claims annexed hereto and form a part hereof. However, for a better understanding of the invention, its advantages, and the objects obtained by its use, reference should be made to the drawings which form a further part hereof, and to accompanying descriptive matter, in which there is illustrated and described specific examples of an apparatus in accordance with the invention.

[0014] Referring now to the drawings in which like reference numbers represent corresponding parts throughout:

[0015] FIG. 1 is a block diagram illustrating an exemplary hardware environment used to implement the preferred embodiment of the present invention;

[0016] FIG. 2 is a block diagram that further illustrates the structure of a Component Broker according to the present invention; and

[0017] FIG. 3 is a flowchart illustrating the logic performed by an Application Program, Component Broker, and Relational Database Management System according to the preferred embodiment of the present invention.

[0018] In the following description of the preferred embodiment, reference is made to the accompanying drawings, which form a part hereof, and in which is shown byway of illustration a specific embodiment in which the invention may be practiced. It is to be understood that other embodiments may be utilized and structural changes may be made without departing from the scope of the present invention.

[0019] The present invention provides a method for accessing a relational database using object-oriented techniques by modeling specialized data types within the database using specific object classes. The present invention allows an object-oriented application program to create an instance of a class for the purpose of representing data in a relational table that comprise a specialized data type. The attributes and behavior of the specialized data type in the database are preserved, where appropriate, in the corresponding class, and are available to the application program.

[0020] FIG. 1 is a block diagram illustrating an exemplary hardware environment used to implement the preferred embodiment of the invention. A client computer 100 communicates with a server computer 102. Both the client computer 100 and the server computer 102 are typically comprised of one or more processors, random access memory (RAM), read-only memory (ROM), and other components such data storage devices and data communications devices.

[0021] The client computer 100 executes one or more computer programs 104 operating under the control of an operating system. These computer programs 104 transmit requests to the server computer 102 for performing various functions and receive data from the server computer 102 in response to the requests.

[0022] The server computer 102 also operates under the control of an operating system, and executes one or more computer programs 106, 108, and 110. These computer programs 106, 108, and 110 receive requests from the client computer 100 for performing various functions and transmit data to the client computers 100 in response to the requests.

[0023] The server computer 102 manages one or more databases 112 stored on one or more data storage devices (such as a fixed or hard disk drive, a floppy disk drive, a CD-ROM drive, a tape drive, or other device). In a preferred embodiment, the database 112 is managed by the DB2™ relational database management system (RDBMS) offered by IBM Corporation. Those skilled in the art will recognize, however, that the present invention may be applied to any database and associated database management system.

[0024] The preferred embodiment of the present invention is generally implemented using five major components executed by client computers 100 and server computers 102, including a Client Program 104, Application Program 106, Component Broker 108 (which comprises a variant of an Object Request Broker), relational database management system (RDBMS) 110, and database 112, wherein each of these components comprise instructions and/or data. In the preferred embodiment, the Client Program 104 provides a user interface, the Application Program 106 performs application functions, the Component Broker 108 materializes data retrieved from the database 112 as objects, and the database management system 110 controls access to the database 112.

[0025] Generally, these instructions and/or data 104-112 are all tangibly embodied in or retrievable from a computer-readable device, medium, or carrier, e.g., a memory, a data storage device, a remote device coupled to the computer via a data communications device, etc. Moreover, these instructions and/or data, when read, executed, and/or interpreted by the client computer 100 and/or server computer 102, causes the client computer 100 and/or server computer 102 to perform the steps necessary to implement and/or use the present invention.

[0026] Thus, the present invention may be implemented as a method, apparatus, or article of manufacture using standard programming and/or engineering techniques to produce software, firmware, hardware, or any combination thereof. The term “article of manufacture” (or alternatively, “computer program product”) as used herein is intended to encompass logic and/or data embodied in any device, medium, or carrier.

[0027] Of course, those skilled in the art will recognize many modifications may be made to this configuration without departing from the scope of the present invention. Those skilled in the art will also recognize that any combination of the above components, or any number of different components, including computer programs, peripherals, and other devices, may be used to implement the present invention, so long as similar functions are performed thereby.

[0028] FIG. 2 is a block diagram that further illustrates the structure of the Component Broker 112 according to the present invention. The Component Broker 112 provides a suite of tools that allows the user to write computer programs in an object-oriented programming context. In the preferred embodiment, the Component Broker 112 interacts with the Application Program 106. In alternative embodiments, the Component Broker 112 could interact with the Client Program 104 as well.

[0029] The Component Broker 112 is used to create and work with components 200, wherein a component 200 is a distributed set of objects that an Application Program 106 can access as a single entity and which work together to represent the logic and data relationships that perform a desired function for the Application Program 106.

[0030] In the present invention, the component 200 generally comprises a business object 202 and a data object 204, although other elements may be present as well. Business objects 202 include one or more methods and one or more attributes that are used directly by the Application Program 106. Data objects 204 also include one or more methods and one or more attributes that are used directly by the business objects 202 (and this indirectly by the Application Program 106).

[0031] Business objects 202 and data objects 204 are independent of any individual Application Program 106 and can be used in any combination to perform a desired task. A business object 202 may also have relationships with other business objects 202 and can cooperate with these other business objects 202 to perform a desired task.

[0032] Data objects 204 have direct access to data stored in the relational database 112 and are responsible for managing the persistence of state data for the component 200. By providing an interface between business objects 202 and the RDBMS 110, the data object 204 isolates the business object 202 from the details of the RDBMS 110 and relieves it from having to keep track of how to access and manage the data while maintaining persistency.

[0033] An Application Program 106 may access the data stored in the relational database 112 by interacting with business objects 202, which in turn interact with data objects 204, which in turn transmit requests to the RDBMS 110 using SQL functionality. For example, the data object 204 will generally have member functions that generate the appropriate SQL statements, package the statements, and forward them to the RDBMS 110 for execution, receive and process the results, and then return the results to the business objects 202, which ultimately provides access to the results to the Application Program 106.

[0034] As is well known, each column of a relational table 112 has a respective data type. Traditional data types include integer, floating point, logical, fixed length character, and variable length character data types. Some specialized data types include date, decimal, duration, time, and timestamp. Generally, SQL statements include expressions or functions that permit manipulation of the specialized data types. A description of specialized data types and their associated expressions or functions can be found in the publication by IBM Corporation entitled DB2 Universal Database SQL Reference V.5, S1OJ-8165-00, pp. 143-156, Copyright 1993, 1997.

[0035] The direct use of such SQL expressions or functions is disadvantageous in that the specialized data type must be retrieved from the table in the relational database 112, the function must be performed by the RDBMS 110, and the result must then be provided back to the data object 204. There would be advantages, then, to performing these functions for specialized data types in an object, rather than the RDBMS 110. However, prior art class libraries do not support specialized data types.

[0036] In the present invention, the Component Broker 108 provides helper classes 206, 208, 210, 212, and 214 that emulate the semantics of the corresponding specialized data types for use in various operations, such as comparison operations, arithmetic operations, etc. In the preferred embodiment, these classes 206,208, 210, 212, and 214 include:

[0037] ICBCDate Class 206 (representing the Date type).

[0038] ICBCDecimal Class 208 (representing the Decimal type).

[0039] ICBCDuration Class 210 (representing the Date Duration, Time Duration, Timestamp duration, and Labeled Duration types). The Duration data type is complementary to the Date, Time, and Timestamp classes, but is not, itself, stored in tables in the relational database 112.

[0040] ICBCTime Class 212 (representing the Time type).

[0041] ICBCTimestamp Class 214 (representing the Timestamp type).

[0042] (The abbreviation ICBC stands for IBM Component Broker Class.)

[0043] Each helper class 206, 208, 210, 212, and 214 provides a public interface (i.e., IDL) for accessing the attributes and for invoking the methods or member functions of the class. In each case, the public interface of the class is designed to match the characteristics and usage of the particular specialized data type in the RDBMS 110. As a result, methods or member functions performed by these classes 206, 208, 210, 212, and 214 produce the same results as equivalent SQL expressions evaluated by the RDBMS 110. Thus, the Application Program 106 uses the helper class objects 206, 208, 210, 212, and 214 to manipulate Dates, Decimals, Durations, Times, or Timestamps whenever it is desirable that the results should be consistent with those that would be produced by the RDBMS 110 itself.

[0044] In the preferred embodiment, the helper classes 206, 208, 210, 212, and 214 are implemented in accordance with specialized data types and associated expressions or functions found in the DB2™ RDBMS 110 sold by IBM Corporation. However, those skilled in the art will recognize that the classes 206, 208, 210, 212, and 214 can be implemented to accommodate specialized data types from any RDBMS 110, such as those offered by ORACLED™, SYBASE™, MICROSOFT™, etc.

[0045] Descriptions of the helper classes 206, 208, 210, 212, and 214, and a list of at least some of their methods or member functions are provided below. In addition, the Programming Language Reference included below provides additional descriptions of the various attributes and methods associated with the helper classes 206, 208, 210, 212, and 214.

[0046] The ICBCDate Class 206 stores the value of a calendar date between 01/01/0001 and 12/31/9999. AR access and manipulation of this date is through a public functional interface. The actual date value and its format are stored in private attributes.

[0047] Note that ICBCDate Class 206 assumes the proleptic Gregorian calendar. The Gregorian calendar in use today is assumed to extend back to year 0001 and it is the responsibility of the application to apply any corrections that may be required for dates prior to the Gregorian calendar reform.

[0048] The ICBCDate Class 206 includes a number of different methods such as object initialization, comparisons, query functions, and manipulation functions. The object initialization methods include initializeFromString, initializeFromNumber, itializeFromTimestamp, and initalizeFromValues methods. The comparison methods include equalTo, notEqualTo, lessThan, lessThanOrEqualTo, greaterThan, and greaterThanOrEqualTo. The query functions methods include OutputFormat, formattedString, day, dayOfWeek, dayOfYear, julianDay, modifiedJulianDay, dayName, dayFromString, dayOfWeekFromString, dayOfYearFromString, julianDayFromString, modifiedJulianDayFromString, dayNameFromString, dayNameFromNumber, month, monthName, monthFromString, monthNameFromString, monthNameFromNumber, quarter, quarterFromstring, year, yearFromString, isLeapYear, daysInObject, daysInString, daysInMonth, daysInYear, isVaidMonthDayYear, isValidYearDay, and isObjectChanged. The manipulation methods include assignFromDate, increment, decrement, dateOverflow, intervalFromDate, intervalFromString, and intravalFromLong.

[0049] The ICBCDecimal Class 208 stores the value of a Decimal data type (from a DB2™ RDBMS 110) or number type (from an ORACLE™ RDBMS 110) in which scale is less than or equal to precision, and positive with a specified maximum precision (e.g., 38). All access and manipulation of this value is through a public functional interface. The actual decimal value and its precision and scale are stored in private attributes.

[0050] The ICBCDecimal Class 208 includes a number of different methods such as object initialization, comparisons, query functions, and manipulation functions. The object initialization methods include initializeFromString1, initializeFromString2, initializeFromDouble, initializeFromFloat, initializeFromLong, initializeFromShort, initializdFormDecimal1, initializeFromDecimal2, and initiaizeFromPackedDecimal. The comparison methods include equalTo, notEqualTo, lessThan, lessThanOrEqualTo, greaterThan, and greaterThanOrEqualTo. The query functions methods include getAsFormattedString1, getAsFormattedString2, getAsFormattedString3, getAsDouble, getAsFloat, getAsLong, getAsShort, getAsDigits, getAsPackedDecimal, getPrecision, getScale, isNegative, and isChanged. The manipulation methods include assignFromDecimal, assignFromDouble, assignFromFloat, assignFromLong, assignFromShort, increment, decrement, multiplyThisObjectBy, divideThisObjectBy, remainderInThisObject, addWithNewObject, subtractWithNewObject, multiplyWithNewObject, divideWithNewObject, remainderWithNewObject, getPrecedingRemainder, swapSign, and decimalOverflow.

[0051] The ICBCDuration Class 210 represents the “Labeled Duration”, “Date Duration”, “Time Duration”, and “Timestamp Duration” constructs of Duration. Duration is complementary data type to Date, Time, and Timestamp, and participates in expressions in SQL statements. However, it is not, itself, stored in tables in the relation database 112.

[0052] The Class 210 holds the value of a duration, and a record of whether this duration value is in units of years, months, days, hours, minutes seconds, or microseconds. The value can also be of a composite type defining a “Date Duration” of the form yyyymmdd, a “Time Duration” of the form hhmmss, or a “Timestamp Duration” of the form yyyymmddhhmmsszzzzz.

[0053] In the preferred embodiment, arithmetic between two ICBCDuration Class 210 objects is not supported (which is consistent with DB2™ support of Durations). However, they can be compared, and a unary minus operator (which swaps the sign) is provided.

[0054] The ICBCDuration Class 210 includes a number of different methods such as object initialization, comparisons, query functions, and manipulation functions. The object initialization methods include initializeLabeledDuration, initializeDateTimeDuration, and initializeTimestampDuration. The comparison methods include equalTo, notEqualTo, lessThan, lessThanOrEqualTo, greaterThan, and greaterThanOrEqualTo. The query functions methods include isNegative, microsecond, second, minute, hour, day, month, year, size, and formattedString. The manipulation function methods include assignFromDuration, and swapSign.

[0055] The ICBTime Class 212 stores the value of a time-of-day. All access and manipulation of this time is through a public functional interface. The actual time value and its format are stored in private attributes.

[0056] The ICBCTime Class 212 includes a number of different methods such as object initialization, comparisons, query functions, and manipulation functions. The object initialization methods include initializeFromString, initiailzeFromTimestamp, and initializeFromValues. The comparison methods include equalTo, notEqualTo, lessThan, lessThanOrEqualTo, greaterThan, and greaterThanOrEqualTo. The query functions methods include second, minute, hour, and isObjectChanged. The manipulation functions methods include assignFromTime, increment, decrement, timeOverflow, intervalFromTime, and intervalFromString.

[0057] The ICBCTimestamp Class 214 stores the value of a Timestamp type (from a DB2™ RDBMS 110) or a DATE type (from an ORACLE™ RDBMS 110). All access and manipulation of this timestamp is through a public functional interface; the actual timestamp value is stored in private attributes.

[0058] In the preferred embodiment, a Timestamp attribute in a business object 204 that originates from the database 112 is represented by Component Broker 108 as a 26 character string of form yyyy-mm-dd-hh.mm.ss.mmmmmm. This string can be used to initialize an instance of the ICBCTimestamp Class 214 through the initializeFromString function. A DATE attribute that originates from an ORACLE™ database 112 is represented by Component Broker 108 in the same 26 character form yyyy-mm-dd-hh.mm.ss.mmmmmm; but with the final six characters (the microseconds field) always set to zeros. This string can be used to initialize an instance of the ICBCTimestamp Class 214 via initializeFromString function. However, ORACLES™ dates earlier than 0001-01-01 are rejected. Whether the ICBCTimestamp object is initialized from data originating in a DB2™ or in ORACLE™ database 112, ICBCTimestamp applies DB2™ semantics in its processing of the data.

[0059] The ICBCTimestamp Class 214 includes a number of different methods such as object initialization, comparisons, query functions, and manipulation functions. The object initialization methods include initializeFromString, initializeFromDateTime, initializeFromDate, initializeFromTime, and initiaizeFromDataStoreFormat. The comparison methods include equalTo, notEqualTo, lessThan, lessThanOrEqualTo, greaterThan, and greaterThanOrEqualTo. The query functions methods include formattedString, getAsDateFormattedString, getAsTimeFormattedString, getAsDatstoreFormat, microsecond, second, minute, hour, day, month, year, dayOfWeek, dayOfYear, julianDay, modifiedJulianDay, dayName, dayFromString, dayOfWeekFromString, dayOfYearFromString, julianDayFromString, modifiedJulianDayFromString, dayNameFromString, dayNameFromNumber, monthName, monthFromString, monthNameFromString, monthNameFromNumber, quarter, quarterFromString, yearFromString, isLeapYear, daysInObject, daysInString, daysInMonth, daysInYear, and isObjectChanged. The manipulation functions methods include assignFromTimestamp, increment, decrement, timestampOverflow, intervalFromTimestamp, and intervalFromString.

[0060] FIG. 3 is a flowchart illustrating the logic performed by the Application Program 106, Component Broker 108, and RDBMS 110 according to the preferred embodiment of the present invention.

[0061] Block 300 represents the Component Broker 108 instantiating one or more of the helper classes 206, 208, 210, 212, and 214 as objects. Generally, this step is performed in response to a request from the Application Program 106, although other events may trigger this step as well.

[0062] Block 302 represents the Component Broker 108 retrieving one or more tuples comprised of at least a Date, Decimal, Duration, Time, or Timestamp column or attribute from a table in the relational database 112. This retrieval step is performed via the data object 204 within the Component Broker 108, wherein the data object 204 has member functions that generate appropriate SQL statements, package the statements, and forward them to the RDBMS 110 for execution.

[0063] Block 304 represents the Component Broker 108 storing the requested data retrieved from the table in the relational database 112 as a string attribute in a business object 202. This storage step is also performed via the data object 204 within the Component Broker 108, wherein the data object 204 has member functions that receive and process the results from the execution of the SQL statements by the RDBMS 110, and then return the results to the business objects 202.

[0064] Block 306 represents the Application Program 106 retrieving the string attribute from the business object 202 in the Component Broker 108.

[0065] Block 308 represents the Application Program 106 using the retrieved string attribute to initialize one or more of the helper class objects 206, 208, 210, 212, or 214 in the Component Broker 108.

[0066] Block 310 represents the Application Program 106 performing one or more various operations, such as object initialization, comparisons, query functions, manipulation functions, arithmetic operations, etc., on the helper class objects 206, 208, 210, 212, or 214.

[0067] Block 312 represents the Application Program 106 extracting the string attribute from the helper class objects 206, 208, 210, 212, or 214 in the Component Broker 108.

[0068] Block 314 represents the Application Program 106 updating the attribute in the business object 202 using the extracted string attribute.

[0069] Block 316 represents the Component Broker 108 storing the updated string attribute from the business object 202 into the relational database 112. This storing step is performed via the data object 204 within the Component Broker 108, wherein the data object 204 has member functions that generate appropriate SQL statements, package the statements, and forward them to the RDBMS 110 for execution.

[0070] This concludes the description of the preferred embodiment of the invention. The following paragraphs describe some alternative methods of accomplishing the same objects.

[0071] In alternative embodiments of the present invention, other types and configurations of computers could be used. For example, the invention need not be restricted to client-server configurations. In addition, mainframes, minicomputers, or personal computers, could be used with the present invention.

[0072] In alternative embodiments of the present invention, other types and configurations of computer programs could be used. For example, the invention need not be restricted to COBRA environments, but could be used with COM, DCOM, or other object-oriented environments.

[0073] In alternative embodiments of the present invention, other database management systems could be used. For example, the invention need not be restricted to DB2™ relational database in management systems. Instead, the present invention could be used to model other types of databases and datastores.

[0074] In summary, the present invention discloses a method, apparatus, and article of manufacture for defining object classes to match corresponding specialized data types stored in a relational database. An object-oriented application program may create an instance of a class for the purpose of representing data in a relational table that comprise a specialized data type. The attributes and behavior of the specialized data type in the database are preserved, where appropriate, in the corresponding class, and are available to the application program.

[0075] The foregoing description of the preferred embodiment of the invention has been presented for the purposes of illustration and description. It is not intended to be exhaustive or to limit the invention to the precise form disclosed. Many modifications and variations are possible in light of the above teaching. It is intended that the scope of the invention be limited not by this detailed description, but rather by the claims appended hereto.

[0076] Programming Language Reference

[0077] The following Programming Language Reference provides descriptions of the various attributes and methods associated with the helper classes 206, 208, 210, 212, and 214. These descriptions describe the implementation of the preferred embodiment of the present invention, and are not intended to be limiting in any way. Specifically, those skilled in the art will recognize that different methods, attributes, functionality or implementations may be made without departing from the scope of the present invention.

[0078] ICBCDate Class

[0079] The class stores the value of a calendar date between 01/01/0001 and 12/31/9999. All access and manipulation of this date is through a public functional interface. The actual date value and its format are stored in private attributes.

[0080] Note that ICBCDate assumes the proleptic Gregorian calendar. The Gregorian calendar in use today is assumed to extend back to year 0001 and it is the responsibility of the application to apply any corrections that may be required for dates prior to the Gregorian calendar reform.

[0081] IDL Interface Description

[0082] interface ICBCDate: IManagedLocal::ILocalOnly

[0083] {

[0084] // Object initialization

[0085] boolean initializeFromString(in string aDate);

[0086] boolean initializeFromNumber(in long aDate);

[0087] boolean initializeFromTimestamp(in ICBCTimestamp aTimestamp);

[0088] boolean initializeFromValues(in long aYear, in long aMonth,

[0089] in long aDay);

[0090] // Comparisons

[0091] boolean equalTo(in ICBCDate aDate);

[0092] boolean notEqualTo(in ICBCDate aDate);

[0093] boolean lessThan(in ICBCDate aDate);

[0094] boolean lessThanOrEqualTo(in ICBCDate aDate);

[0095] boolean greaterThan(in ICBCDate aDate);

[0096] boolean greaterThanOrEqualTo(in ICBCDate aDate);

[0097] // Query functions

[0098] in enum OutputFormat {ISO, USA, EUR, JIS, LOC)};

[0099] string formattedString(inout string aTarget,

[0100] in ICBCDate::OutputFormat aFormat);

[0101] long day( );

[0102] long dayOfWeek( );

[0103] long dayOfYear( );

[0104] long julianDay( );

[0105] long modifiedJulianDay( );

[0106] string dayName( );

[0107] long dayFromString(in string aString);

[0108] long dayOfWeekFromString(in string aDate);

[0109] long dayOfYearFromString(in string aDate);

[0110] long julianDayFromString(in string aDate);

[0111] long modifiedJulianDayFromString(in string aDate);

[0112] string dayNameFromString(in string aDate);

[0113] string dayNameFromNumber(in long aDayIndex);

[0114] long month( );

[0115] string monthName( );

[0116] long monthFromString(in string aDate);

[0117] string monthNameFromString(in string aDate)

[0118] string monthNameFromNumber(in long aMonthIndex);

[0119] long quarter( );

[0120] long quarterFromstring(in string aDate);

[0121] long year( );

[0122] long yearFromString(in string aString);

[0123] boolean isLeapYear(in long aYear);

[0124] long daysInObject( );

[0125] long daysInString(in string aDate);

[0126] long daysInMonth(in long aYear, in long aMonth);

[0127] long daysInYear(in long aYear);

[0128] boolean isValidMonthDayYear(in long aMonth, in long aDay,

[0129] in long aYear);

[0130] boolean isValidYearDay(in long aYear, in long aDay);

[0131] boolean isObjectChanged( );

[0132] // Manipulation functions

[0133] void assignFromDate(in ICBCDate aDate);

[0134] void increment(in ICBCDuration aDuration);

[0135] void decrement(in ICBCDuration aDuration);

[0136] long dateOverflow( );

[0137] ICBCDuration intervalFromDate(in ICBCDate aDate);

[0138] ICBCDuration intervalFromString(in string aDate);

[0139] ICBCDuration intervalFromLong(in long aDate);

[0140] };

[0141] Supported Methods

[0142] ICBCDate::_create

[0143] ICBCDate::assignFromDate

[0144] ICBCDate::dateOverflow

[0145] ICBCDate::day

[0146] ICBCDate::dayFromString

[0147] ICBCDate::dayName

[0148] ICBCDate::dayNameFromNumber

[0149] ICBCDate::dayNameFromString

[0150] ICBCDate::dayOfWeek

[0151] ICBCDate::dayOfWeekFromString

[0152] ICBCDate::dayOfYear

[0153] ICBCDate::dayOfYearFromString

[0154] ICBCDate::daysInMonth

[0155] ICBCDate::daysInObject

[0156] ICBCDate::daysInString

[0157] ICBCDate::daysInYear

[0158] ICBCDate::decrement

[0159] ICBCDate::equalTo

[0160] ICBCDate::formattedString

[0161] ICBCDate::greaterThan

[0162] ICBCDate::greaterThanOrEqualTo

[0163] ICBCDate::increment

[0164] ICBCDate::initializeFromNumber

[0165] ICBCDate::initializeFromString

[0166] ICBCDate::initializeFromTimestamp

[0167] ICBCDate::initializeFromValues

[0168] ICBCDate::interval

[0169] ICBCDate::isObjectChanged

[0170] ICBCDate::isLeapYear

[0171] ICBCDate::isValidMonthDayYear

[0172] ICBCDate::isValidYearDay

[0173] ICBCDate::julianDay

[0174] ICBCDate::julianDayFromString

[0175] ICBCDate::lessThan

[0176] ICBCDate::lessThanOrEqualTo

[0177] ICBCDate::modifiedJulianDay

[0178] ICBCDate::modifiedJulianDayFromString

[0179] ICBCDate::month

[0180] ICBCDate::monthFromString

[0181] ICBCDate::monthName

[0182] ICBCDate::monthNameFromNumber

[0183] ICBCDate::monthNameFromString

[0184] ICBCDate::notEqualTo

[0185] ICBCDate::quarter

[0186] ICBCDate::quarterFromString

[0187] ICBCDate::year

[0188] ICBCDate:yearFromString

[0189] ICBCDate::_create

[0190] Returns a pointer to a new IDBCDate object. The object is initialized to the current system date.

[0191] ICBCDate::assignFromDate

[0192] Sets all state data in this ICBCData object equal to the second ICBCData object. The change flag of this object is set to TRUE.

[0193] IDL Syntax

[0194] ICBCDate assignFromDate (in ICBCDate aDate);

[0195] ICBCDate::dateOverflow

[0196] Returns the number of overflow or underflow years of a preceding increment or decrement operation. For an increment, returns the years in excess of year 9999; for decrement, the number of years less than year 0001.

[0197] IDL Syntax

[0198] long dateOverflow( );

[0199] ICBCDate::day

[0200] Returns the day part of this object, as a number between 1 and 31.

[0201] IDL Syntax

[0202] long day( );

[0203] ICBCDate::dayFromString

[0204] Returns the day part Returns the day part of the date encoded in the input string parameter.

[0205] The input string parameter must conform to a format recognizable as a date. Refer to IBCDate::initializeFromString( ) for a description of supported formats. If the input parameter is not recognizable, a value of −1 is returned.

[0206] IDL Syntax

[0207] long dayFromString(in string aString);

[0208] ICBCDate::dayName

[0209] Returns a string containing the name of the day of the week for this date object.

[0210] IDL Syntax

[0211] string dayName( );

[0212] ICBCDate::dayNameFromNumber

[0213] Returns a string containing the name of the day of the week for the day number within a week provided in the input parameter. The input parameter must be a number between 1 and 7. Sunday is day number 1.

[0214] If the input parameter is not recognizable, an empty string is returned.

[0215] IDL Syntax

[0216] string dayNameFromNumber(in long aDayIndex);

[0217] ICBCDate::dayNameFromString

[0218] Returns a string containing the name of the day of the week for the date encoded in the input string parameter. The input string parameter must conform to a format recognizable as a date. Refer to ICBCDate::initializeFromString for a description of supported formats.

[0219] If the input parameter is not recognizable, an empty string is returned.

[0220] IDL Syntax

[0221] long dayNameFromString(in string aDate);

[0222] ICBCDate::dayOfWeek

[0223] Returns a number between 1 and 7 representing the day of the week for this date object. Sunday is day number 1.

[0224] IDL Syntax

[0225] long dayOfWeek( );

[0226] ICBCDate::dayOfWeekFromString

[0227] Returns a number between 1 and 7 representing the day of the week for the date encoded in the input string parameter. Sunday is day number 1.

[0228] The input string parameter must conform to a format recognizable as a date. Refer to ICBCDate::initializeFromString for a description of supported formats. If the input parameter is not recognizable, a value of −1 is returned.

[0229] IDL Syntax

[0230] long dayOfWeekFromString(in string aString);

[0231] ICBCDate::dayOfYear

[0232] Returns a number between 1 and 366 representing the day of the year for this date object. January 1 is day number 1.

[0233] IDL Syntax

[0234] long dayOfYear( );

[0235] ICBCDate::dayOfYearFromString

[0236] Returns a number between 1 and 366 representing the day of the year for the date encoded in the input string parameter. January 1 is day number 1.

[0237] The input string parameter must conform to a format recognizable as a date. Refer to ICBCDate::initializeFromString for a description of supported formats. If the input parameter is not recognizable, a value of −1 is returned.

[0238] IDL Syntax

[0239] long dayOfYearFromString(in string aString);

[0240] ICBCDate::daysInMonth

[0241] Returns the number of days in the month of the year provided in the input parameters. Month number must be between 1 and 12.

[0242] If the input parameters are not valid, a value of −1 is returned.

[0243] IDL Syntax

[0244] long daysInMonth(in long aYear, in long aMonth);

[0245] ICBCDate::daysInObject

[0246] Returns the number of days from January 1, 0001 to the date represented by this object, plus one day. For example, an object holding the date January 2, 0001 returns the value 2.

[0247] IDL Syntax

[0248] long daysInObject( );

[0249] ICBCDate::daysInString

[0250] Returns the number of days from January 1, 0001 to the date represented by the string parameter, plus one day. For example, an object holding the date 00010102 returns the value 2. If the string is invalid, the value −1 is returned.

[0251] IDL Syntax

[0252] long daysInString(in string aDate);

[0253] Parameters

[0254] The string must be one of the following:

[0255] A string of length 7 of the form yyyynnn.

[0256] A string of length 6 of the form yyyymmdd.

[0257] A punctuated string representation of a date.

[0258] aDate

[0259] For additional details on the string parameter, see ICBCDate::initializeFromString.

[0260] ICBCDate::daysInYear

[0261] Returns the number of days in the year provided in the input parameter.

[0262] If the input parameter is not valid, a value of −1 is returned.

[0263] IDL Syntax

[0264] long daysInYear(in long aYear);

[0265] ICBCDate::decrement

[0266] Subtracts a ICBCDuration from the value of this ICBCDate object.

[0267] IDL Syntax

[0268] void decrement(in ICBCDuration aDuration);

[0269] Remarks

[0270] This operation is performed essentially as the inverse of ICBCDate::increment. When the duration of type DATE is subtracted from a date, the date is decremented by the specified number of days, months, and years (in this order). If the years value of the result of an decrement operation is less than 0001 years, the years value of the result is set to 0001 and the number of underflow years can be retrieved as a negative number using ICBCDate::dateOverflow. The number of overflow years is cleared by the next assignFromDate or arithmetic operation on the object.

[0271] The change flag of this object is set to TRUE.

[0272] ICBCDate::equalTo

[0273] Returns TRUE if the date in this ICBCDate object is equal to the other ICBCDate object.

[0274] IDL Syntax

[0275] boolean equalTo(in ICBCDate aDate);

[0276] ICBCDate::formattedString

[0277] Returns the date value of this object as a string in a specified format. The parameter OutputType must take one of the values: ISO, USA, EUR, JIS. Formats are as described for ICBCDate::initializeFromString. The LOC site-defined operation described in the DB2 manual is not supported by ICBCDate.

[0278] The application must supply a non-const pointer to a target storage area long enough to receive the formatted date. The function returns a reference to this area.

[0279] IDL Syntax

[0280] string formattedString(inout string aOutput,

[0281] in ICBCDate::OutputFormat aFormat)

[0282] ICBCDate::greaterThan

[0283] Returns TRUE if the date stored in this ICBCDate object is greater than the other ICBCDate object.

[0284] IDL Syntax

[0285] boolean greaterThan(in ICBCDate aDate);

[0286] ICBCDate::greaterThanOrEqualTo

[0287] Returns TRUE if the date stored in this ICBCDate object is greater than or equal to the other ICBCDate object.

[0288] IDL Syntax

[0289] boolean greaterThanOrEqualTo(in ICBCDate aDate);

[0290] ICBCDate::increment

[0291] Adds a ICBCDuration to the value of this ICBCDate object. If the duration is negative, the operation is performed as a decrement. If a duration of type YEARS is added to the date, only the year portion of the date is affected. The month is unchanged, as is the day, unless the result would be February 29 of a non-leap-year. In this case, the day is changed to 28.

[0292] Similarly, if a duration of type MONTHS is added, only months and, if necessary, years are affected. Note that adding months to a Date is like turning the pages of a calendar, starting with the page on which the date appears. The day portion of the date is unchanged unless the result would be invalid (September 31, for example). In this case, the day is set to the last day of the month. If one or more months is added to a given date, and then the same number of months is subtracted from the result, the final date is not necessarily the same as the original date.

[0293] Adding a duration of type DAYS will, of course, affect the day portion of the date, and potentially the month and year.

[0294] When a duration of type DATE is added to a date, the date is incremented by the specified number of year, months, and days, in this order.

[0295] If the years value of the result of an increment operation is greater than 9999 years, then the years value of the result is set to 9999, and the number of overflow years can be retrieved using the dateOverflow( ) function. The number of overflow years is cleared by the next assignFromDate of arithmetic operation on the object.

[0296] The change flag of this object is set to TRUE.

[0297] IDL Syntax

[0298] void increment(in ICBCDuration aDuration);

[0299] ICBCDate::initializeFromNumber

[0300] Accepts a numerical value for the date. Any existing value in the object is replaced. The parameter aDate must be positive, non-zero, and less than 3652059. Creates a date that is (aDate−1) days beyond Jan. 1, 0001, i.e., Jan. 2, 0001 is day number 2. Returns TRUE if the number is a valid date representation, FALSE otherwise. If FALSE is returned the state of the object is unchanged.

[0301] IDL Syntax

[0302] boolean initializeFromNumber(in long aDate);

[0303] ICBCDate::initializeFromString

[0304] Accepts a value for the date in the form of a string. Returns TRUE if the string is a valid date representation and the object is successfully initialized. Any existing value in the object is replaced. Returns FALSE if the parameter is invalid. If FALSE is returned the state of the object is unchanged.

[0305] IDL Syntax

[0306] boolean initializeFromString(in string aDate);

[0307] Parameters

[0308] The string must be:

[0309] A string of length 7 of the form yyyynnn. The yyyyddd string must consist of entirely numeric characters with padding zeros where necessary—embedded signs or blanks are not allowed. However leading and trailing blanks are acceptable provided the string length is less than 20 characters. Only SBCS characters maybe present in the string.

[0310] A string of length 8 of the form yyyymmdd. The yyyymmdd string must consist of entirely numeric characters with padding zeros where necessary—embedded signs or blanks are not allowed. However leading and trailing blanks around the string are acceptable provided the string length is less than 20 characters. Only SBCS characters may be present in the string.

[0311] A valid punctuated string representation of a date, in one of the following valid forms:

[0312] aDate

[0313] International Standards Organization (ISO) (yyyy-mm-dd).

[0314] IBM USA standard (USA) (mm/dd/yyyy).

[0315] IBM European standard (EUR) (dd.mm.yyyy)

[0316] Japanese Industrial Standard Christian Era (JIS) (yyyy-mm-dd).

[0317] Leading and trailing blanks are acceptable provided the string length is less than 20 characters. Leading zeros may be omitted from the month and day portions. Only SBCS characters may be present in the string.

[0318] A string representation of a timestamp. Any of the string forms acceptable by the ICBCTimestamp::initializeFromString function are acceptable. For details refer to that function. Briefly, the forms include:

[0319] A punctuated string: yyyy-mm-dd-hh.mm.ss.nnnnnn.

[0320] A 14 byte string without punctuation, of the form: yyyymmddhhmmss.

[0321] ICBCDate::initializeFromTimestamp

[0322] Initializes this object from the date portion of a Timestamp object.

[0323] IDL Syntax

[0324] boolean initializeFromTimestamp(in ICBCTimestamp aTimestamp);

[0325] ICBCDate::initializeFromValues

[0326] Accepts the date in the form of three separate value parameters for year, month, and day. The values must make a valid date. Returns TRUE if the values are a valid date representation, FALSE otherwise. If FALSE is returned the state of the object is unchanged.

[0327] IDL Syntax

[0328] boolean initializeFromValues(in long aYear, in long aMonth,

[0329] in long aDay);

[0330] ICBCDate::interval

[0331] Calculates the Duration between two ICBCDate objects. The result is a pointer to a new ICBCDuration object of type DATE.

[0332] If the interval between DATE1 and DATE2 is required, and DATE1 is greater than or equal to DATE2, the operation is performed by subtracting DATE2 from DATE1. If, however, DATE1 is less than DATE2, DATE1 is subtracted from DATE2, and the sign of the result is made negative.

[0333] The following procedural description clarifies the steps involved in the operation result DATE1−DATE2.

[0334] If DAY(DATE2)<=DAY(DATE1)

[0335] then DAY(RESULT)=DAY(DATE1)−DAY(DATE2).

[0336] If DAY(DATE2)>DAY(DATE1)

[0337] then DAY(RESULT)=N+DAY(DATE1)−DAY(DATE2)

[0338] where N=the last day of MONTH(DATE2).

[0339] MONTH(DATE2) is then incremented by 1.

[0340] If MONTH(DATE2)<=MONTH(DATE1)

[0341] then MONTH(RESULT)=MONTH(DATE1)−MONTH(DATE2).

[0342] If MONTH(DATE2)>MONTH(DATE1)

[0343] then MONTH(RESULT)=12+MONTH(DATE1)−MONTH(DATE2).

[0344] YEAR(DATE2) is incremented by 1.

[0345] YEAR(RESULT)=YEAR(DATE1)−YEAR(DATE2).

[0346] IDL Syntax

[0347] ICBCDuration_ptr intervalFromDate(in ICBCDate aDate);

[0348] ICBCDuration_ptr intervalFromString(in string aDate);

[0349] ICBCDuration_ptr intervalFromLong(in long aDate);

[0350] In the cases with a string parameter, the parameter must be recognizable as a date. For details refer to the description of ICBCDate::initializeFromString. If the string is invalid, a pointer value of −1 is returned.

[0351] ICBCDate::isObjectChanged

[0352] Returns a boolean indicating whether the value of this object has been changed since it was initialized.

[0353] IDL Syntax

[0354] boolean isObjectChanged( );

[0355] ICBCDate::isLeapYear

[0356] Returns TRUE if the year number in the input parameter is a leap year, FALSE otherwise. Year number must be between 1 and 9999.

[0357] If the input parameter is not in this range, FALSE is returned.

[0358] IDL Syntax

[0359] boolean isLeapYear(in long aYear);

[0360] ICBCDate::isValidMonthDayYear

[0361] Returns TRUE if the provided values for month, day, and year make a valid date, and FALSE otherwise.

[0362] IDL Syntax

[0363] boolean isValidMonthDayYear(in long aMonth, in longMonth, in longYear);

[0364] ICBCDate::isValidYearDay

[0365] Returns TRUE if the provided values for year, and day within year make a valid date, and FALSE otherwise.

[0366] IDL Syntax

[0367] boolean isValidYearDay(in long aYear,in long aDay);

[0368] ICBCDate::julianDay

[0369] Returns the Julian day number corresponding to noon GMT on the date represented by this object. (Julian Day count started at noon, GMT, on January 1, 4712 BC

[0370] IDL Syntax

[0371] long julianDay( );

[0372] ICBCDate::julianDayFromString

[0373] Returns the Julian day number corresponding to noon GMT on the date encoded in the input string parameter. (Julian Day count started at noon, GMT, on January 1, 4712 BC). The input string parameter must conform to a format recognizable as a date. Refer to ICBCDate::initializeFromString for a description of supported formats. If the input parameter is not recognizable, a value of −1 is returned.

[0374] IDL Syntax

[0375] long julianDayFromString(in string aString);

[0376] ICBCDate::lessThan

[0377] Returns TRUE if the date stored in this ICBCDate object is less than the other ICBCDate object.

[0378] IDL Syntax

[0379] boolean lessThan(in ICBCDate aDate);

[0380] ICBCDate::lessThanOrEqualTo

[0381] Returns TRUE if the date stored in this ICBCDate object is less than or equal to the other ICBCDate object.

[0382] IDL Syntax

[0383] boolean lessThanOrEqualTo(in ICBCDate aDate);

[0384] ICBCDate::modifiedJulianDay

[0385] Returns the Modified Julian day number (MJD) corresponding to time 00:00:00 GMT on the date represented by this object. MJD is defined as Julian Day—2,400,000.5 days. It thus starts at time 00:00:00 (i.e. midnight), in line with normal civil practice, and unlike Julian Day which extends from noon to noon.

[0386] IDL Syntax

[0387] long modified Julianay( );

[0388] ICBCDate::modifiedJulianDayFromString

[0389] Returns the Modified Julian day number (MJD) corresponding to time 00:00:00 GMT on the date encoded in the input string parameter. MJD is defined as Julian Day—2,400,000.5 days. It thus starts at time 00:00:00 (i.e., midnight), in line with normal civil practice, and unlike Julian Day which extends from noon to noon.

[0390] The input string parameter must conform to a format recognizable as a date. Refer to ICBCDate::initializeFromString for a description of supported formats. If the input parameter is not recognizable, a value of −1 is returned.

[0391] IDL Syntax

[0392] long modifiedJulianDayFromString(in string aString);

[0393] ICBCDate::month

[0394] Returns the month part of this object, as a number between 1 and 12.

[0395] IDL Syntax

[0396] long month( );

[0397] ICBCDate::monthFromString

[0398] Returns the month part of the date encoded in the input string parameter. The input string parameter must conform to a format recognizable as a date. Refer to ICBCDate::initializeFromString for a description of supported formats.

[0399] If the input parameter is not recognizable, a value of −1 is returned.

[0400] IDL Syntax

[0401] long monthFromString(in string aString);

[0402] ICBCDate::monthName

[0403] Returns a string containing the name of the month of this object.

[0404] IDL Syntax

[0405] long monthName( );

[0406] ICBCDate::monthNameFromNumber

[0407] Returns a string containing the name of the month for the month number within a year provided in the input parameter. The input parameter must be a number between 1 and 12.

[0408] If the input parameter is not recognizable, an empty string is returned.

[0409] IDL Syntax

[0410] string monthNameFromNumber(in long aDayIndex);

[0411] ICBCDate::monthNameFromString

[0412] Returns a string containing the name of the month for the date encoded in the input sting parameter. The input string parameter must conform to a format recognizable as a date. Refer to ICBCDate::initializeFromString for a description of supported formats.

[0413] If the input parameter is not recognizable, an empty string is returned.

[0414] IDL Syntax

[0415] string monthNameFromString(in string aDate);

[0416] ICBCDate::notEqualTo

[0417] The opposite of the operator==member.

[0418] IDL Syntax

[0419] boolean notEqualTo(in ICBCDate aDate);

[0420] ICBCDate::quarter

[0421] Returns a number for the quarter within the year for this object. Dates between January 1 and March 31 are in the first quarter, and so on.

[0422] IDL Syntax

[0423] long quarter( );

[0424] ICBCDate::quarterFromString

[0425] Returns a number for the quarter within the year for the date encoded in the input string parameter. The input string parameter must conform to a format recognizable as a date. Refer to ICBCDate::initializeFromString for a description of supported formats. Dates between January 1 and March 31 are in the first quarter, and so on.

[0426] If the input parameter is not recognizable, a value of −1 is returned.

[0427] IDL Syntax

[0428] long quarterFromString(in string aDate);

[0429] ICBCDate::year

[0430] Returns the year part of the date.

[0431] IDL Syntax

[0432] longYear( );

[0433] ICBCDate::yearFromString

[0434] Returns the year part of the date encoded in the input string parameter. The input string parameter must conform to a format recognizable as a date. Refer to ICBCDate::initializeFromString for a description of supported formats.

[0435] If the input parameter is not recognizable, a value of −1 is returned.

[0436] IDL Syntax

[0437] long yearFromString(in string aString);

[0438] ICBCDecimal Class

[0439] The class stores the value of a DB2 Decimal data type, or Oracle number type in which scale is less than or equal to precision, and positive with a maximum precision of 38. All access and manipulation of this value is through a public functional interface. The actual decimal value and its precision and scale are stored in private attributes.

[0440] Throughout the description of ICBCDecimal, precision is the total number of digits in the decimal number; scale is the number of digits in the fractional part of the number−the number of digits that lie to the right of the decimal point.

[0441] IDL Interface Description

[0442] interface ICBCDecimal :IManagedLocal::ILocalOnly

[0443] {

[0444] // Object initialization CDB2 semantics)

[0445] boolean initializedFromString(in string aString, in short aPrecision,

[0446] in short aScale, in char aDecimalChar);

[0447] boolean initializeFromString(in string aString, in char aDecimalChar);

[0448] boolean initializeFromDouble(in double aDouble, in short aPrecision,

[0449] in short aScale);

[0450] boolean initializeFromDate(in float aFloat, in short aPrecision,

[0451] in short aScale);

[0452] boolean initializeFromLong(in long aLong, in short aPrecision,

[0453] in short aScale);

[0454] boolean initializeFromShort(in short aShort, in short aPrecision,

[0455] in short aScale);

[0456] boolean initializeFromDecimal1(in ICBCDecimal aDecimal, in short aPrecision,

[0457] in short aScale);

[0458] boolean initializeFromDecimal2(in ICBCDecimal aDecimal);

[0459] boolean initializeFromPackedDecimal(in string aString,in short aPrecision,

[0460] in short aScale);

[0461] //Comparisons

[0462] boolean equalTo(in ICBCDecimal aDecimal);

[0463] boolean notEqualTo(in ICBCDecimal aDecimal);

[0464] boolean lessThan(in ICBCDecimal aDecimal);

[0465] boolean lessThanOrEqualTo(in ICBCDecimal aDecimal);

[0466] boolean greaterThan(in ICBCDecimal aDecimal);

[0467] boolean greaterThanOrEqualTo(in ICBCDecimal aDecimal);

[0468] //Query functions

[0469] string getAsFormattedString1(inout string aOutput,

[0470] in char aDecimalCharacter);

[0471] string getAsFormattedString2(inout string aOutput,

[0472] in char aDecimalCharcter);

[0473] string getAsFormattedString3(inout string aOutput,

[0474] in char aDecimalCharaaer);

[0475] double getAsDouble( );

[0476] float getAsFloat( );

[0477] long getAsLong( );

[0478] short getAsShort( );

[0479] string getAsDigits(inout string aOutput);

[0480] string getAsPackedDecimal(inout string aOutput; inout short aPrecision,

[0481] inout short aScale);

[0482] short getPrecision( ); short getScale( );

[0483] boolean isNegative( );

[0484] boolean isChanged( );

[0485] // Manipulation functions

[0486] ICBCDecimal assignFromDecimal(in ICBCDecial aDecimal);

[0487] ICBCDecimal assignFromDouble(in double aDouble);

[0488] ICBCDecimal assignFromFloat(in float aFloat);

[0489] ICBCDecimal assignFromLong(in long aLong;

[0490] ICBCDecimal assignFromShort(in short aShort);

[0491] ICBCDecimal increment(in ICBCDecimal aDecimal);

[0492] ICBCDecimal decrement(in ICBCDecimal aDecimal);

[0493] ICBCDecimal multiplyThisObjectBy(in ICBCDecimal aDecimal);

[0494] ICBCDecimal divideThisObjectBy(in ICBCDecimal aDecimal);

[0495] ICBCDecimal remainderInThisObject(in ICBCDecimal aDecimal);

[0496] ICBCDecimal addWithNewObject(in ICBCDecial aDecimal);

[0497] ICBCDecimal subtractWithNewObject(in ICBCDecimal aDecimal);

[0498] ICBCDecimal multiplyWithNewObject(in ICBCDecimal aDecimal);

[0499] ICBCDecimal divideWithNewObject(in ICBCDecimal aDecimal);

[0500] ICBCDecimal remainderWithNewObject(in ICBCDecimal aDecimal);

[0501] ICBCDecimal getPrecedingRemainder( );

[0502] void swapSign( );

[0503] boolean decimalOverflow( );

[0504] };

[0505] Supported Methods

[0506] ICBCDecimal::addWithNewObject

[0507] ICBCDecimal::assignFromDecimal

[0508] ICBCDecimal::assignFromDouble

[0509] ICBCDecimal::assignFromFloat

[0510] ICBCDecimal::assignFromLong

[0511] ICBCDecimal::assignFromShort

[0512] ICBCDecimal::_create

[0513] ICBCDecimal::decimalOverflow

[0514] ICBCDecimal::decrement

[0515] ICBCDecimal::divideThisObjectBy

[0516] ICBCDecimal::divideWithNewObject

[0517] ICBCDecimal::equalTo

[0518] ICBCDecimal::getAsDouble

[0519] ICBCDecimal::getAsFloat

[0520] ICBCDecimal::getAsFormattedString1

[0521] ICBCDecimal::getAsFormattedString2

[0522] ICBCDecimal::getAsFormattedString3

[0523] ICBCDecimal::getAsDigits

[0524] ICBCDecimal::getAsLong

[0525] ICBCDecimal::getAsPackedDecimal

[0526] ICBCDecimal::getAsShort

[0527] ICBCDecimal::getPreceedingRemainder

[0528] ICBCDecimal::getPrecision

[0529] ICBCDecimal::getScale

[0530] ICBCDecimal::greaterThan

[0531] ICBCDecimal::greaterThanOrEqualTo

[0532] ICBCDecimal::increment

[0533] ICBCDecimal::initializeFromDecimal1

[0534] ICBCDecimal::initializeFromDecimal2

[0535] ICBCDecimal::initializeFromDouble

[0536] ICBCDecimal :initializeFromFloat

[0537] ICBCDecimal::initializeFromLong

[0538] ICBCDecimal::initializeFromPackedDecimal

[0539] ICBCDecimal::initializeFromShort

[0540] ICBCDecimal::initializeFromString1

[0541] ICBCDecimal::initializeFromString2

[0542] ICBCDecimal::isChanged

[0543] ICBCDecimal::isNegative

[0544] ICBCDecimal::lessThan

[0545] ICBCDecimal::lessThanOrEqualTo

[0546] ICBCDecimal::multiplyWithNewObject

[0547] ICBCDecimal::multiplyThisObjectBy

[0548] ICBCDecimal::notEqualTo

[0549] ICBCDecimal::remainderInThisObject

[0550] ICBCDecimal::remainderWithNewObject

[0551] ICBCDecimal::subtractWithNewObject

[0552] ICBCDecimal::swapSign

[0553] ICBCDecimal::addWithNewObject

[0554] Adds the receiving object and the argument ICBCDecimal object and returns a new ICBCDecimal object containing the result. The original operand objects are unchanged. The precision of the result object is:

[0555] min(38, max(p1−s1, p2−s2)+max(s1, s2)+1)

[0556] The scale is: max(s1, s2)

[0557] IDL Syntax

[0558] ICBCDecimal addWithNewObject(in ICBCDecimal aDecimal);

[0559] Remarks

[0560] After a addWithNewObject operation, the change flag of the new object is set to TRUE. The change flag of the original object is unchanged.

[0561] It is the application's responsibility to delete the new object, freeing its memory, when no longer needed.

[0562] If the non-zero digits to the left of the decimal point in the result object would exceed (p−s)of the result, or if other errors occur that prevent the creation of the new object, an ICBCDecimal pointer with value −1 is returned.

[0563] ICBCDecimal::assignFromDecimal

[0564] Sets the value of the receiving ICBCDecimal object equal to that of the second ICBCDecimal object. The precision and scale of the receiving object are not changed.

[0565] IDL Syntax

[0566] ICBCDecimal assignFromDecimal(in ICBCDecimal aDecimal);

[0567] Remarks

[0568] If the non-zero digits to the left of the decimal point in the source object exceed (P1−s1) of the receiving object (i.e.,the whole number of the source object will not fit in the receiving object), the receiving object is unchanged, and a following invocation of decimalOverflow( ) on the receiving object function will return the value TRUE.

[0569] The scale of the source object is reduced to fit the scale of the receiving object, if necessary, by truncating digits from the right.

[0570] Any remainder value in the source object resulting from a preceding division operation is not transferred to the receiving object.

[0571] The change flag of the receiving object is set to TRUE.

[0572] Note that this operation preserves the precision and scale of the receiving object, as in a DB2 regular assignment between two decimal types. In contrast, the ICBCDecimal::initializeFromDecimal( ) function sets the precision and scale of the receiving object, is as in the DB2 DECIMAL built-in function.

[0573] ICBCDecimal::assignFromDouble

[0574] Sets the value of a receiving ICBCDecimal object equal to a double variable. The precision and scale of the object is not changed.

[0575] IDL Syntax

[0576] ICBCDecimal assignFromDouble(in double aDouble);

[0577] Remarks

[0578] The operand is converted to a temporary decimal object of precision 38. Numbers less than 0.5E-38 will be rounded to zero. The temporary decimal number is then converted to the precision and scale of the receiving ICBCDecimal object.

[0579] If the non-zero digits to the left of the decimal point in the source object exceed (p1−s1) of the receiving object (.e., the whole number portion of the source object will not fit in the receiving object), the receiving object is unchanged, and a following invocation of decimalOverflow( ) function on the receiving object will return the value TRUE.

[0580] ICBCDecimal::assignFromFloat

[0581] Sets the value of a receiving ICBCDecimal object equal to a float variable. The precision and scale of the object is not changed.

[0582] IDL Syntax

[0583] ICBCDecimal assignFromFloat(in float afloat);

[0584] Remarks

[0585] The operand is converted to a temporary decimal object of precision 38. Numbers less than 0.5E-38 will be rounded to zero. The temporary decimal number is then converted to the precision and scale of the receiving ICBCDecimal object.

[0586] If the non-zero digits to the left of the decimal point in the source object exceed (P1−s1) of In the receiving object (i.e., the whole number portion of the source object will not fit in the receiving object), the receiving object is unchanged, and a following invocation of decimalOverflow( ) function on the receiving object will return the value TRUE.

[0587] ICBCDecimal::assignFromLong

[0588] Sets the value of a receiving ICBCDecimal object equal to a long variable. The precision and scale of the object is not changed.

[0589] IDL Syntax

[0590] ICBCDecimal assignFromLong(in long aLong);

[0591] Remarks

[0592] The operand is converted to a temporary decimal number, of precision 11 which is then converted to the precision and scale of the receiving object.

[0593] If the non-zero digits to the left of the decimal point in the source object exceed (p1−s1) of the receiving object (i.e., the whole number portion of the source object will not fit in the receiving object), the receiving object is unchanged, and a following invocation of decimalOverflow( ) function will return the value TRUE on the receiving object.

[0594] ICBCDecimal::assignFromShort

[0595] Sets the value of a receiving ICBCDecimal object equal to a short variable. The precision and scale of the object is not changed.

[0596] IDL Syntax

[0597] ICBCDecimal assignFromShort(in short aShort);

[0598] Remarks

[0599] The operand is converted to a temporary decimal number, of precision 5 which is then converted to the precision and scale of the receiving object.

[0600] If the non-zero digits to the left of the decimal point in the source object exceed (p1−s1) of the receiving object (i.e., the whole number portion of the source object will not fit in the receiving object), the receiving object is unchanged, and a following invocation of decimalOverflow( ) function on the receiving object will return the value TRUE.

[0601] ICBCDecimal::_create

[0602] Returns a pointer to a new ICBCDecimal object. The object is initialized to zero, with precision=1 and scale=0.

[0603] ICBCDecimal::decimalOverflow

[0604] Following certain functions that potentially cause a precision overflow in a ICBCDecimal object, this function indicates whether an overflow did, in fact, take place. If the most recent initialization, assignment, or arithmetic operation caused an overflow, this function will return TRUE. Otherwise it returns FALSE. Intervening query or comparison operations will not affect the returned value.

[0605] IDL Syntax

[0606] boolean decimalOverflow( );

[0607] ICBCDecimal::decrement

[0608] Subtracts the argument ICBCDecimal object from the receiving ICBCDecimal object and sets the value of the receiving object to the result. The precision and scale of the receiving object are reset.

[0609] The precision is given by:

[0610] min(38, max(p1−s1, p2−s2)+max(s1, s2)+1)

[0611] The scale is given by:

[0612] max(s1, s2)

[0613] If the non-zero digits to the left of the decimal point in the result exceed (p−s) of the result, the receiving object is not changed, and a following invocation of the function decimalOverflow( ) will return TRUE.

[0614] The change flag of the receiving object is set to TRUE.

[0615] IDL Syntax

[0616] ICBCDecimal decrement(in ICBCDecimal aDecimal);

[0617] ICBCDecimal::divideThisObjectBy

[0618] Divides the receiving object by the argument ICBCDecimal object, and sets the receiving object to the quotient. The precision and scale of the receiving object are reset.

[0619] The precision is 38.

[0620] The scale is given by:

[0621] 38−p1+s1−s2

[0622] Scale may not be negative.

[0623] The division proceeds as far as possible within these limits for the quotient and then stops. Any remainder can be retrieved using the getPrecedingRemainder( ) function (see ICBCDecimal::getPreceedingRemainder).

[0624] This function does not cause any overflow conditions. However, the decimalOverflow( ) function is used to warn of zeroDivide situations, returning TRUE if a zeroDivide occurred in the preceding divideThisObjectBy( ) function, and FALSE if it did not.

[0625] After a divideThisObjectBy operation, the change flag of the receiving object is set to TRUE. For example, 200.00 (precision 5, scale 2) divided by 3.00 (precision 3, scale 2) returns a quotient of precision 38 and scale 33:

[0626] 00066.666666666666666666666666666666666

[0627] A subsequent call to getPrecedingRemainder( ) on the same object returns a remainder with precision 38 and scale 35:

[0628] 000.00000000000000000000000000000000200

[0629] IDL Syntax

[0630] ICBCDecimal divideThisObjecty(in ICBCDecimal aDecimal);

[0631] ICBCDecimal::divideWithNewObject

[0632] Divides the receiving object and the argument ICBCDecimal object, and returns a new ICBCDecimal object containing the quotient. The original operand objects are unchanged.

[0633] The precision of the result object is 38.

[0634] The scale is: 38−p1+s1−s2

[0635] IDL Syntax

[0636] ICBCDecimal divideWithNewObject(in ICBCDecimal aDecimal);

[0637] Remarks

[0638] The division proceeds as far as possible within these limits and then stops. Any remainder can be retrieved using the getPrecedingRemainder( ) function (see ICBCDecimal::getPreceedingRemainder).For an example of a divide operation, see ICBCDecimal::divideThisObjectBy.

[0639] After a divideWithNewObject operation, the change flag of the new object is set to TRUE. The change flag of the original object is unchanged.

[0640] It is the application's responsibility to delete the new remainder object, freeing its memory, when no longer needed.

[0641] This function does not cause any overflow conditions, but may encounter a zeroDivide situation. If so, or if other errors occurred that prevented the creation of the new object, an ICBCDecimal pointer with value −1 is returned.

[0642] ICBCDecimal::equalTo

[0643] Returns TRUE if the value of the receiving ICBCDecimal object is equal to the other ICBCDecimal object.

[0644] IDL Syntax

[0645] boolean equalTo(in ICBCDecimal aDecimal);

[0646] ICBCDecimal::getAsDouble

[0647] Returns the value of the receiving object as a double. Since the double representation has maximum precision less than that of a decimal data type in DB2, accuracy of the object value may be lost.

[0648] IDL Syntax

[0649] double getAsDouble( );

[0650] ICBCDecimal::getAsFloat

[0651] Returns the value of the receiving object as a float. Since the float representation has maximum precision less than that of a decimal data type in DB2, accuracy of the object value may be lost.

[0652] IDL Syntax

[0653] double getAsFloat( );

[0654] ICBCDecimal::getAsFormattedString1

[0655] Returns the value of the receiving object as a formatted string. This function is equivalent to the CHAR( ) built-in function of DB2.

[0656] The application must supply a non-const pointer to a target storage area long enough to receive the formatted decimal number. The function returns a reference to this area.

[0657] IDL Syntax

[0658] string getAsFormattedString1(inout string aOutput,

[0659] in char aDecimalCharacter);

[0660] Parameters

[0661] aDecimalCharacter must be a single character to be used as the “decimal point” character in the output. The characters plus (+) and minus (−) are not permitted, and blanks are not permitted. The length of the output string is always precision +2, where precision is the current precision of the object. One of the additional character positions is always used for the decimal point. If required, the additional character position is used for a leading sign. If a sign is not required, the output string will have a trailing blank. Leading and trailing padding zeros are provided if necessary to fill the current precision and scale of the object.

[0662] aDecimalCharacter

[0663] For example, assuming an aDecimalCharacter of ‘.’:

[0664] ICBCDecimal::getAsFormattedString2

[0665] Returns the value of the receiving object as a string formatted without leading zero padding. The application must supply a non-const pointer to a target storage area long enough to receive the formatted decimal number. The function returns a reference to this area.

[0666] IDL Syntax

[0667] string getAsFormattedString2(inout string aOutput,

[0668] in char aDecimalCharacter);

[0669] Parameters

[0670] aDecimalCharacter must be a single character to be used as the “decimal point” character in the output. The characters plus (+) and minus (−) are not permitted, and blanks are not permitted. The length of the output string is always precision +2, where precision is the current precision of the object. The leftmost character position is reserved for the sign, if necessary. The following positions contain the number, with an embedded decimal point, which is always present, even if the scale of the number is zero. The digits in the number are padded with leading blanks and trailing zeros to fill the full current precision and scale of the object. Finally, if leading blanks are present, the sign moves to a position immediately adjacent to the first digit (or decimal point).

[0671] aDecimalCharacter

[0672] For example, assuming an aDecimalCharacter of ‘.’, and showing blank as the character ‘b’:

[0673] ICBCDecimal::getAsFormattedString3

[0674] Returns the value of the receiving object formatted as a left justified string with a leading sign if required, and a decimal point only if there are digits that the to the right of the decimal point There are no leading or trailing zeros or blanks.

[0675] The application must supply a non-const pointer to a target storage area long enough to receive the formatted decimal number. The function returns a reference to this area.

[0676] IDL Syntax

[0677] string getAsFormattedString3(inout string aOutput,

[0678] in char aDecimalCharacter);

[0679] Parameters

[0680] aDecimalCharacter must be a single character to be used as the “decimal point” character in the output. The characters plus (+) and minus (−) are not permitted, and blanks are not permitted. The length of the output string is variable, containing only enough characters to hold the significant digits plus a sign and a decimal point if required. The precision and scale of the object are not reflected in the length output string. This format is suitable for providing to the Oracle TO_NUMBER function without the need for an associated “NUMBER format element” parameter.

[0681] aDecimalCharacter

[0682] For example, assuming an aDecimalCharacter of ‘.’:

[0683] ICBCDecimal::getAsDigits

[0684] Returns a null terminated string of length equal to the precision of the object, containing the digits in the value of the object, left justified, and without either decimal point or sign. Leading zeros are provided if necessary. For example, an object of precision and scale of 6 and 2 respectively, containing a value of −6.28 would return a string containing ‘000628’.

[0685] IDL Syntax

[0686] string getAsDigits(inout string aOutput);

[0687] Remarks

[0688] The application must supply a non-const pointer to a target storage area long enough to receive the digits and null terminator. The function returns a reference to this area.

[0689] ICBCDecimal::getAsLong

[0690] Returns the value of the receiving object as a long. All digits in the object value that lie to the right of the decimal point will be truncated. It is a user responsibility to ensure that the value of the object does not exceed the range for a long data type.

[0691] IDL Syntax

[0692] double getAsLong( );

[0693] ICBCDecimal::getAsPackedDecimal

[0694] Returns the value of the object as a packed decimal string.

[0695] The format of the returned packed string will one of the following:

[0696] [dd]..[ds] if the number of digits is odd

[0697] [0d]..[ds] if the number of digits is even

[0698] where [ ] denotes a single byte containing two 4-bit nibbles, d is a four-bit binary digit, 0 is a 4-bit binary zero, and s is a 4-bit sign representation. A hexadecimal value “C” denotes the positive sign, and “D” the negative sign. A sign is always present in the lower order four bits of the rightmost byte.

[0699] Parameters

[0700] There is no decimal point embedded in the string. Output parameters are updated to describe the precision (aPrecision), and scale (aScale), of the packed string aScale.

[0701] IDL Syntax

[0702] string getAsPackedDecimal(inout string aOutput, inout short aPrecision,

[0703] inout short aScale);

[0704] Remarks

[0705] Because of the presence of the sign, and the packing of two digits per byte, strings with an even number of bytes will have a leading zero padding character.

[0706] It is the responsibility of the application to provide a string of sufficient length to receive the packed string, with its sign and leading zero (if present). On return, a null terminator is appended to the end of the string.

[0707] ICBCDecimal::getAsShort

[0708] Returns the value of the receiving object as a short. All digits in the object value that lie to the right of the decimal point will be truncated. It is a user responsibility to ensure that the value of the object does not exceed the range for a long data type.

[0709] IDL Syntax

[0710] double getAsShort( );

[0711] In ICBCDecimal::getPreceedingRemainder

[0712] Returns a new object containing the remainder value of an immediately preceding division operation. This function may be invoked on an object that has been the subject of a divideThisObjectBy( ) operation, or on the new object produced by a divideWithNewObject( ) operation. This function will only return a meaningful result if used immediately after a divide operation. If used following any other manipulation function it will return an object with a zero value.

[0713] The precision of the result object is 38.

[0714] The scale is: 38−p1+s1

[0715] IDL Syntax

[0716] ICBCDecimal getPreceedingRemainder( );

[0717] Remarks

[0718] If errors occur that prevent creation of the new object, a ICBCDecimal pointer with value −1 is returned.

[0719] If a division operation has already been performed, this function is a more efficient way of obtaining the remainder than issuing a remainderInThisObject( ) or remainderWithNewObject( ). This function retrieves the remainder that was cached in the object as a by-product of the preceding divide operation, whereas the latter two functions perform an implicit divide to calculate the remainder.

[0720] It is the application's responsibility to delete the new remainder object, freeing its memory, when no longer needed.

[0721] ICBCDecimal::getPrecision

[0722] Returns the precision of the object—the maximum number of digits that make up the value of the object. Precision is conceptually similar to the precision of a DB2 column. For example, an object with precision and scale of 5 and 2 respectively can store numbers up to value 999.99, but could not store numbers 1000.00, nor 999.991, nor 99.991. Precision is set by an ICBCDecimal::initialize..( ) function, and is generally retained by the object through its lifetime unless changed by arithmetic functions.

[0723] IDL Syntax

[0724] short getPrecision( );

[0725] ICBCDecimal::getScale

[0726] Returns the scale of the object. Scale, like precision (see ICBCDecimal::getPrecision), is set by the ICBCDecimal::initialize..( ) functions, and is generally retained by the object through its lifetime unless changed by arithmetic operations.

[0727] IDL Syntax

[0728] short getScale( );

[0729] ICBCDecimal::greaterThan

[0730] Returns TRUE if the value of the receiving ICBCDecimal object is greater than the other ICBCDecimal object.

[0731] IDL Syntax

[0732] boolean greaterThan(in ICBCDecimal aDecimal);

[0733] ICBCDecimal::greaterThanOrEqualTo

[0734] Returns TRUE if the value of the receiving ICBCDecimal object is greater than or equal to the other ICBCDecimal object.

[0735] IDL Syntax

[0736] boolean greaterThanOrEqualTo(in ICBCDecimal aDecimal);

[0737] ICBCDecimal::increment

[0738] Adds the argument ICBCDecimal object to the receiving ICBCDecimal object and sets the value of the receiving object to the result. The precision and scale of the receiving object are reset. The precision is given by:

[0739] min(38, max(p1−s1, p2−s2)+max(s1, s2)+1)

[0740] The scale is given by:

[0741] max(s1, s2)

[0742] If the non-zero digits to the left of the decimal point in the result exceed (p−s) of the result, the receiving object is not changed, and a following invocation of the function decimalOverflow( ) will return TRUE.

[0743] After an increment operation, the change flag of the receiving object is set to TRUE.

[0744] IDL Syntax

[0745] ICBCDecimal increment(in ICBCDecimal aDecimal);

[0746] ICBCDecimal::initializeFromDecimal1

[0747] Initializes the receiving object with the value of the argument ICBCDecimal object, and sets its precision and scale to the values of the parameters.

[0748] IDL Syntax

[0749] boolean initializeFromDecimal1(in ICBCDecimal aDecimal in short precision,

[0750] in short scale);

[0751] Remarks

[0752] This function requires parameters to be explicitly specified for the precision and scale of the receiving object precision must be a number between zero and 38. If zero, a default value of 15 is assumed scale must be a number between 0 and the value of precision. If precision is zero, the value of scale is ignored and the scale of the object is taken to be zero. The value of precision—scale must be sufficient to contain the digits to the left of the decimal point in the source ICBCDecimal object. If scale is insufficient to contain the digits to the right of the decimal point, those digits will be truncated from the right.

[0753] The difference between this function and ICBCDecimal::assignFromDecimal( ) is that this function sets the precision and scale of the receiving object, whereas ICBCDecimal::assignFromDecimal( ) leaves the existing precision and scale of the receiving object unchanged.

[0754] If the object can be successfully initialized from the other Decimal object, TRUE is returned and any existing value in the object is replaced. If the initialization cannot be performed, FALSE is returned and the state of the object is unchanged, except that, if the FALSE return resulted from a numeric overflow, a following invocation of the decimalOverflow( ) function against the object will return the value TRUE.

[0755] ICBCDecimal::initializeFromDecimal2

[0756] Initializes the receiving object with the value of the argument ICBCDecimal object, and sets its precision and scale to the values of the parameters.

[0757] IDL Syntax

[0758] boolean initializeFromDecimal2(in ICBCDecimal aDecimal);

[0759] Remarks

[0760] This function has no explicit parameters for precision and scale. The precision and scale of the receiving object are set to the same values as the source Decimal object.

[0761] The difference between this function and ICBCDecimal::assignFromDecimal( ) is that this function sets the precision and scale of the receiving object, whereas ICBCDecimal::assignFromDecimal( ) leaves the existing precision and scale of the receiving object unchanged.

[0762] If the object can be successfully initialized from the other Decimal object, TRUE is returned and any existing value in the object is replaced. If the initialization cannot be performed, FALSE is returned and the state of the object is unchanged, except that, if the FALSE return resulted from a numeric overflow, a following invocation of the decimalOverflow( ) function against the object will return the value TRUE.

[0763] ICBCDecimal::initializeFromDouble

[0764] Initializes the receiving object with the value of an argument of type double, and sets its precision and scale.

[0765] IDL Syntax

[0766] boolean initializeFromDouble(in double aDouble in short precision,

[0767] in short scale);

[0768] Parameters

[0769] Precision

[0770] Precision must be a number between zero and 38. A zero value implies that the application is not supplying values for precision or scale. In this case, a default value of 15 is assumed.

[0771] scale

[0772] Scale must be a number between 0 and the value of precision. If precision is zero, the value of scale is ignored and a value of zero is assumed.

[0773] Remarks

[0774] If the the object can be successfully initialized with the numeric operand, TRUE is returned and any existing value in the object is replaced. If the initialization cannot be performed, FALSE is returned and the state of the object is unchanged, except that, if the FALSE return resulted from a numeric overflow, a following invocation of the decimalOverflow( ) function against the object will return the value TRUE.

[0775] Precision and scale must be such that (precision−scale) is sufficient to contain the digits to the left of the decimal point in the numeric operand. If scale is insufficient to contain the digits to the right of the decimal point, those digits will be truncated from the right.

[0776] ICBCDecimal::initializeFromFloat

[0777] Initializes the receiving object with the value of an argument of type float, and sets its precision and scale.

[0778] IDL Syntax

[0779] boolean initializeFromFloat(in float afloat in short precision,

[0780] in short scale);

[0781] Parameters

[0782] Precision

[0783] Precision must be a number between zero and 38. A zero value implies that the application is not supplying values for precision or scale. In this case, a default value of 15 is assumed.

[0784] scale

[0785] Scale must be a number between 0 and the value of precision. If precision is zero, the value of scale is ignored and a value of zero is assumed.

[0786] Remarks

[0787] If the the object can be successfully initialized with the numeric operand, TRUE is returned and any existing value in the object is replaced. If the initialization cannot be performed, FALSE is returned and the state of the object is unchanged, except that, if the FALSE return resulted from a numeric overflow, a following invocation of the decimalOverflow( ) function against the object will return the value TRUE.

[0788] Precision and scale must be such that (precision−scale) is sufficient to contain the digits to the left of the decimal point in the numeric operand. If scale is insufficient to contain the digits to the right of the decimal point, those digits will be truncated from the right.

[0789] ICBCDecimal::initializeFromLong

[0790] Initializes the receiving object with the value of an argument of type long, and sets its precision and scale.

[0791] IDL Syntax

[0792] boolean initializeFromLong(in long aLong in short precision,

[0793] in short scale);

[0794] Parameters

[0795] Precision

[0796] Precision must be a number between zero and 38. A zero value implies that the application is not supplying values for precision or scale. In this case, a default value of 11 is assumed.

[0797] scale

[0798] Scale must be a number between 0 and the value of precision. If precision is zero, the value of scale is ignored and a value of zero is assumed.

[0799] Remarks

[0800] If the the object can be successfully initialized with the numeric operand, TRUE is returned and any existing value in the object is replaced. If the initialization cannot be performed, FALSE is returned and the state of the object is unchanged, except that, if the FALSE return resulted from a numeric overflow, a following invocation of the decimalOverflow( ) function against the object will return the value TRUE.

[0801] Precision and scale must be such that (precision−scale) is sufficient to contain the digits in the numeric operand.

[0802] ICBCDecimal::initializeFromPackedDecimal

[0803] Accepts a value in the form of a packed decimal string.

[0804] IDL Syntax

[0805] boolean initializeFromPackedDecimal(in string aString, in short aPrecision,

[0806] in short aScale);

[0807] Parameters

[0808] must have one of the following forms:

[0809] [dd][dd] . . . [ds] if number of digits is odd

[0810] [0d][dd] . . . [ds] if number of digits is even

[0811] Where [ ] denotes a byte containing two 4-bit “nibbles”, d is a four-bit binary digit, 0 is a 4-bit binary zero, and s is a 4-bit sign representation. The hexadecimal value “C” is interpreted as the positive sign, and “D” as the negative sign. There is no embedded decimal point. The scale of the object is defined by the scale input argument aScale. The number of digits unpacked from aString is defined by the aPrecision argument. The sign is always present in the lower order four bits of the rightmost byte. Because of the presence of the sign, and the packing of two digits per byte, strings with an even number of bytes will have a leading zero padding character.

[0812] aString

[0813] This format is consistent with that used by DB2 for packed decimal variables passed to an application program.

[0814] Precision

[0815] This must be a number between zero and 38, and must always be present. There is no default.

[0816] scale

[0817] This parameter must be a number between 0 and the value of precision. It indicates the scale number of digits that lie to the right of the decimal point. It must always be present. There is no default. A null terminator character on the packed string is not required, but is tolerated if present.

[0818] Remarks

[0819] If the string is a valid packed decimal representation and the object is successfully initialized, TRUE is returned and any existing value in the object is replaced. Returns FALSE if the parameter is invalid. If FALSE is returned the state of the object is unchanged, except that, if the FALSE return resulted from a numeric overflow, a following invocation of the decimalOverflow( ) function against the object will return the value TRUE.

[0820] ICBCDecimal::initializeFromShort

[0821] Initializes the receiving object with the value of an argument of type short, and sets its precision and scale.

[0822] IDL Syntax

[0823] boolean initializeFromShort(in short aShort in short precision,

[0824] in short scale);

[0825] Parameters

[0826] precision

[0827] Precision must be a number between zero and 38. A zero value implies that the application is not supplying values for precision or scale. In this case, a default value of 5 is assumed.

[0828] scale

[0829] Scale must be a number between 0 and the value of precision. If precision is zero, the value of scale is ignored and a value of zero is assumed.

[0830] Remarks

[0831] If the the object can be successfully initialized with the numeric operand, TRUE is returned and any existing value in the object is replaced. If the initialization cannot be performed, FALSE is returned and the state of the object is unchanged, except that, if the FALSE return resulted from a numeric overflow, a following invocation of the decimalOverflow( ) function against the object will return the value TRUE.

[0832] Precision and scale must be such that (precision−scale) is sufficient to contain the digits in the numeric operand.

[0833] ICBCDecimal::initializeFromString1

[0834] Accepts a value for this decimal object in the form of a string, specified values for precision and scale of the object, and the character that is used in the string as the decimal point (if any).

[0835] IDL Syntax

[0836] boolean initializeFromString1(in string aString, in short precision, in

[0837] short scale, in char decimalChar);

[0838] Parameters

[0839] aString

[0840] The parameter aString must be of the form:

[0841] [spaces][sign][zeros][digits][decimal point][digits][zeros]&lbrk.spaces]

[0842] decimalChar

[0843] A negative sign is ignored if the value represented by the string is zero. decimalChar must be a single character that is used in aString to represent the decimal point. The characters plus (+) and minus (−) are not permitted, and blanks are not permitted.

[0844] precision

[0845] Precision must be a number between zero and 38. If the value is zero, a default precision of 15 and a default scale of zero are used (the parameter for scale is ignored in this case). Otherwise the parameter values for precision and scale are used.

[0846] scale

[0847] Scale must be a number between 0 and the value of precision. It indicates the number of digits that lie to the right of the decimal point. Note that if the parameter precision is zero, the value of scale is ignored and a default scale of zero is used.

[0848] Remarks

[0849] If the parameters are valid, TRUE is returned and any existing value in the object is replaced. If the parameter is invalid, FALSE is returned and the state of the object is unchanged, except that, if the FALSE return resulted from a numeric overflow, a following invocation of the decimalOverflow( ) function against the object will return the value TRUE.

[0850] Precision and scale must be such that (precision−scale) is sufficient to contain the non-zero characters to the left of the decimal point in aString. If scale is insufficient to contain the characters to the right of the decimal point, those characters will be truncated from the right.

[0851] ICBCDecimal::initializeFromString2

[0852] Accepts a value for this decimal object in the form of a string, and the character used in the string as a decimal point.

[0853] IDL Syntax

[0854] boolean initializeFromString2(in string aString, in char aDecimalChar);

[0855] Remarks

[0856] The precision and scale of the object are set to the actual precision and scale of the string parameter. The precision is the total number of digits, including leading and trailing zeros. The scale is the number of digits to the right of the decimal point, including trailing zeros. In other respects, this function behaves the same as ICBCDecimal::initializeFromString1( ).

[0857] If the input parameters are valid, TRUE is returned and any existing value in the object is replaced. If the parameter is invalid, FALSE is returned and the state of the object is unchanged, except that, if the FALSE return resulted from a numeric overflow, a following invocation of the decimalOverflow( ) function against the object will return the value TRUE.

[0858] ICBCDecimal::isChanged

[0859] Returns a boolean indicating whether the the value of the receiving object has been changed since its initialization. All initialization functions set a changed flag in the object to FALSE. All arithmetic and assignment functions set the flag TRUE. Query functions do not affect the changed flag.

[0860] IDL Syntax

[0861] boolean isChanged( );

[0862] ICBCDecimal::isNegative

[0863] Returns a boolean indicating whether the the value of the receiving object is less than zero.

[0864] IDL Syntax

[0865] boolean isNegative ( );

[0866] ICBCDecimal::lessThan

[0867] Returns TRUE if the value of the receiving ICBCDecimal object is less than the other ICBCDecimal object.

[0868] IDL Syntax

[0869] boolean lessThan(in ICBCDecimal aDecimal);

[0870] ICBCDecimal::lessThanOrEqualTo

[0871] Returns TRUE if the value of the receiving ICBCDecimal object is less than or equal to the other ICBCDecimal object.

[0872] IDL Syntax

[0873] boolean lessThanOrEqualTo(in ICBCDecimal aDecimal); ICBCDecimal::multiplyWithNewObject

[0874] Multiplies the receiving object by the argument ICBCDecimal object and returns a new ICBCDecimal object containing the result. The original operand objects are unchanged. The precision of the result object is:

[0875] min(38, p1+p2)

[0876] The scale is: min(38, s1+s2)

[0877] IDL Syntax

[0878] ICBCDecimal multiplyWithNewObject(in ICBCDecimal aDecimal);

[0879] Remarks

[0880] After a multiplyWithNewObject operation, the change flag of the new object is set to TRUE. The change flag of the original object is unchanged.

[0881] It is the application's responsibility to delete the new object, freeing its memory, when no longer needed.

[0882] If the non-zero digits to the left of the decimal point in the result object would exceed (p−s) of the result, or if other errors occur that prevent the creation of the new object, an ICBCDecimal pointer with value −1 is returned.

[0883] ICBCDecimal::notEqualTo

[0884] The opposite of the operator==member.

[0885] IDL Syntax

[0886] boolean notEqualTo(in ICBCDecimal aDecimal);

[0887] ICBCDecimal::multiplyThisObjectBy

[0888] Multiplies the receiving object by the argument ICBCDecimal object, and sets the receiving object to the result. The precision and scale of the receiving object are reset. The precision is given by:

[0889] min(38, p1+p2)

[0890] The scale is given by:

[0891] min(38, s1+s2)

[0892] If the non-zero digits to the left of the decimal point in the results exceed (p−s) of the result, the object is not changed, and a following invocation of the function decimalOverflow( ) will return TRUE.

[0893] The change flag of the receiving object is set to TRUE.

[0894] IDL Syntax

[0895] ICBCDecimal multiplyThisObjectBy(in ICBCDecimal aDecimal);

[0896] ICBCDecimal::remainderInThisObject

[0897] Divides the receiving object by the argument ICBCDecimal object, and sets the receiving object to the remainder of the division operation. The precision and scale of the receiving object are reset.

[0898] The change flag of the receiving object is set to TRUE.

[0899] The precision is: 38.

[0900] The scale is: 38−p1+s1

[0901] IDL Syntax

[0902] ICBCDecimal remainderInThisObject(in ICBCDecimal aDecimal);

[0903] ICBCDecimal::remainderWithNewObject

[0904] Divides the receiving object by the argument ICBCDecimal object and returns a new ICBCDecimal object containing the remainder. The original operand objects are unchanged.

[0905] The precision of the result object is 38.

[0906] The scale is: 38−p1+s1

[0907] IDL Syntax

[0908] ICBCDecimal remainderWithNewObject(in ICBCDecimal aDecimal);

[0909] Remarks

[0910] This function does not cause any overflow conditions, but may encounter a zeroDivide situation. If so, or if errors occur that prevent the recreation of the new object, a ICBCDecimal pointer with value −1 is returned.

[0911] After a remainderWithNewObject operation, the change flag of the new object is set to TRUE. The change flag of the original object is unchanged.

[0912] It is the application's responsibility to delete the new object, freeing its memory, when no longer needed.

[0913] ICBCDecimal::subtractWithNewObject

[0914] Subtracts the argument ICBCDecimal object from the receiving object and returns a new ICBCDecimal object containing the result. The original operand objects are unchanged. The precision of the result object is:

[0915] min(38, max(p1−s1, p2−s2)+max(s1, s2)+1)

[0916] The scale is: max(s1, s2)

[0917] IDL Syntax

[0918] ICBCDecimal subtractWithNewObject(in ICBCDecimal aDecimal);

[0919] Remarks

[0920] After a subtractWithNewObject operation, the change flag of the new object is set to TRUE. The change flag of the original object is unchanged.

[0921] It is the applications responsibility to delete the new object, freeing its memory, when no longer needed.

[0922] If the non-zero digits to the left of the decimal point in the result object would exceed (p−s) of the result, or if other errors occur that prevent the creation of the new object, an ICBCDecimal pointer with value −1 is returned.

[0923] ICBCDecimal::swapSign

[0924] This function is effectively a unary minus operator which reverses the sign of this ICBCDecimal object.

[0925] IDL Syntax

[0926] void swapSign( );

[0927] ICBCDuration Class

[0928] The class ICBCDuration represents the “Labeled Duration”, “Date Duration”, “Time Duration”, and “Timestamp Duration” constructs of DB2. Duration is a complementary data type to Date, Tune, and Timestamp, and participates in SQL expressions. However, it is not, itself, stored in DB2 tables.

[0929] The class holds the value of a duration, and a record of whether this duration value is in units of years, months, days, hours, minutes seconds, or microseconds. The value can also be of a composite type defining a “Date Duration” of the form yyyymmdd, a “Time Duration” of the form hhmmss, or a “Timestamp Duration” of the form yyyymmddhhmmsszzzzzz.

[0930] Arithmetic between two ICBCDuration classes is not supported (This is consistent with DB2 support of Durations). However, they can be compared, and a unary minus operator (which swaps the sign) is provided.

[0931] IDL Interface Description

[0932] interface ICBCDuration :IManagedLocal::ILocalOnly

[0933] {

[0934] enum durationType {YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS, MICROSECONDS, DATE, TIME, TIMESTAMP};

[0935] // Object initialization

[0936] // 1. Initializer for YEAR, MONTH, DAY, HOUR, MINUTE, SECOND

[0937] // and MICROSECOND durations

[0938] boolean initializeLabeledDuration(in long aDuration,

[0939] in ICBCDuration::durationType aType);

[0940] //Initializer for DATE and TIME durations boolean initializeDateTimeDuration(in long aValue1, in long aValue2,

[0941] in long aValue3,

[0942] in boolean aNegativeFlag,

[0943] in ICBCDuration::durationType aType);

[0944] //Initialize for TIMESTAMP durations

[0945] boolean initializeTimestampDuration(in long aValue1, in long aValue2,

[0946] in long aValue3, in long aValue4,

[0947] in long aValue5, in long aValue6,

[0948] in long aValue7,

[0949] in boolean aNegativeFlag);

[0950] /*Comparisons*/

[0951] boolean equalTo(in ICBCDuration aDuration);

[0952] boolean notEqualTo(in ICBCDuration aDuration);

[0953] boolean lessThan(in ICBCDuration aDuration);

[0954] boolean lessThanOrEqualTo(in ICBCDuration aDuration);

[0955] boolean greaterThan(in ICBCDuration aDuration);

[0956] boolean greaterThanOrEqualTo(in ICBCDuration aDuration);

[0957] /*Query functions*/

[0958] ICBCDuration::durationType getType( );

[0959] boolean isNegative( );

[0960] long microsecond( );

[0961] long second( );

[0962] long minute( );

[0963] long hour( );

[0964] long day( );

[0965] long month( );

[0966] long year( );

[0967] long size(in long aIntervalType);

[0968] string formattedString(inout string aString);

[0969] /*Manipulation functions*/

[0970] void assignFromDuration(in ICBCDuration aDuration);

[0971] void swapsign( ); // unary minus

[0972] };

[0973] Supported Methods

[0974] ICBCDuration::_create

[0975] ICBCDuration::initalizeLabeledDuration

[0976] ICBCDuration::initializeDateTimeDuration

[0977] ICBCDuration::initializeTimestampDuration

[0978] ICBCDuration::equalTo

[0979] ICBCDuration::notEqualTo

[0980] ICBCDuration::lessThan

[0981] ICBCDuration::lessThanOrEqualTo

[0982] ICBCDuration::greaterThan

[0983] ICBCDuration::greaterThanOrEqualTo

[0984] ICBCDuration::formattedString

[0985] ICBCDuration::getType

[0986] ICBCDuration::isNegative

[0987] ICBCDuration::microSecond

[0988] ICBCDuration::second

[0989] ICBCDuration::minute

[0990] ICBCDuration::hour

[0991] ICBCDuration::day

[0992] ICBCDuration::month

[0993] ICBCDuration::year

[0994] ICBCDuration::assignFromDuration

[0995] ICBCDuration::size

[0996] swapSign

[0997] ICBCDuration::assignFromDuration

[0998] Sets all state data of this ICBCDuration object equal to the the other ICBCDuration object.

[0999] IDL Syntax

[1000] void assignFromDuration(in ICBCDuration aDuration);

[1001] ICBCDuration::_create

[1002] Returns a pointer to a new ICBCDuration object. The object is initialized to a type of “YEARS” and a value of zero.

[1003] ICBCDuration::day

[1004] !Returns the day part of the ICBCDuration.

[1005] IDL Syntax

[1006] long day( );

[1007] ICBCDuration::equalTo

[1008] Returns TRUE if all state data of this ICBCDuration object is equal to the other ICBCDuration object.

[1009] IDL Syntax

[1010] boolean equalTo(in ICBCDuration aDuration);

[1011] ICBCDuration::formattedString

[1012] Returns the value of a DATE type duration as a string of the form yyyymmdd, a TIME type duration in the form hhmmss, or a TIMESTAMP duration in the form yyyymmddhhmmssmmmmmm. For other duration types this function returns a null string.

[1013] IDL Syntax

[1014] string formattedString(inout string aString);

[1015] The application must supply a non-const pointer to a target storage area long enough to receive the formatted date. The function returns a reference to this area, enabling the function to be nested in stream operations.

[1016] ICBCDuration::greaterThan

[1017] Returns TRUE if the value of this ICBCDuration object is greater than the other ICBCDuration object.

[1018] IDL Syntax

[1019] boolean greaterThan(in ICBCDuration aDuration);

[1020] ICBCDuration::greaterThanOrEqualTo

[1021] Returns TRUE if the value of this ICBCDuration object is greater than or equal to the other ICBCDuration object.

[1022] IDL Syntax

[1023] boolean greaterThanOrEqualTo(in ICBCDuration aDuration);

[1024] ICBCDuration::getType

[1025] Returns the type of this ICBCDuration. Returned values can be DATE, TIME, YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS, MICROSECONDS.

[1026] IDL Syntax

[1027] ICBCDuration::durationType getType( );

[1028] ICBCDuration::hour

[1029] Returns the hour part of the ICBCDuration.

[1030] IDL Syntax

[1031] long hour( );

[1032] ICBCDuration::initializeDateTimeDuration

[1033] Accepts three numeric values, an indicator of the sign of the duration (positive or negative) and an indicator of the duration type.

[1034] IDL Syntax

[1035] I: boolean initializeDateTimeDuration(in long aValue1,

[1036] in long aValue2,

[1037] in long aValue3,

[1038] in boolean aNegativeFlag,

[1039] in ICBCDuration::durationType aType);

[1040] If the type indicator is DATE, then aValue1, aValue2, aValue3 must supply valid values for years, months, and days, respectively. Each value must be a positive number, or zero. If the supplied parameters are valid, returns TRUE, else returns FALSE.

[1041] If type indicator is TIME, then aValue1, aValue2, aValue3 must supply valid values for hours, minutes, and seconds, respectively.

[1042] Each value must be a positive number, or zero. If the supplied parameters are valid, returns TRUE, else returns FALSE.

[1043] ICBCDuration::initializeLabeledDuration

[1044] Accepts a single numeric value, and an indicator of the type of duration.

[1045] IDL Syntax

[1046] boolean initializeLabeledDuration(in long aDuration,

[1047] in ICBCDuration::durationType aType);

[1048] The type indicator can be: YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS, MICROSECONDS. The supplied values must be a positive number or zero. If the numeric value is valid, returns TRUE, otherwise returns FALSE. If the values are valid, any existing value in the object is replaced.

[1049] ICBCDuration::initializeTimestampDuration

[1050] Accepts seven numeric values, and an indicator of the sign of the duration (positive or negative).

[1051] IDL Syntax

[1052] boolean initializeTimestampDuration(in long aValue1,

[1053] in long aValue2,

[1054] in long aValue3,

[1055] in long aValue4,

[1056] in long aValue5,

[1057] in long aValue6,

[1058] in long aValue7,

[1059] in boolean aNegativeFlag);

[1060] The numeric values represent the years, months, days, hours, minutes, seconds, and microseconds portions of the timestamp duration. They must be positive numbers or zeros. If the supplied parameters are valid, returns TRUE, else returns FALSE.

[1061] ICBCDuration::isNegative

[1062] Returns a Boolean TRUE is this object's value is negative. Otherwise returns FALSE;

[1063] IDL Syntax

[1064] boolean isNegative( );

[1065] ICBCDuration::lessThan

[1066] Returns TRUE if the value of this ICBCDuration object is less than the other ICBCDuration object.

[1067] IDL Syntax

[1068] boolean lessThan(in ICBCDuration aDuration);

[1069] ICBCDuration::lessThanOrEqualTo

[1070] Returns TRUE if the value of this ICBCDuration object is less than or equal to the other ICBCDuration object

[1071] IDL Syntax

[1072] boolean lessThanOrEqualTo(in ICBCDuration aDuration);

[1073] ICBCDuration::microSecond

[1074] Returns the microseconds part of the ICBCDuration.

[1075] IDL Syntax

[1076] long microSecond( );

[1077] ICBCDuration::minute

[1078] Returns the minute part of the ICBCDuration.

[1079] IDL Syntax

[1080] long minute( );

[1081] ICBCDuration::month

[1082] Returns the month part of the ICBCDuration.

[1083] IDL Syntax

[1084] long month( );

[1085] ICBCDuration::notEqualTo

[1086] The opposite of the equalTo operation.

[1087] IDL Syntax

[1088] boolean notEqualTo(in ICBCDuration aDuration);

[1089] ICBCDuration::second

[1090] Returns the seconds part of the ICBCDuration.

[1091] IDL Syntax

[1092] long seconds( );

[1093] ICBCDuration::size

[1094] Equivalent to the DB2 TIMESTAMPDIFF built-in function.

[1095] IDL Syntax

[1096] long size(in long aIntervalType);

[1097] Remarks

[1098] Returns the value of the timestamp duration converted to the interval type specified in the input parameter. If the parameter is not valid, a value of −1 is returned. Valid parameter values, and associated interval types are:

[1099] 1 Fractions of a second.

[1100] 2 Seconds.

[1101] 4 Minutes.

[1102] 8 Hours.

[1103] 16 Days.

[1104] 32 Weeks.

[1105] 64 Months.

[1106] 128 Quarters.

[1107] 256 Years.

[1108] The conversion is not precise. A standard length year and month are assumed, taking no account of leap years. Conversion factors used are as follows:

[1109] 365 days per year.

[1110] 30 days per month.

[1111] 24 hours per day.

[1112] 60 minutes per hour.

[1113] 60 seconds per minute.

[1114] ICBCDuration::year

[1115] Returns the year part of the ICBCDuration.

[1116] IDL Syntax

[1117] long year( ); swapSign

[1118] This function is effectively a unary minus operator which reverses the sign of this ICBCDuration object.

[1119] IDL Syntax

[1120] void swapSign( );

[1121] ICBCTime Class

[1122] The class stores the value of a time-of-day. All access and manipulation of this time is through a public functional interface. The actual time value and its format are stored in private attributes.

[1123] IDL Interface Description

[1124] interface ICBCTime :IManagedLocal::ILocalOnly

[1125] {

[1126] /*Object initialization (DB2 semantics)*/

[1127] boolean initializeFromString(in string aTime);

[1128] boolean initializeFromTimestamp(in ICBCTimestamp aTimestamp);

[1129] boolean initializeFromValues(in long aHour,

[1130] in long aMinute,

[1131] in long aSecond);

[1132] // Comparisons

[1133] boolean equalTo(in ICBCTime aTime);

[1134] boolean notEqualTo(in ICBCTime aTime);

[1135] boolean lessThan(in ICBCTime aTime);

[1136] boolean lessThanOrEqualTo(in ICBCTime aTime);

[1137] boolean greaterThan(in ICBCTime aTime);

[1138] boolean greaterThanOrEqualTo(in ICBCTime aTime);

[1139] // Query functions (DB2 semantics)

[1140] enum OutputFormat {ISO, USA, EUR, JIS, LOC};

[1141] string formattedString(inout string aOutput,

[1142] in ICBCTime::OutputFormat aFormat);

[1143] long second( );

[1144] long minute( );

[1145] long hour( );

[1146] boolean isObjectChanged( );

[1147] // Manipulation functions (DB2 semantics)

[1148] void assignFromTime(in ICBCTime aTime);

[1149] void increment(in ICBCDuration aDuration);

[1150] void decrement(in ICBCDuration aDuration);

[1151] long timeOverflow( );

[1152] ICBCDuration intervalFromTime(in ICBCTime aTime);

[1153] ICBCDuration intervalFromString(in string aTime);

[1154] }

[1155] Supported Methods

[1156] ICBCTime::_create

[1157] ICBCTime::initializeFromString

[1158] ICBCTime::initializeFromTimestamp

[1159] ICBCTime::initializeFromValues

[1160] ICBCTime::equalTo

[1161] ICBCTime::notEqualTo

[1162] ICBCTime::lessThan

[1163] ICBCTime::lessThanOrEqualTo

[1164] ICBCTime::greaterThan

[1165] ICBCTime::greaterThanOrEqualTo

[1166] ICBCTime::formattedString

[1167] ICBCTime::second

[1168] ICBCTime::minute

[1169] ICBCTime::hour

[1170] ICBCTime::isObjectChanged

[1171] ICBCTime::assignFromTime

[1172] ICBCTime::increment

[1173] ICBCTime::decrement

[1174] ICBCTime::timeOverflow

[1175] ICBCTime::interval

[1176] ICBCTime::assignFromTime

[1177] Sets all state data in this ICBCTime object equal to the second ICBCTime object. The change flag of this object is set to TRUE.

[1178] IDL Syntax

[1179] void assignFromTime(in ICBCTime aTime);

[1180] ICBCTime::_create

[1181] Returns a pointer to a new ICBCTime object. The object is initialized to the current local time.

[1182] ICBCTime::decrement

[1183] Subtracts a ICBCDuration from the value of this ICBCTime object.

[1184] IDL Syntax

[1185] void decrement(in ICBCDuration aDuration);

[1186] Remarks

[1187] This operation is performed essentially as the inverse of the increment operation.

[1188] When a duration of type TIME is subtracted from a time, the time is decremented by the specified number of hours, minutes, and seconds, in that order.

[1189] If the hours value of the result of a decrement operation is negative, then enough whole periods of 24 hours are added to the value to make it positive. The number of 24 hour periods (i.e., days) thus added can be retrieved as a negative number using the timeOverflow( ) function.

[1190] Although a ICBCTime object with a value (expressed in ISO format) of 24.00.00 can be input to an increment or decrement operation, a time of 24.00.00 will never be returned as the result of the operation. Thus 24.00.00 plus or minus a zero duration will return the time 00.00.00.

[1191] The change flag of this object is set to TRUE.

[1192] ICBCTime::equalTo

[1193] Returns TRUE if the time in this ICBCTime object is equal to the other ICBCTime object. Note: Although 24.00.00 and 00.00.00 both represent midnight, ICBCTime considers that 24.00.00>00.00.00.

[1194] IDL Syntax

[1195] boolean equalTo(in ICBCTime aTime);

[1196] ICBCTime::formattedString

[1197] Returns the time value of this object as a string in a specified format. The parameter OutputType must take one the values: ISO, USA, EUR, JIS. Formats are as described for the function ICBCTime::initializeFromString( ). The LOC site-defined option described in the DB2 manual is not supported by ICBCTime.

[1198] IDL Syntax

[1199] string formattedString(inout string aOutput,

[1200] in ICBCTime::OutputFormat aFormat);

[1201] The application must supply a non-const pointer to a target storage area long enough to receive the formatted time. The function returns a reference to this area.

[1202] ICBCTime::greaterThan

[1203] Returns TRUE if the time stored in this ICBCTime object is greater than the other ICBCTime object.

[1204] IDL Syntax

[1205] boolean greaterThan(in ICBCTime aTime);

[1206] ICBCTime::greaterThanOrEqualTo

[1207] Returns TRUE if the time stored in this ICBCTime object is greater than or equal to the other ICBCTime object.

[1208] IDL Syntax

[1209] boolean greaterThanOrEqualTo(in ICBCTime aTime);

[1210] ICBCTime::hour

[1211] Returns the hour part of the time.

[1212] IDL Syntax

[1213] long hour( );

[1214] ICBCTime::increment

[1215] Adds a ICBCDuration to the value of this ICBCTime object.

[1216] IDL Syntax

[1217] void increment(in ICBCDuration aDuration);

[1218] Remarks

[1219] If a duration of type HOURS is added to a time, only the hours portion of the time is affected. The minutes and seconds are unchanged.

[1220] Similarly, if a duration of type MINUTES is added to the time, only minutes and, if necessary, hours are affected.

[1221] Adding a duration of type SECONDS will, of course, affect the seconds portion of the time, and potentially the minutes and hours.

[1222] When a duration of type TIME is added to a time, the time is incremented by the specified number of hours, minutes, and seconds, in that order.

[1223] If the hours value of the result of an increment operation is greater than 24 hours, then the hours value is divided by 24 and the remainder stored in the hours value. The quotient of the division (the number of whole 24 hour periods or days in the original hours value) can be retrieved using the timeOverflow( ) function.

[1224] Although a ICBCTime object with a value (expressed in ISO format) of 24.00.00 can be input to an increment or decrement operation, a time of 24.00.00 will never be returned as the result of the operation. Thus 24.00.00 plus or minus a zero duration will return the time 00.00.00. The change flag of this object is set to TRUE.

[1225] ICBCTime::initializeFromString

[1226] Accepts a value for the time in the form of a string. Any existing value in the object is replaced. Returns TRUE if the string is a valid time representation and the object is successfully initialized. Returns FALSE if the parameter is invalid. If FALSE is returned the state of the object is unchanged.

[1227] IDL Syntax

[1228] boolean initializeFromString(in string aTime);

[1229] Parameters

[1230] The string must be either:

[1231] A valid string representation of a time, in one of the following valid forms.

[1232] International Standards Organization (ISO) (hh.mm.ss).

[1233] IBM USA standard (USA) (hh:mm AM or PM).

[1234] IBM European standard (EUR) (hh.mm.ss).

[1235] Japanese Industrial Standard Christian Era (JIS) (hh:mm.ss).

[1236] aTime

[1237] Leading and trailing blanks are acceptable provided the string length is less than 20 characters. Leading zeros can be omitted from the hours portion, and in ISO, EUR and JIS the seconds portion can be omitted completely. In the USA format, the minutes can be omitted. Zeros are assumed for omitted portions. In the USA time format, the hour cannot be greater than 12 and cannot be 0 except for the special case of 00:00 AM. Only SBCS characters may be present in the string.

[1238] A string representation of a timestamp.

[1239] Any of the string forms acceptable by the ICBCTimestamp::initializeFromString( ) function are acceptable. For details refer to that function. Briefly, the forms include:

[1240] A punctuated string: yyyy-mm-dd-hh.mm.ss.nnnnnn.

[1241] A 14 byte string without punctuation, of the form: yyyymmddhhmmss.

[1242] ICBCTime::initializeFromTimestamp

[1243] Initialize this object from the time portion of a Timestamp object.

[1244] IDL Syntax

[1245] boolean initializeFromTimestamp(in ICBCTimestamp aTimestamp);

[1246] ICBCTime::initializeFromValues

[1247] Accepts the time in the form of three separate value parameters for hour, minute, and second.

[1248] The values must make a valid time.

[1249] Returns TRUE if the values are a valid time representation, FALSE otherwise. If FALSE is returned, the state of the object is unchanged.

[1250] IDL Syntax

[1251] boolean initializeFromValues(in long aHour, in long aMinute,

[1252] in long aSecond);

[1253] ICBCTime::interval

[1254] Calculates the Duration between two ICBCTime objects. The result is a pointer to a new ICBCDuration object of type TIME.

[1255] If the interval between TIME1 and TIME2 is required, and TIME1 is greater than or equal to TIME2, the operation is performed by subtracting TIME2 from TIME1. If, however, TIME1 is less than TIME2, TIME1 is subtracted from TIME2, and the sign of the result is made negative. The following procedural description clarifies the steps involved in the operation result=TIME1−TIME2.

[1256] If SECOND(TIME2)<=SECOND(TIME1)

[1257] then SECOND(RESULT=SECOND(TIME1)−SECOND(TIME2).

[1258] If SECOND(TIME2)>SECOND(TIME1)

[1259] then SECOND(RESULT=60+SECOND(TIME1)−SECOND(TIME2).

[1260] MINUTE(TIME2) is then incremented by 1.

[1261] If MINUTE(TIME2)<MINUTE(TIME1)

[1262] then MINUTE(RESULT)=MINUTE(TIME1)−MINUTE(TIME2).

[1263] If MINUTE(TIME2)>MINUTE(TIME1)

[1264] then MINUTE(RESULT)=60+MINUTE(TIME1)−MINUTE(TIME2).

[1265] HOUR(TIME2) is then incremented by 1.

[1266] HOUR(RESULT)=HOUR(TIME1)−HOUR(TIME2).

[1267] IDL Syntax

[1268] ICBCDuration_ptr intervalFromTime(in ICBCTime aTime);

[1269] ICBCDuration_ptr intervalFromString(in string aTime);

[1270] In the case with a string parameter, the parameter must be a valid string representation of a time. For details see ICBCTime::initializeFromString.

[1271] If parameters to this function cannot be recognized as a valid time, then a pointer value of −1 is returned.

[1272] ICBCTime::isObjectChanged

[1273] Returns a boolean indicating whether the value of this object has been changed since it was initialized.

[1274] IDL Syntax

[1275] boolean isObjectChanged( );

[1276] ICBCTime::lessThan

[1277] Returns TRUE if the time stored in this ICBCTime object is less than the other ICBCTime object.

[1278] IDL Syntax

[1279] boolean lessThan(in ICBCTime aTime);

[1280] ICBCTime::lessThanOrEqualTo

[1281] Returns TRUE if the time stored in this ICBCTime object is less than or equal to the other ICBCTime object.

[1282] IDL Syntax

[1283] boolean lessThanOrEqualTo(in ICBCTime aTime);

[1284] ICBCTime::minute

[1285] Returns the minute part of the time.

[1286] IDL Syntax

[1287] long minutes;

[1288] ICBCTime::notEqualTo

[1289] The opposite of the operator==member.

[1290] IDL Syntax

[1291] boolean notEqualTo(in ICBCTime aTime);

[1292] ICBCTime::second

[1293] Returns the second part of the time.

[1294] IDL Syntax

[1295] long second( );

[1296] ICBCTime::timeOverflow

[1297] Returns the number of overflow or underflow days of a preceding increment or decrement operation. For an increment, returns the number of whole 24 hour periods (days) in the hours value of the result. For a decrement, returns the number of 24 hour periods necessary to restore the hours value of the result to a positive value.

[1298] IDL Syntax

[1299] long timeOverflow( );

[1300] ICBCTimestamp Class

[1301] The class stores the value of a DB2 Timestamp or an Oracle DATE type. All access and manipulation of this timestamp is through a public functional interface. The actual timestamp value is stored in a private attributes.

[1302] A Timestamp attribute in a Component Broker business object that originates from a DB2 database is represented by Component Broker as a 26 character string of form yyyy-mm-dd-hh.mm.ss.mmmmmmm This string can be used to initialize an ICBCTimestamp instance through the ICBCTimestamp::initializeFromString function. A DATE attribute that originates from an Oracle database is represented by Component Broker in the same 26 character form yyyy-mm-dd-hh.mm.ss.mmmmmm, but with the final six characters (the microseconds field) always set to zeros. This string can be used to initialize an ICBCTimestamp via ICBCTimestamp::initializedFromString. However, Oracle dates earlier than 0001-01-01 are rejected. Whether the ICBCTimestamp object is initialized from data originating in DB2 or in Oracle, ICBCTimestamp applies DB2 semantics in its processing of the data.

[1303] IDL Interface Description

[1304] interface ICBCTimestamp :IManagedLocal::ILocalOnly

[1305] {

[1306] // Object initialization

[1307] boolean initializeFromString(in string aTimestamp);

[1308] boolean initializeFromDateTime(in ICBCDate aDate,

[1309] in ICBCTime aTime,

[1310] in long aMicroseconds);

[1311] void initializeFromDate(in ICBCDate aDate); // Equivalent to TIMESTAMP_ISO

[1312] void initializeFromTirne(in ICBCTime aTime); // Equivalent to TIMESTAMP_ISO

[1313] enum DatastoreType {ORCL};

[1314] boolean initializeFromDatastoreFormat(in string aTimestamp,

[1315] in ICBCTimestamp:DatastoreType aDatastore);

[1316] // Comparisons

[1317] boolean equalTo(in ICBCTimestamp aTimestamp);

[1318] boolean notEqualTo(in ICBCTimestamp aTimestamp);

[1319] boolean lessThan(in ICBCTimestamp aTimestamp);

[1320] boolean lessThanOrEqualTo(in ICBCTimestamp aTimestamp);

[1321] boolean greaterThan(in ICBCTimestamp aTimestamp);

[1322] boolean greaterThanOrEqualTo(in ICBCTimestamp aTimestamp);

[1323] // Query functions

[1324] enum OutputFormat {ISO, USA, EUR, JIS, LOC};

[1325] // gets whole timestamp as a string:

[1326] string formattedString(inout string aOutput);

[1327] string getAsDateFormattedString(inout string aTarget,

[1328] in ICBCTimestamp::OutputFormat aFormat);

[1329] string getAsTimeFormattedString(inout string aTarget,

[1330] in ICBCTimestamp::OutputFormat aFormat);

[1331] string getAsDatastoreFormat(inout string aTarget,

[1332] in ICBCTimestamp::DatastoreType aDatastore);

[1333] long microsecond( );

[1334] long second( );

[1335] long minute( );

[1336] long hour( );

[1337] long day( );

[1338] long month( );

[1339] long year( );

[1340] long dayOfWeek( );

[1341] long dayOfYear( );

[1342] long julianDay( );

[1343] long modifiedJulianDay( );

[1344] string dayName( );

[1345] long dayFromString(in string aTimestamp);

[1346] long dayOfWeekFromString(in string aTimestamp);

[1347] long dayOYearFromString(in string aTimestamp);

[1348] long julianDayFromString(in string aTimestamp);

[1349] long modifiedJulianDayFromString(in string aTimestamp);

[1350] string dayNameFromString(in string aTimestamp);

[1351] string dayNameFromNumber(in long aDayIndex);

[1352] string monthName( );

[1353] long monthFromString(in string aTimestamp);

[1354] string monthNameFromString(in string aTimestamp);

[1355] string monthNameFromNumber(in long aMonthIndex);

[1356] long quarters;

[1357] long quarterFromString(in string aTimestamp);

[1358] long yearFromString(in string aTimestamp);

[1359] boolean isLeapYear(in long aYear);

[1360] long daysInObject( );

[1361] long daysInString(in string aTimestamp);

[1362] long daysInMonth(in long aYear, in long aMonth);

[1363] long daysInYear(in long aYear);

[1364] boolean isObjectChanged( );

[1365] // Manipulation functions

[1366] void assignFromTimestamp(in ICBCTimestamp aTimestamp);

[1367] void increment(in ICBCDuration aDuration);

[1368] void decrement(in ICBCDuration aDuration);

[1369] long timestampOverflow( );

[1370] ICBCDuration intervalFromTimestamp(in ICBCTimestamp aTimestamp);

[1371] ICBCDuration intervalFromString(in string aTimestamp);

[1372] };

[1373] Supported Methods

[1374] ICBCTimestamp::_create

[1375] ICBCTimestamp::initializeFromString

[1376] ICBCTimestamp::initializeFromDateTime

[1377] ICBCTimestamp::initalizeFromDate

[1378] ICBCTimestamp::initializeFromTime

[1379] ICBCTimestamp::equalTo

[1380] ICBCTimestamp::notEqualTo

[1381] ICBCTimestamp::lessThan

[1382] ICBCTimestamp::lessThanOrEqualTo

[1383] ICBCTimestamp::greaterThan

[1384] ICBCTimestamp::greaterThanOrEqualTo

[1385] ICBCTimestamp::formattedString

[1386] ICBCTimestamp::microsecond

[1387] ICBCTimestamp::second

[1388] ICBCTimestamp::minute

[1389] ICBCTimestamp::hour

[1390] ICBCTimestamp::day

[1391] ICBCTimestamp::month

[1392] ICBCTimestamp::year

[1393] ICBCTimestamp::dayOfWeek

[1394] ICBCTimestamp::dayOfYear

[1395] ICBCTimestamp::julianDay

[1396] ICBCTimestamp::modifiedJulianDay

[1397] ICBCTimestamp::dayName

[1398] ICBCTimestamp::dayFromString

[1399] ICBCTimestamp::dayOfWeekFromString

[1400] ICBCTimestamp::dayOfYearFromString

[1401] ICBCTimestamp::julianDayFromString

[1402] ICBCTimestamp::modifiedJulianDayFromString

[1403] ICBCTimestamp::dayNameFromString

[1404] ICBCTimestamp::dayNameFromNumber

[1405] ICBCTimestamp::monthName

[1406] ICBCTimestamp::monthFromString

[1407] ICBCTimestamp::monthNameFromString

[1408] ICBCTimestamp::monthNameFromNumber

[1409] ICBCTimestamp::quarter

[1410] ICBCTimestamp::quarterFromString

[1411] ICBCTimestamp::yearFromString

[1412] ICBCTimestamp::isLeapYear

[1413] ICBCTimestamp::daysInObject

[1414] ICBCTimestamp::daysInString

[1415] ICBCTimestamp::daysInMonth

[1416] ICBCTimestamp::daysInYear

[1417] ICBCTimestamp::isObjectChanged

[1418] ICBCTimestamp::assignFromTimestamp

[1419] ICBCTimestamp::increment

[1420] ICBCTimestamp::decrement

[1421] ICBCTimestamp::timestampOverflow

[1422] ICBCTimestamp::interval

[1423] ICBCTimestamp::assignFromTimestamp

[1424] Sets all state data in this ICBCTimestamp object equal to the the second ICBCTimestamp object. The change flag of this object is set to TRUE.

[1425] IDL Syntax

[1426] ICBCTimestamp assignFromTimestamp(in ICBCTimestamp aTimestamp);

[1427] ICBCTimestamp::_create

[1428] Returns a pointer to a new ICBCTimestamp object. The object is initialized to today's date and the current local time with a microseconds value of zero.

[1429] ICBCTimestamp::day

[1430] Returns the day part of the timestamp.

[1431] IDL Syntax

[1432] long day( );

[1433] ICBCTimestamp::dayFromString

[1434] Returns the day part of the timestamp encoded in the input string parameter. The input string parameter must conform to a format recognizable as a timestamp. Refer to ICBCTimestamp::initializeFromString( ) for a description of supported formats.

[1435] If the input parameter is not recognizable, a value of −1 is returned.

[1436] IDL Syntax

[1437] long dayFromString(in string aString);

[1438] ICBCTimestamp::dayName

[1439] Returns a string containing the name of the day of the week for this timestamp object.

[1440] IDL Syntax

[1441] long dayName( );

[1442] ICBCTimestamp::dayNameFromNumber

[1443] Returns a string containing the name of the day of the week for the day number within a week provided in the input parameter. The input parameter must be a number between 1 and 7. Sunday is day number 1.

[1444] If the input parameter is not recognizable, an empty string is returned.

[1445] IDL Syntax

[1446] long dayNameFromNumber(in long aDayIndex);

[1447] ICBCTimestamp::dayNameFromString

[1448] Returns a string containing the name of the day of the week for the timestamp encoded in the input string parameter. The input string parameter must conform to a format recognizable as a timestamp. Refer to ICBCTimestamp::initializeFromString( ) for a description of supported formats.

[1449] If the input parameter is not recognizable, an empty string is returned.

[1450] IDL Syntax

[1451] long dayNameFromString(in string aTimestamp);

[1452] ICBCTimestamp::dayOfWeek

[1453] Returns a number between 1 and 7 representing the day of the week for this Timestamp object. Sunday is day number 1.

[1454] IDL Syntax

[1455] long dayOfWeek( );

[1456] ICBCTimestamp::dayOfWeekFromString

[1457] Returns a number between 1 and 7 representing the day of the week for the timestamp encoded in the input string parameter. Sunday is day number 1.

[1458] The input string parameter must conform to a format recognizable as a timestamp. Refer to ICBCTimestamp::initializeFromString( ) for a description of supported formats.

[1459] If the input parameter is not recognizable, a value of −1 is returned.

[1460] IDL Syntax

[1461] long dayOfWeekFromString(in string aString);

[1462] ICBCTimestamp::dayOfYear

[1463] Returns a number between 1 and 366 representing the day of the year for this timestamp object. January 1 is day number 1.

[1464] IDL Syntax

[1465] long dayOfYear( );

[1466] ICBCTimestamp::dayOfYearFromString

[1467] Returns a number between 1 and 366 representing the day of the year for the timestamp encoded in the input string parameter. January 1 is day number 1.

[1468] The input string parameter must conform to a format recognizable as a timestamp. Refer to ICBCTimestamp::initializeFromString( ) for a description of supported formats.

[1469] If the input parameter is not recognizable, a value of −1 is returned.

[1470] IDL Syntax

[1471] long dayOfYearFromString(in string aString);

[1472] ICBCTimestamp::daysInObject

[1473] The result is the number of days from January 1, 0001 to the timestamp represented by this object, plus one day. i.e., an object holding a timestamp for date January 2, 0001 returns the value 2.

[1474] IDL Syntax

[1475] long daysInObject( );

[1476] ICBCTimestamp::daysInMonth

[1477] Returns the number of days in the month of the year provided in the input parameters. Month number must be between 1 and 12. If the input parameters are not valid, a value of −1 is returned.

[1478] IDL Syntax

[1479] long daysInMonth(in long aYear, in long aMonth);

[1480] ICBCTimestamp::daysInString

[1481] The result is the number of days from January 1, 0001 to the timestamp represented by the string parameter, plus one day. i.e., an object holding a timestamp for date 00010102 returns the value 2.

[1482] If the string is invalid, returns a value of −1.

[1483] IDL Syntax

[1484] long daysInString(in string aTimestamp);

[1485] The input string parameter must conform to a format recognizable as a timestamp. Refer to ICBCTimestamp::initializeFromString( ) for a description of supported formats. If the input parameter is not recognizable, a value of −1 is returned.

[1486] ICBCTimestamp::daysInYear

[1487] Returns the number of days in the year provided in the input parameter. If the input parameter is not valid, a value of −1 is returned. Returns the number of days in the year provided in the input parameter.

[1488] If the input parameter is not valid, a value of −1 is returned.

[1489] IDL Syntax

[1490] long daysInYear(in long aYear);

[1491] ICBCTimestamp::decrement

[1492] Subtracts a ICBCDuration from the value of this ICBCTimestamp object. No value is returned (i.e., this is effectively a−=operator).

[1493] Decrementing of a timestamp with a duration (of any type) is carried out on the date and time portions of the timestamp as described for ICBCDate and ICBCTime, except that any underflow of microseconds is satisfied from the seconds portion of the result timestamp, and any underflow of hours is satisfied from the days portion.

[1494] If the years value of the result of an decrement operation is less than 0001 years, then the years value of the result is set to 0001, and the number of “underflow” years can be retrieved as a negative number with the dateOverflow( ) function.

[1495] The change flag of this object is set to TRUE.

[1496] Although an ICBCTimestamp object with an time portion equal to 24.00.00 can be initialized, or returned from an ICBCTimestamp::interval operation, and can be input to an increment or decrement operation, such a timestamp is never be returned as a result of the increment or decrement operation. For the purposes of the calculation, the time portion of the timestamp is considered to be 00.00.00, with the days part incremented by 1. For example, a timestamp value of 1998-11-2-24.00.00.000000 plus or minus a zero duration will return the timestamp result 1998-11-3-00.00.00.000000.

[1497] IDL Syntax

[1498] void decrement(in ICBCDuration aDuration);

[1499] ICBCTimestamp::equalTo

[1500] Returns TRUE if the date and time this ICBCTimestamp object is equal to the other ICBCTimestamp object.

[1501] Note that because of the alternative representations of midnight it is possible to have two different timestamps that actually represent the same point in time, for example: 1997-11-02-24.00.00.000000 and 1997-11-03-00.00.00.000000. ICBCTimestamp compares timestamps by date portion, followed by time portion, and will consider that for timestamp pairs of this type, the timestamp with the higher day part is greater. e.g.: 1997-11-03-00.00.00.000000>1997-11-0224.00.00.000000.

[1502] IDL Syntax

[1503] boolean equalTo(n ICBCTimestamp aTimestamp);

[1504] ICBCTimestamp::formattedString

[1505] Returns the value of this timestamp object as a string in the form yyyy-mm-dd-hh.mm.ss.mmmmmm.

[1506] The application must supply a non-const pointer to a target storage area long enough to receive the formatted timestamp. The function returns a reference to this area, enabling the function to be nested in stream operations.

[1507] IDL Syntax

[1508] string formattedString(inout string aOutput);

[1509] ICBCTimestamp::greaterThan

[1510] Returns TRUE if the date and time stored in this ICBCTimestamp object is greater than the other ICBCTimestamp object.

[1511] IDL Syntax

[1512] boolean greaterThan(in ICBCTimestamp aTimestamp);

[1513] ICBCTimestamp::greaterThanOrEqualTo

[1514] Returns TRUE if the date and time stored in this ICBCTimestamp object is greater than or equal to the other ICBCTimestamp object.

[1515] IDL Syntax

[1516] boolean greaterThanOrEqualTo(in ICBCTimestamp aTimestamp);

[1517] ICBCTimestamp::hour

[1518] Returns the hour part of the timestamp.

[1519] IDL Syntax

[1520] long hour( );

[1521] ICBCTimestamp::increment

[1522] Adds a ICBCDuration to the value of this ICBCTimestamp object.

[1523] Incrementing of a timestamp with a duration (of any type) is carried out on the date and time portions of the timestamp as described for ICBCDate and ICBCTime, except that any overflow of microseconds is carried into the seconds portion of the result timestamp, and any overflow of hours is carried into the days portion.

[1524] If the years value of the result of an increment operation is greater than 9999 years, then the years value of the result timestamp is set to 9999, and the number of overflow years can be retrieved using the dateOverflow( ) function.

[1525] The change flag of this object is set to TRUE.

[1526] Although an ICBCTimestamp object with an time portion equal to 24.00.00 can be initialized, or returned from an ICBCTimestamp::interval operation, and can be input to an increment or decrement operation, such a timestamp is never be returned as a result of the increment or decrement operation. For the purposes of the calculation, the time portion of the In timestamp is considered to be 00.00.00, with the days part incremented by 1. For example, a timestamp value of 1998-11-2-24.00.00.000000 plus or minus a zero duration will return the timestamp result 1998-11-3-00.00.00.000000.

[1527] IDL Syntax

[1528] void increment(in ICBCDuration Duration);

[1529] ICBCTimestamp::initializeFromString

[1530] Accepts a value for the time in the form of a string. Any existing value in the object is replaced. Returns TRUE if the string is a valid timestamp representation and the object is successfully initialized. Returns FALSE if the parameter is invalid. If FALSE is returned the state of the object is unchanged.

[1531] IDL Syntax

[1532] boolean initializeFromstring(in string aTimestamp);

[1533] The string must be in one of two formats:

[1534] A character string of length 14 numeric characters, yyyyxxddhhmmss. Leading and trailing blanks are acceptable provided the string length is less than 30 characters. The string must represent a valid date and time. The microseconds portion of the timestamp is set to zero. Only SBCS characters may be present in the string.

[1535] A punctuated string of the form yyyy-mm-dd-hh.mm.ss.mmmmmm. Leading and trailing blanks are acceptable provided the string length is less than 30 characters. The string must represent a valid date and time. Leading zeros can be omitted from month, day, and hour. Microseconds can be truncated, or omitted entirely. If omitted, microseconds are set to zero. Only SBCS characters may be present in the string.

[1536] ICBCTimestamp::initializeFromDateTime

[1537] Initializes this timestamp object from one ICBCDate and one ICBCTime object. The time portion the timestamp takes its value from the ICBCDate and the time portion from the ICBCTime object. The microseconds portion of the timestamp is set to zero.

[1538] IDL Syntax

[1539] boolean initializeFromDateTime(in ICBCDate_ptr a ICBCDate,

[1540] in ICBCTime_ptr a ICBCTime);

[1541] ICBCTimestamp::initializeFromDate

[1542] Initializes the date part of this timestamp object from the provided ICBCDate parameter. The time portion and the microseconds portion of the timestamp are set to zero.

[1543] IDL Syntax

[1544] void initializeFromDate(in ICBCDate aDate);

[1545] ICBCTimestamp::initializeFromTime

[1546] Initializes the date portion of this timestamp object to the current date, and the time portion from the provided ICBCTime parameter. The microseconds portion of the timestamp is set to zero.

[1547] IDL Syntax

[1548] void initializeFromTime(in ICBCTime aTime);

[1549] ICBCTimestamp::interval

[1550] Calculates the Duration between two ICBCTimestamp objects. The result is a pointer to a new ICBCDuration object of type TIMESTAMP.

[1551] If the interval between TIMESTAMP1 and TIMESTAMP2 is required, and TIMESTAMP1 is greater than or equal to TIMESTAMP2, the operation is performed by subtracting TIMESTAMP2 from TIMESTAMP1. If, however, TIMESTAMP1 is less than TIMESTAMP2, TIMESTAMP1 is subtracted from TIMESTAMP2, and the sign of the result is made negative. The following procedural description clarifies the steps involved in the operation result=TIMESTAMP1−TIMESTAMP2.

[1552] If MICROSECOND(TS2)<=MICROSECOND(TS1)

[1553] then MICROSECOND(RESULT)=MICROSECOND(TS1)−MICROSECOND(TS2).

[1554] If MICROSECOND(TS2)>MICROSECOND(TS1)

[1555] then MICROSECOND(RESULT)=1000000+MICROSECOND(TS1)−MICROSECOND(TS2).

[1556] and SECOND(TS2) is incremented by 1.

[1557] The seconds and minutes part of the timestamps are subtracted as specified in rules for subtracting ICBCTime.

[1558] If HOUR(TS2)<=HOUR(TS1)

[1559] then HOUR(RESULT)=HOUR(TS1)−HOUR(TS2).

[1560] IF HOUR(TS2)>HOUR(S1)

[1561] then HOUR(RESULT)=24+HOUR(TS1)−HOUR(TS2)

[1562] and DAY(TS2) is incremented by 1

[1563] The date part of the timestamps is subtracted as specified in the rules for subtracting ICBCDate.

[1564] IDL Syntax

[1565] ICBCDuration_ptr intervalFromTimestamp (in ICBCTimestamp aTimestamp);

[1566] ICBCDuration_ptr intervalFromString(in string aTimestamp);

[1567] In the case with a string parameter, the parameter must be a valid string representation of a timestamp, in the form yyyy-mm-dd-hh.mm.ss.mmmmmm For details refer to the description of ICBCTimestamp::initializeFromString( ).

[1568] If the string parameter to this function cannot be recognized as a valid timestamp, then a pointer value of −1 is returned.

[1569] ICBCTimestamp::isLeapYear

[1570] Returns TRUE if the year number in the input parameter is a leap year, FALSE otherwise. Year number must be between 1 and 9999.

[1571] If the input parameter is not in this range, FALSE is returned.

[1572] IDL Syntax

[1573] boolean isLeapYear(in long aYear);

[1574] ICBCTimestamp::isObjectChanged

[1575] Returns a boolean indicating whether the the value of this object has been changed since it was initialized.

[1576] IDL Syntax

[1577] boolean isObjectChanged( );

[1578] ICBCTimestamp::julianDay

[1579] Returns the Julian day number corresponding to noon GMT on the date of this timestamp object. (Julian Day count started at noon, GMT, on January 1 4712 BC.)

[1580] IDL Syntax

[1581] In, long julianDay( );

[1582] ICBCTimestamp::julianDayFromString

[1583] Returns the Julian day number corresponding to noon GMT on the timestamp encoded in the input string parameter. (Julian Day count started at noon, GMT, on January 1 4712 BC) The input string parameter must conform to a format recognizable as a timestamp. Refer to ICBCTimestamp::initializeFromString( ) for a description of supported formats.

[1584] If the input parameter is not recognizable, a value of −1 is returned.

[1585] IDL Syntax

[1586] long julianDayFromString(in string aString);

[1587] ICBCTimestamp::lessThan

[1588] Returns TRUE if the date and time stored in this ICBCTimestamp object is less than the other ICBCTimestamp object.

[1589] IDL Syntax

[1590] boolean lessThan(in ICBCTimestamp aTimestamp);

[1591] ICBCTimestamp::lessThanOrEqualTo

[1592] Returns TRUE if the date and time stored in this ICBCTimestamp object is less than or equal to the other ICBCTimestamp object.

[1593] IDL Syntax

[1594] boolean lessThanOrEqualTo(in ICBCTimestamp aTimestamp);

[1595] ICBCTimestamp::microsecond

[1596] Returns the microsecond part of the timestamp.

[1597] IDL Syntax

[1598] long microsecond( );

[1599] ICBCTimestamp::minute

[1600] Returns the minute part of the timestamp.

[1601] IDL Syntax

[1602] long minute( );

[1603] ICBCTimestamp::modifiedJulianDay

[1604] Returns the Modified Julian day number (MUD) corresponding to time 00:00:00 GMT on the date of this timestamp object. MJD is defined as Julian Day—2,400,000.5 days. It thus starts at time 00:00:00 (i.e., midnight), in line with normal civil practice, and unlike Julian Day which extends from noon to noon.

[1605] IDL Syntax

[1606] long modifiedJulianDay( );

[1607] ICBCTimestamp::modifiedJulianDayFromString

[1608] Returns the Modified Julian day number (MJD) corresponding to time 00:00:00 GMT on the ID date of the timestamp encoded in the input string parameter. MJD is defined as Julian Day—2,400,000.5 days. It thus starts at time 00:00:00 (i.e., midnight), in line with normal civil practice, and unlike Julian Day which extends from noon to noon. The input string parameter must conform to a format recognizable as a timestamp. Refer to ICBCTimestamp::initializeFromstring( ) for a description of supported formats.

[1609] If the input parameter is not recognizable, a value of −1 is returned.

[1610] IDL Syntax

[1611] long modifiedJulianDayFromString(in string aString);

[1612] ICBCTimestamp::month

[1613] Returns the month pant of the timestamp.

[1614] IDL Syntax

[1615] long month( );

[1616] ICBCTimestamp::monthFromString

[1617] Returns the month part of the timestamp encoded in the input string parameter. The input string parameter must conform to a format recognizable as a timestamp. Refer to ICBCTimestamp::initializeFromString( ) for a description of supported formats.

[1618] If the input parameter is not recognizable, a value of −1 is returned.

[1619] IDL Syntax

[1620] long monthFromString(in string aString);

[1621] ICBCTimestamp::monthName

[1622] Returns a string containing the name of the month of this timestamp object.

[1623] IDL Syntax

[1624] string monthName( );

[1625] ICBCTimestamp::monthNameFromNumber

[1626] Returns a string containing the name of the month for the month number within a year provided in the input parameter. The input parameter must be a number between 1 and 12.

[1627] If the input parameter is not recognizable, an empty string is returned.

[1628] IDL Syntax

[1629] string monthNameFromNumber(in long aDayIndex);

[1630] ICBCTimestamp::monthNameFromString

[1631] Returns a string containing the name of the month for the timestamp encoded in the input string parameter. The input string parameter must conform to a format recognizable as a timestamp. Refer to ICBCTimestamp::initializeFromString( ) for a description of supported formats.

[1632] If the input parameter is not recognizable, an empty string is returned.

[1633] IDL Syntax

[1634] string monthNameFromString(in string aTimestamp);

[1635] ICBCTimestamp::notEqualTo

[1636] The opposite of the operator==member.

[1637] IDL Syntax

[1638] boolean notEqualTo(in ICBCTimestamp aTimestamp);

[1639] ICBCTimestamp::quarter

[1640] Returns a number for the quarter within the year for this timestamp object. timestamps between January 1 and March 31 are in the first quarter, and so on.

[1641] IDL Syntax

[1642] long quarter( );

[1643] ICBCTimestamp::quarterFromString

[1644] Returns a number for the quarter within the year for the timestamp encoded in the input string parameter. The input string parameter must conform to a format recognizable as a timestamp. Refer to ICBCTimestamp::initializedFromString( ) for a description of supported formats. Timestamps between January 1 and March 31 are in the first quarter, and so on.

[1645] If the input parameter is not recognizable, a value of −1 is returned.

[1646] IDL Syntax

[1647] long quarterFromString(in string aTimestamp);

[1648] ICBCTimestamp::second

[1649] Returns the second part of the timestamp.

[1650] IDL Syntax

[1651] ICBCTimestamp::timestampOverflow

[1652] Returns the number of overflow or underflow years of a preceding increment or decrement operation. For an increment, returns the years in excess of year 9999. For a decrement, returns the number of years less than year 0001.

[1653] IDL Syntax

[1654] long timestampOverflow( );

[1655] ICBCTimestamp::year

[1656] Returns the year part of the timestamp.

[1657] IDL Syntax

[1658] longYear( );

[1659] ICBCTimestamp::yearFromString

[1660] Returns the year part of the timestamp encoded in the input string parameter. The input string parameter must conform to a format recognizable as a timestamp. Refer to ICBCTimestamp::initializeFromString( ) for a description of supported formats.

[1661] If the input parameter is not recognizable, a value of −1 is returned.

[1662] IDL Syntax

[1663] long yearFromString(in string aString);