28.3 OCIの日付関数、日時関数および時間隔関数
OCIの日付関数および時間隔関数をリストし、説明します。
表28-4は、この項で説明しているOCIの日付関数および時間隔関数を示しています。
表28-4 日付関数
関数 | 用途 |
---|---|
日数の加算または減算を行います。 |
|
月の加算または減算を行います。 |
|
日付を割り当てます |
|
指定の日付が有効かどうかをチェックします。 |
|
日付を比較します |
|
2つの日付の間にある日数を取得します。 |
|
文字列を日付に変換します。 |
|
日付の日付部分を取得します。 |
|
日付の時刻部分を取得します。 |
|
月末の日付を取得します。 |
|
次の日の日付を取得します。 |
|
日付の日付部分を設定します。 |
|
日付の時刻部分を設定します。 |
|
現行のシステム日付および時刻を取得します。 |
|
日付の割当てを実行します。 |
|
指定の日付が有効かどうかをチェックします。 |
|
2つの日時値を比較します。 |
|
日時記述子を作成します。 |
|
ある日時型を別の日時型に変換します。 |
|
サイズ |
|
指定された書式に従って、指定の文字列を |
|
日時値の日付部分(年、月、日)を取得します。 |
|
日時値の時刻部分(時間、分、秒、小数秒)を取得します。 |
|
日時値のタイム・ゾーン名部分を取得します。 |
|
日時値のタイム・ゾーン(時間、分)部分を取得します。 |
|
日時に時間隔を加算して、結果の日時を生成します。 |
|
日時から時間隔を減算して、その結果を日時に格納します。 |
|
2つの日時を入力値にして、その差異を時間隔に格納します。 |
|
現行のシステム日付および時刻を、タイム・ゾーン付きタイムスタンプとして取得します。 |
|
|
|
指定された日付を指定の書式の文字列に変換します。 |
|
日付を文字列に変換します。 |
|
あるタイム・ゾーンの日付を別のゾーンの日付に変換します。 |
|
2つの時間隔を加算して、その結果の時間隔を生成します。 |
|
ある時間隔を別の時間隔にコピーします。 |
|
時間隔の妥当性をチェックします。 |
|
2つの時間隔を比較します |
|
時間隔をOracle |
|
Oracle |
|
時間隔文字列が指定されている場合、その文字列で表現される時間隔を戻します。 |
|
|
|
時間隔から日、時、分、秒の値を取得します。 |
|
時間隔から年と月を取得します。 |
|
時間隔をOracle |
|
時間隔に日、時、分、秒を設定します。 |
|
時間隔に年と月を設定します。 |
|
2つの時間隔を減算し、その結果を時間隔に格納します。 |
|
時間隔をOracle NUMBERに変換します。 |
|
時間隔が指定されている場合、その時間隔を表現する文字列を生成します。 |
28.3.1 OCIDateAddDays()
指定の日付に日数を加算または減算します。
用途
指定の日付に日数を加算または減算します。
構文
sword OCIDateAddDays ( OCIError *err, const OCIDate *date, sb4 num_days, OCIDate *result );
パラメータ
戻り値
この関数は、無効な日付が渡された場合はエラーを戻します。
関連トピック
28.3.2 OCIDateAddMonths()
指定の日付に月数を加算または減算します。
用途
指定の日付に月数を加算または減算します。
構文
sword OCIDateAddMonths ( OCIError *err, const OCIDate *date, sb4 num_months, OCIDate *result );
パラメータ
コメント
入力されたdate
が月末の場合は、出力される日付も月末になるように適切な調整が行われます。たとえば、2月28日+1か月=3月31日、11月30日 – 3か月=8月31日となります。それ以外の場合、result
の日付はdate
の日付コンポーネントと同じになります。
戻り値
この関数は、無効な日付が渡された場合はエラーを戻します。
関連トピック
28.3.3 OCIDateAssign()
日付の割当てを実行します。
用途
日付の割当てを実行します。
構文
sword OCIDateAssign ( OCIError *err, const OCIDate *from, OCIDate *to );
パラメータ
コメント
この関数は、あるOCIDate
変数の値を別の変数に割り当てます。
関連トピック
28.3.4 OCIDateCheck()
指定の日付が有効かどうかをチェックします。
用途
指定の日付が有効かどうかをチェックします。
構文
sword OCIDateCheck ( OCIError *err, const OCIDate *date, uword *valid );
パラメータ
- err (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
をコールして診断情報を取得します。 - date (IN)
-
チェックする日付です。
- valid (OUT)
-
有効な日付の場合は0 (ゼロ)を戻します。それ以外の場合は、表28-5に指定されたすべてのエラー・ビットの論理演算子ORによる組合せを戻します。
表28-5 OCIDateCheck()の有効なパラメータによって戻されるエラー・ビット
マクロ名 | ビット数 | エラー |
---|---|---|
|
0x1 |
無効な日 |
|
0x2 |
無効な日の、有効な日に対する大/小を示すビット(1=小)。 |
|
0x4 |
無効な月 |
|
0x8 |
無効な月の、有効な月に対する大/小を示すビット(1=小)。 |
|
0x10 |
無効な年 |
|
0x20 |
無効な年の、有効な年に対する大/小を示すビット(1=小)。 |
|
0x40 |
無効な時刻(時) |
|
0x80 |
無効な時刻(時)の、有効な時刻(時)に対する大/小を示すビット(1=小)。 |
|
0x100 |
無効な時刻(分) |
|
0x200 |
無効な時刻(分)の、有効な時刻(分)に対する大/小を示すビット(1=小)。 |
|
0x400 |
無効な時刻(秒) |
|
0x800 |
無効な時刻(秒)の、有効な時刻(秒)に対する大/小を示すビット(1=小)。 |
|
0x1000 |
日が1582から欠落しています。 |
|
0x2000 |
年が0 (ゼロ)に等しくありません。 |
|
0x8000 |
無効な日付書式入力。 |
たとえば、渡された日付が2/0/1990 25:61:10 (月/日/年 時:分:秒書式)の場合は、次のエラーが戻されます。
OCI_DATE_INVALID_DAY | OCI_DATE_DAY_BELOW_VALID | OCI_DATE_INVALID_HOUR | OCI_DATE_INVALID_MINUTE.
戻り値
この関数は、date
またはvalid
ポインタがNULL
の場合はエラーを戻します。
関連トピック
28.3.5 OCIDateCompare()
2つの日付を比較します。
用途
2つの日付を比較します。
構文
sword OCIDateCompare ( OCIError *err, const OCIDate *date1, const OCIDate *date2, sword *result );
パラメータ
- err (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
をコールして診断情報を取得します。 - date1、date2 (IN)
-
比較する日付です。
- result (OUT)
-
表28-6に示したような比較結果です。
表28-6 比較結果
比較結果 | resultパラメータの出力 |
---|---|
|
-1 |
|
0 |
|
1 |
戻り値
この関数は、無効な日付が渡された場合はエラーを戻します。
関連トピック
28.3.6 OCIDateDaysBetween()
2つの日付間の日数を取得します。
用途
2つの日付間の日数を取得します。
構文
sword OCIDateDaysBetween ( OCIError *err, const OCIDate *date1, const OCIDate *date2, sb4 *num_days );
パラメータ
コメント
date1
とdate2
の間の日数の計算時には、時刻は無視されます。
戻り値
この関数は、無効な日付が渡された場合はエラーを戻します。
関連トピック
28.3.7 OCIDateFromText()
指定された書式に従って、文字列を日付型に変換します。
用途
指定された書式に従って、文字列を日付型に変換します。
構文
sword OCIDateFromText ( OCIError *err, const OraText *date_str, ub4 d_str_length, const OraText *fmt, ub1 fmt_length, const OraText *lang_name, ub4 lang_length, OCIDate *date );
パラメータ
- err (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
をコールして診断情報を取得します。 - date_str (IN)
-
Oracle日付に変換される入力文字列です。
- d_str_length (IN)
-
入力文字列のサイズです。長さが–1の場合、
date_str
はNULL
で終了する文字列として処理されます。 - fmt (IN)
-
変換書式です。
fmt
がNULL
ポインタの場合、文字列は"DD-MON-YY"書式になります。 - fmt_length (IN)
-
fmt
パラメータの長さです。 - lang_name (IN)
-
日および月の名前と省略が指定される言語です。
lang_name
がNULL
文字列(text *)0
の場合は、そのセッションのデフォルト言語が使用されます。 - lang_length (IN)
-
lang_name
パラメータの長さです。 - date (OUT)
-
日付に変換された指定文字列です。
コメント
書式および多言語引数の詳細は、『Oracle Database SQL言語リファレンス』のTO_DATE
変換関数の説明を参照してください。
戻り値
この関数は、無効な書式、言語または入力文字列を受け取った場合はエラーを戻します。
関連トピック
28.3.8 OCIDateGetDate()
Oracle日付に格納されている年月日を取得します。
用途
Oracle日付に格納されている年月日を取得します。
構文
void OCIDateGetDate ( const OCIDate *date, sb2 *year, ub1 *month, ub1 *day );
パラメータ
コメント
なし。
関連トピック
28.3.9 OCIDateGetTime()
Oracle日付に格納されている時刻を取得します。
用途
Oracle日付に格納されている時刻を取得します。
構文
void OCIDateGetTime ( const OCIDate *date, ub1 *hour, ub1 *min, ub1 *sec );
パラメータ
戻り値
時、分、秒の時刻情報を戻します。
関連トピック
28.3.10 OCIDateLastDay()
指定された日付の月の最後の日の日付を取得します。
用途
指定された日付の月の最後の日の日付を取得します。
構文
sword OCIDateLastDay ( OCIError *err, const OCIDate *date, OCIDate *last_day );
パラメータ
戻り値
この関数は、無効な日付が渡された場合はエラーを戻します。
関連トピック
28.3.11 OCIDateNextDay()
指定した日付以降で、指定した曜日の最初の日付を取得します。
用途
指定した日付以降で、指定した曜日の最初の日付を取得します。
構文
sword OCIDateNextDay ( OCIError *err, const OCIDate *date, const OraText *day, ub4 day_length, OCIDate *next_day );
パラメータ
戻り値
date
以降で、day
によって指定された週の最初の曜日の日付を戻します。
例
次のコード例は、1996年4月18日(木曜日)の次の月曜日の日付の取得方法を示しています。
指定した日付以降の指定した曜日の日付の取得
OCIDate one_day, next_day; /* Add code here to set one_day to be '18-APR-96' */ OCIDateNextDay(err, &one_day, "MONDAY", strlen("MONDAY"), &next_day);
OCIDateNextDay()
は"22-APR-96"を戻します。
この関数は、無効な日付または曜日が渡された場合はエラーを戻します。
関連トピック
28.3.12 OCIDateSetDate()
Oracle日付に値を設定します。
用途
Oracle日付に値を設定します。
構文
void OCIDateSetDate ( OCIDate *date, sb2 year, ub1 month, ub1 day );
パラメータ
コメント
なし。
関連トピック
28.3.13 OCIDateSetTime()
Oracle日付に時刻情報を設定します。
用途
Oracle日付に時刻情報を設定します。
構文
void OCIDateSetTime ( OCIDate *date, ub1 hour, ub1 min, ub1 sec );
パラメータ
コメント
なし。
関連トピック
28.3.14 OCIDateSysDate()
クライアントの現行のシステム日付およびシステム時刻を取得します。
用途
クライアントの現行のシステム日付およびシステム時刻を取得します。
構文
sword OCIDateSysDate ( OCIError *err, OCIDate *sys_date );
パラメータ
コメント
なし。
関連トピック
28.3.15 OCIDateTimeAssign()
日時の割当てを実行します。
用途
日時の割当てを実行します。
構文
sword OCIDateTimeAssign ( void *hndl, OCIError *err, const OCIDateTime *from, OCIDateTime *to );
パラメータ
コメント
この関数は、type
パラメータの説明にリストされている日時型に関して、from
日時からto
日時への割当てを実行します。
出力のtype
は入力と同じです。
戻り値
OCI_SUCCESS
またはOCI_ERROR。
28.3.16 OCIDateTimeCheck()
指定の日付が有効かどうかをチェックします。
用途
指定の日付が有効かどうかをチェックします。
構文
sword OCIDateTimeCheck ( void *hndl, OCIError *err, const OCIDateTime *date, ub4 *valid );
パラメータ
- hndl (IN)
-
OCIユーザー・セッション・ハンドルまたは環境ハンドルです。ユーザー・セッション・ハンドルが渡されると、セッションの
NLS_LANGUAGE
およびセッションのNLS_CALENDAR
で変換が行われます。渡されない場合は、デフォルトが使用されます。 - err (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
をコールして診断情報を取得します。 - date (IN)
-
チェックする日付です。
- valid (OUT)
-
有効な日付の場合は0 (ゼロ)を戻します。それ以外の場合は、表28-7に指定されたすべてのエラー・ビットの論理演算子ORによる組合せを戻します。
表28-7 OCIDateTimeCheck()の有効なパラメータによって戻されるエラー・ビット
マクロ名 | ビット数 | エラー |
---|---|---|
|
0x1 |
無効な日 |
|
0x2 |
無効な日の、有効な日に対する大/小を示すビット(1=小)。 |
|
0x4 |
無効な月 |
|
0x8 |
無効な月の、有効な月に対する大/小を示すビット(1=小)。 |
|
0x10 |
無効な年 |
|
0x20 |
無効な年の、有効な年に対する大/小を示すビット(1=小)。 |
|
0x40 |
無効な時刻(時) |
|
0x80 |
無効な時刻(時)の、有効な時刻(時)に対する大/小を示すビット(1=小)。 |
|
0x100 |
無効な時刻(分) |
|
0x200 |
無効な時刻(分)の、有効な時刻(分)に対する大/小を示すビット(1=小)。 |
|
0x400 |
無効な時刻(秒) |
|
0x800 |
無効な時刻(秒)の、有効な時刻(秒)に対する大/小を示すビット(1=小)。 |
|
0x1000 |
日が1582から欠落しています。 |
|
0x2000 |
年が0 (ゼロ)に等しくありません。 |
|
0x4000 |
無効なタイム・ゾーン |
|
0x8000 |
無効な日付書式入力。 |
たとえば渡された日付が2/0/1990 25:61:10 (月/日/年 時:分:秒書式)の場合は、次のエラーが戻されます。
OCI_DT_INVALID_DAY | OCI_DT_DAY_BELOW_VALID | OCI_DT_INVALID_HOUR | OCI_DT_INVALID_MINUTE.
戻り値
OCI_SUCCESS
、OCI_INVALID_HANDLE
(errがNULL
ポインタの場合)、OCI_ERROR
(date
またはvalid
がNULL
ポインタの場合)。
関連トピック
28.3.17 OCIDateTimeCompare()
2つの日時値を比較します。
用途
2つの日時値を比較します。
構文
sword OCIDateTimeCompare ( void *hndl, OCIError *err, const OCIDateTime *date1, const OCIDateTime *date2, sword *result );
パラメータ
- hndl (IN/OUT)
-
OCIユーザー・セッション・ハンドルまたは環境ハンドルです。
- err (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
をコールして診断情報を取得します。 - date1、date2 (IN)
-
比較する日付です。
- result (OUT)
-
表28-8に示したような比較結果です。
表28-8 OCIDateTimeCompare()のresultパラメータによって戻される比較結果
比較結果 | resultパラメータの出力 |
---|---|
|
-1 |
|
0 |
|
1 |
戻り値
OCI_SUCCESS
、OCI_INVALID_HANDLE
(errがNULL
ポインタの場合)、OCI_ERROR
(無効な日付が使用されている場合または入力日付引数が相互に比較可能な型でない場合)。
28.3.18 OCIDateTimeConstruct()
日時記述子を作成します。
用途
日時記述子を作成します。
構文
sword OCIDateTimeConstruct ( void *hndl, OCIError *err, OCIDateTime *datetime, sb2 year, ub1 month, ub1 day, ub1 hour, ub1 min, ub1 sec, ub4 fsec, OraText *timezone, size_t timezone_length );
パラメータ
- hndl (IN)
-
OCIユーザー・セッション・ハンドルまたは環境ハンドルです。
- err (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
をコールして診断情報を取得します。 - datetime (IN)
-
OCIDateTime
記述子へのポインタです。 - year (IN)
-
年の値です。
- month (IN)
-
月の値です。
- day (IN)
-
日の値です。
- hour (IN)
-
時間の値です。
- min (IN)
-
分の値です。
- sec (IN)
-
秒の値です。
- fsec (IN)
-
小数秒の値です。
- timezone (IN)
-
タイム・ゾーン文字列です。タイム・ゾーン置換の文字列表現は、[+|-][HH:MM]という書式での、現地時間とUTC (協定世界時、以前はグリニッジ平均時)との差異(時分による)です。たとえば、「-08:00」のようにします。
- timezone_length (IN)
-
タイム・ゾーン文字列の長さです。
コメント
日時の型は、OCIDateTime
記述子の型です。型に基づいた関連フィールドのみを使用します。タイム・ゾーンを持つ型の場合、日付フィールドと時刻フィールドは、指定されたタイム・ゾーンのローカル・タイムとみなされます。
タイム・ゾーンが指定されていない場合は、セッションのデフォルト・タイム・ゾーンが使用されます。
戻り値
OCI_SUCCESS
、OCI_ERROR
(日時が無効な場合)。
28.3.19 OCIDateTimeConvert()
ある日時型を別の日時型に変換します。
用途
ある日時型を別の日時型に変換します。
構文
sword OCIDateTimeConvert ( void *hndl, OCIError *err, OCIDateTime *indate, OCIDateTime *outdate );
パラメータ
コメント
この関数は、ある日時型を別の日時型に変換します。結果タイプは、outdate
記述子の型になります。タイム・ゾーンを持たない日時をタイム・ゾーンを持つ日時に変換する場合は、セッションのデフォルト・タイム・ゾーン(ORA_SDTZ
)が使用されます。
戻り値
OCI_SUCCESS
、OCI_INVALID_HANDLE
(err
がNULL
の場合)、OCI_ERROR
(指定の入力値では変換が不可能な場合)。
関連トピック
28.3.20 OCIDateTimeFromArray()
日付が含まれている配列をOCIDateTime
記述子に変換します。
用途
日付が含まれている配列をOCIDateTime
記述子に変換します。
構文
sword OCIDateTimeFromArray ( void *hndl, OCIError *err, const ub1 *inarray, ub4 *len ub1 type, OCIDateTime *datetime, const OCIInterval *reftz, ub1 fsprec );
パラメータ
- hndl (IN)
-
OCIユーザー・セッション・ハンドルまたは環境ハンドルです。
- err (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
をコールして診断情報を取得します。 - inarray(IN)
-
日付が含まれるub1の配列です。
- len (IN)
-
inarray
の長さです。 - type (IN)
-
結果の日時の型です。配列は、特定のSQLT型に変換されます。
- datetime (OUT)
-
OCIDateTime
記述子へのポインタです。 - reftz (IN)
-
SQLT_TIMESTAMP_LT
Z
型の変換時に参照として使用するOCIInterval
の記述子です。 - fsprec (IN)
-
結果の日時の小数秒の精度です。
戻り値
OCI_SUCCESS
、OCI_ERROR
(type
が無効な場合)。
28.3.21 OCIDateTimeFromText()
指定された書式に従って、指定の文字列をOCIDateTime
記述子のOracle日時型に変換します。
用途
指定された書式に従って、指定の文字列をOCIDateTime
記述子のOracle日時型に変換します。
構文
sword OCIDateTimeFromText ( void *hndl, OCIError *err, const OraText *date_str, size_t dstr_length, const OraText *fmt, ub1 fmt_length, const OraText *lang_name, size_t lang_length, OCIDateTime *datetime );
パラメータ
- hndl (IN)
-
OCIユーザー・セッション・ハンドルまたは環境ハンドルです。ユーザー・セッション・ハンドルが渡されると、セッションのNLS_LANGUAGEおよびセッションのNLS_CALENDARで変換が行われます。渡されない場合は、デフォルトが使用されます。
- err (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
をコールして診断情報を取得します。 - date_str (IN)
-
Oracle日時に変換される入力文字列です。
- dstr_length (IN)
-
入力文字列のサイズです。長さが–1の場合、
date_str
はNULL
で終了する文字列として処理されます。 - fmt (IN)
-
変換書式です。
fmt
がNULL
ポインタの場合、文字列は日時型のデフォルトの書式になります。 - fmt_length (IN)
-
fmt
パラメータの長さです。 - lang_name (IN)
-
日および月の名前と略称が指定される際の言語を指定します。
lang_name
がNULL
(lang_name
=(text *)0
)の場合は、セッションのデフォルト言語が使用されます。 - lang_length (IN)
-
lang_name
パラメータの長さです。 - datetime (OUT)
-
日付に変換された指定文字列です。
コメント
書式引数の詳細は、『Oracle Database SQL言語リファレンス』のTO_DATE
変換関数の説明を参照してください。
戻り値
OCI_SUCCESS
、OCI_INVALID_HANDLE
(err
がNULL
の場合)、OCI_ERROR
(次のいずれかの場合)。
-
無効な書式が使用されている場合。
-
不明な言語が使用されている場合。
-
無効な入力文字列が使用されている場合。
28.3.22 OCIDateTimeGetDate()
日時値の日付部分(年、月、日)を取得します。
用途
日時値の日付部分(年、月、日)を取得します。
構文
sword OCIDateTimeGetDate ( void *hndl, OCIError *err, const OCIDateTime *datetime, sb2 *year, ub1 *month, ub1 *day );
パラメータ
コメント
この関数は、日時値の日付部分(年、月、日)を取得します。
戻り値
OCI_SUCCESS
またはOCI_ERROR
。
28.3.23 OCIDateTimeGetTime()
日時値の時刻部分(時間、分、秒、小数秒)を取得します。
用途
日時値の時刻部分(時間、分、秒、小数秒)を取得します。
構文
sword OCIDateTimeGetTime ( void *hndl, OCIError *err, OCIDateTime *datetime, ub1 *hour, ub1 *min, ub1 *sec, ub4 *fsec );
パラメータ
コメント
この関数は、指定の日時値から時刻部分(時間、分、秒、小数秒)を取得します。
この関数は、指定の日時に時間情報が含まれていない場合はエラーを戻します。
戻り値
OCI_SUCCESS
、OCI_ERROR
(日時に時間(SQLT_DATE
)が含まれていない場合)。
28.3.24 OCIDateTimeGetTimeZoneName()
日時のタイム・ゾーン名部分を取得します。
用途
日時のタイム・ゾーン名部分を取得します。
構文
sword OCIDateTimeGetTimeZoneName ( void *hndl, OCIError *err, const OCIDateTime *datetime, ub1 *buf, ub4 *buflen, );
パラメータ
コメント
この関数は、指定の日時値から時刻部分(時間、分、秒、小数秒)を取得します。
この関数は、指定の日時に時間情報が含まれていない場合はエラーを戻します。
戻り値
OCI_SUCCESS
、OCI_ERROR
(日時にタイム・ゾーン(SQLT_DATE
、SQLT_TIMESTAMP
)が含まれていない場合)。
28.3.25 OCIDateTimeGetTimeZoneOffset()
日時値のタイム・ゾーン(時間、分)部分を取得します。
用途
日時値のタイム・ゾーン(時間、分)部分を取得します。
構文
sword OCIDateTimeGetTimeZoneOffset ( void *hndl, OCIError *err, const OCIDateTime *datetime, sb1 *hour, sb1 *min, );
パラメータ
コメント
この関数は、指定の日時値からタイム・ゾーンの時間と分の部分を取得します。
この関数は、指定の日時に時間情報が含まれていない場合はエラーを戻します。
戻り値
OCI_SUCCESS
、OCI_ERROR
(日時にタイム・ゾーン(SQLT_DATE
、SQLT_TIMESTAMP
)が含まれていない場合)。
28.3.26 OCIDateTimeIntervalAdd()
時間隔を日時に加算して、結果の日時を生成します。
用途
時間隔を日時に加算して、結果の日時を生成します。
構文
sword OCIDateTimeIntervalAdd ( void *hndl, OCIError *err, OCIDateTime *datetime, OCIInterval *inter, OCIDateTime *outdatetime );
パラメータ
戻り値
OCI_SUCCESS
(関数が正常に完了した場合)、OCI_INVALID_HANDLE
(err
がNULL
ポインタの場合)、OCI_ERROR
(結果の日付が紀元前4713年1月1日より前、または9999年12月31日より後の場合)。
28.3.27 OCIDateTimeIntervalSub()
日時から時間隔を減算して、その結果を日時に格納します。
用途
日時から時間隔を減算して、その結果を日時に格納します。
構文
sword OCIDateTimeIntervalSub ( void *hndl, OCIError *err, OCIDateTime *datetime, OCIInterval *inter, OCIDateTime *outdatetime );
パラメータ
- hndl (IN)
-
ユーザー・セッション・ハンドルまたは環境ハンドルです。セッション・ハンドルが渡されると、セッションのデフォルト・カレンダで減算が行われます。時間隔は、セッション・カレンダ内であるとみなされます。
- err (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
をコールして診断情報を取得します。 - datetime (IN)
-
入力日時値へのポインタです。
- inter (IN)
-
入力時間隔へのポインタです。
- outdatetime (OUT)
-
出力日時へのポインタです。出力日時と入力日時の型は同じになります。
戻り値
OCI_SUCCESS
(関数が正常に完了した場合)、OCI_INVALID_HANDLE
(err
がNULL
ポインタの場合)、OCI_ERROR
(結果の日付が紀元前4713年1月1日より前、または9999年12月31日より後の場合)。
28.3.28 OCIDateTimeSubtract()
2つの日時を入力値にして、その差異を時間隔に格納します。
用途
2つの日時を入力値にして、その差異を時間隔に格納します。
構文
sword OCIDateTimeSubtract ( void *hndl, OCIError *err, OCIDateTime *indate1, OCIDateTime *indate2, OCIInterval *inter );
パラメータ
戻り値
OCI_SUCCESS
(関数が正常に完了した場合)、OCI_INVALID_HANDLE
(err
がNULL
ポインタの場合)、OCI_ERROR
(入力日時が比較可能な型でない場合)。
28.3.29 OCIDateTimeSysTimeStamp()
現行のシステム日付および時刻を、タイム・ゾーン付きタイムスタンプとして取得します。
用途
現行のシステム日付および時刻を、タイム・ゾーン付きタイムスタンプとして取得します。
構文
sword OCIDateTimeSysTimeStamp ( void *hndl, OCIError *err, OCIDateTime *sys_date );
パラメータ
戻り値
OCI_SUCCESS
、OCI_INVALID_HANDLE
(err
がNULL
ポインタの場合)。
関連トピック
28.3.30 OCIDateTimeToArray()
OCIDateTime
記述子を配列に変換します。
用途
OCIDateTime
記述子を配列に変換します。
構文
sword OCIDateTimeToArray ( void *hndl, OCIError *err, const OCIDateTime *datetime, const OCIInterval *reftz, ub1 *outarray, ub4 *len ub1 fsprec );
パラメータ
- hndl (IN)
-
OCIユーザー・セッション・ハンドルまたは環境ハンドルです。
- err (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
をコールして診断情報を取得します。 - datetime (IN)
-
OCIDateTime
記述子へのポインタです。 - reftz (IN)
-
SQL_TIMESTAMP_LTZ
型の変換時に参照として使用するOCIInterval
の記述子です。 - outarray(OUT)
-
日付が含まれるバイトの配列です。
- len (OUT)
-
outarray
の長さです。 - fsprec (IN)
-
配列の小数秒の精度です。
コメント
OCIによって配列が割り当てられ、その長さが戻されます。
戻り値
OCI_SUCCESS
、OCI_ERROR
(日時が無効な場合)。
28.3.31 OCIDateTimeToText()
指定された日付を指定の書式の文字列に変換します。
用途
指定された日付を指定の書式の文字列に変換します。
構文
sword OCIDateTimeToText ( void *hndl, OCIError *err, const OCIDateTime *date, const OraText *fmt, ub1 fmt_length, ub1 fsprec, const OraText *lang_name, size_t lang_length, ub4 *buf_size, OraText *buf );
パラメータ
- hndl (IN)
-
OCIユーザー・セッション・ハンドルまたは環境ハンドルです。ユーザー・セッション・ハンドルが渡されると、セッションの
NLS_LANGUAGE
およびセッションのNLS_CALENDAR
で変換が行われます。渡されない場合は、デフォルトが使用されます。 - err (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
をコールして診断情報を取得します。 - date (IN)
-
変換するOracle日時値です。
- fmt (IN)
-
変換書式です。
NULL
文字列ポインタ(text*)0
の場合、日付は、その型に対するデフォルトの書式で文字列に変換されます。 - fmt_length (IN)
-
fmt
パラメータの長さです。 - fsprec (IN)
-
戻される小数秒値の精度を指定します。
- lang_name (IN)
-
日および月の名前と略称が戻される際の言語を指定します。
lang_name
がNULL
(lang_name
=(OraText *)0
)の場合は、セッションのデフォルト言語が使用されます。 - lang_length (IN)
-
lang_name
パラメータの長さです。 - buf_size (IN/OUT)
-
(IN)は
buf
バッファのサイズです。(OUT)は変換結果の文字列のサイズです。
- buf (OUT)
-
変換された文字列が配置されるバッファです。
コメント
書式および多言語引数の詳細は、『Oracle Database SQL言語リファレンス』のTO_DATE
変換関数の説明を参照してください。変換されてNULL文字で終了する日付文字列は、buf
バッファに格納されます。
戻り値
OCI_SUCCESS
、OCI_INVALID_HANDLE
(err
がNULL
の場合)、OCI_ERROR
(次のいずれかの場合)。
-
バッファが小さすぎる場合。
-
無効な書式が使用されている場合。
-
不明な言語が使用されている場合。
-
オーバーフロー・エラーがある場合。
28.3.32 OCIDateToText()
日付型を文字列に変換します。
用途
日付型を文字列に変換します。
構文
sword OCIDateToText ( OCIError *err, const OCIDate *date, const OraText *fmt, ub1 fmt_length, const OraText *lang_name, ub4 lang_length, ub4 *buf_size, OraText *buf );
パラメータ
- err (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
をコールして診断情報を取得します。 - date (IN)
-
変換するOracle日付です。
- fmt (IN)
-
変換書式です。
NULL
、つまり(text *)0
の場合、日付はデフォルトの日付書式DD-MON-YYの文字列に変換されます。 - fmt_length (IN)
-
fmt
パラメータの長さです。 - lang_name (IN)
-
月および日の名前と略称が戻される際の言語を指定します。
lang_name
がNULL
((text *)0
)の場合は、セッションのデフォルト言語が使用されます。 - lang_length (IN)
-
lang_name
パラメータの長さです。 - buf_size (IN/OUT)
-
バッファのサイズです(IN)。このパラメータ(OUT)に、結果の文字列のサイズが戻されます。
- buf (OUT)
-
変換された文字列が配置されるバッファです。
コメント
指定された日付を指定の書式の文字列に変換します。変換されてNULL
で終了する日付文字列は、buf
に格納されます。
書式および多言語引数の詳細は、『Oracle Database SQL言語リファレンス』のTO_DATE
変換関数の説明を参照してください。
戻り値
この関数は、バッファが小さすぎる場合または無効な書式や認識できない言語が渡された場合はエラーを戻します。オーバーフローもエラーの原因となります。たとえば、値10を書式9に変換すると、エラーが発生します。
関連トピック
28.3.33 OCIDateZoneToZone()
あるタイム・ゾーンの日付を別のタイム・ゾーンの日付に変換します。
用途
あるタイム・ゾーンの日付を別のタイム・ゾーンの日付に変換します。
構文
sword OCIDateZoneToZone ( OCIError *err, const OCIDate *date1, const OraText *zon1, ub4 zon1_length, const OraText *zon2, ub4 zon2_length, OCIDate *date2 );
パラメータ
コメント
タイム・ゾーンzon1
の指定の日付date1
を、タイム・ゾーンzon2
の日付date2
に変換します。北米のタイム・ゾーンのみが対象です。
有効なゾーン文字列のリストは、『Oracle Database SQL言語リファレンス』のNEW_TIME
関数の説明を参照してください。有効なゾーン文字列の例を次に示します。
-
AST (大西洋標準時)
-
ADT (大西洋夏時間)
-
BST (ベーリング標準時)
-
BDT (ベーリング夏時間)
戻り値
この関数は、無効な日付またはタイム・ゾーンが渡された場合はエラーを戻します。
関連トピック
28.3.34 OCIIntervalAdd()
2つの時間隔を加算して、結果の時間隔を生成します。
用途
2つの時間隔を加算して、結果の時間隔を生成します。
構文
sword OCIIntervalAdd ( void *hndl, OCIError *err, OCIInterval *addend1, OCIInterval *addend2, OCIInterval *result );
パラメータ
戻り値
OCI_SUCCESS
、OCI_INVALID_HANDLE
(err
がNULL
ポインタの場合)、OCI_ERROR
(次のいずれかの場合)。
-
入力された2つの時間隔が相互に比較可能でない場合。
-
結果の年が
SB4MAXVAL
を超える場合。 -
結果の年が
SB4MINVAL
を下回る場合。
28.3.35 OCIIntervalAssign()
ある時間隔を別の時間隔にコピーします。
用途
ある時間隔を別の時間隔にコピーします。
構文
void OCIIntervalAssign ( void *hndl, OCIError *err, const OCIInterval *inpinter, OCIInterval *outinter );
パラメータ
戻り値
OCI_SUCCESS
、OCI_INVALID_HANDLE
(err
がNULL
ポインタの場合)。
28.3.36 OCIIntervalCheck()
時間隔の妥当性をチェックします。
用途
時間隔の妥当性をチェックします。
構文
sword OCIIntervalCheck ( void *hndl, OCIError *err, const OCIInterval *interval, ub4 *valid );
パラメータ
- hndl (IN)
-
OCIユーザー・セッション・ハンドルまたは環境ハンドルです。
- err (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
をコールして診断情報を取得します。 - interval (IN)
-
チェックする時間隔です。
- valid (OUT)
-
時間隔が有効な場合は0 (ゼロ)を戻します。それ以外の場合は、表28-9に指定されたコードの論理演算子ORによる組合せを戻します。
表28-9 OCIIntervalCheck()の有効なパラメータによって戻されるエラー・ビット
マクロ名 | ビット数 | エラー |
---|---|---|
|
0x1 |
無効な日 |
|
0x2 |
無効な日の、有効な日に対する大/小を示すビット(1=小)。 |
|
0x4 |
無効な月 |
|
0x8 |
無効な月の、有効な月に対する大/小を示すビット(1=小)。 |
|
0x10 |
無効な年 |
|
0x20 |
無効な年の、有効な年に対する大/小を示すビット(1=小)。 |
|
0x40 |
無効な時刻(時) |
|
0x80 |
無効な時刻(時)の、有効な時刻(時)に対する大/小を示すビット(1=小)。 |
|
0x100 |
無効な時刻(分) |
|
0x200 |
無効な時刻(分)の、有効な時刻(分)に対する大/小を示すビット(1=小)。 |
|
0x400 |
無効な時刻(秒) |
|
0x800 |
無効な時刻(秒)の、有効な時刻(秒)に対する大/小を示すビット(1=小)。 |
|
0x1000 |
無効な小数秒 |
|
0x2000 |
無効な時刻(小数秒)の、有効な時刻(小数秒)に対する大/小を示すビット(1=小) |
戻り値
OCI_SUCCESS
、OCI_INVALID_HANDLE
(err
がNULL
ポインタの場合)、OCI_ERROR
(エラーの場合)。
28.3.37 OCIIntervalCompare()
2つの時間隔を比較します。
用途
2つの時間隔を比較します。
構文
sword OCIIntervalCompare (void *hndl, OCIError *err, OCIInterval *inter1, OCIInterval *inter2, sword *result );
パラメータ
- hndl (IN)
-
OCIユーザー・セッション・ハンドルまたは環境ハンドルです。
- err (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
をコールして診断情報を取得します。 - inter1 (IN)
-
比較する時間隔です。
- inter2 (IN)
-
比較する時間隔です。
- result (OUT)
-
表28-10に指定したような比較結果です。
表28-10 OCIIntervalCompare()のresultパラメータによって戻される比較結果
比較結果 | resultパラメータの出力 |
---|---|
|
-1 |
|
0 |
|
1 |
戻り値
OCI_SUCCESS
、OCI_INVALID_HANDLE
(err
がNULL
ポインタの場合)、OCI_ERROR
(入力値が相互に比較可能でない場合)。
関連トピック
28.3.38 OCIIntervalDivide()
時間隔をOracle NUMBER
で除算して、時間隔を生成します。
用途
時間隔をOracle NUMBER
で除算して、時間隔を生成します。
構文
sword OCIIntervalDivide ( void *hndl, OCIError *err, OCIInterval *dividend, OCINumber *divisor, OCIInterval *result );
パラメータ
戻り値
OCI_SUCCESS
、OCI_INVALID_HANDLE
(err
がNULL
ポインタの場合)。
28.3.39 OCIIntervalFromNumber()
Oracle NUMBER
を時間隔に変換します。
用途
Oracle NUMBER
を時間隔に変換します。
構文
sword OCIIntervalFromNumber ( void *hndl, OCIError *err, OCIInterval *interval, OCINumber *number );
パラメータ
戻り値
OCI_SUCCESS
、OCI_INVALID_HANDLE
(err
がNULL
ポインタの場合)。
28.3.40 OCIIntervalFromText()
時間隔文字列が指定されている場合、その文字列で表現される時間隔を戻します。時間隔の型は、result
記述子の型です。
用途
時間隔文字列が指定されている場合、その文字列で表現される時間隔を戻します。時間隔の型は、result
記述子の型です。
構文
sword OCIIntervalFromText ( void *hndl, OCIError *err, const OraText *inpstring, size_t str_len, OCIInterval *result );
パラメータ
戻り値
OCI_SUCCESS
、OCI_INVALID_HANDLE
(err
がNULL
ポインタの場合)、OCI_ERROR
(次のいずれかの場合)。
-
リテラル文字列のフィールドが多すぎる場合。
-
年が範囲(–4713から9999)外の場合。
-
月が範囲(1から12)外の場合。
-
1か月の日が範囲(1から28...31)外の場合。
-
時間が範囲(0から23)外の場合。
-
時間が範囲(0から11)外の場合。
-
分が範囲(0から59)外の場合。
-
1分の秒が範囲(0から59)外の場合。
-
1日の秒が範囲(0から86399)外の場合。
-
時間隔が無効な場合。
関連トピック
28.3.41 OCIIntervalFromTZ()
OCIInterval
データ型のOCI_DTYPE_INTERVAL_DS
を、設定されているリージョンID (入力文字列にリージョンが指定されている場合)と現行の絶対オフセット、またはリージョンIDが0 (ゼロ)に設定されている絶対オフセットとともに戻します。
用途
OCIInterval
データ型のOCI_DTYPE_INTERVAL_DS
を、設定されているリージョンID (入力文字列にリージョンが指定されている場合)と現行の絶対オフセット、またはリージョンIDが0 (ゼロ)に設定されている絶対オフセットとともに戻します。
構文
sword OCIIntervalFromTZ ( void *hndl, OCIError *err, const oratext *inpstring, size_t str_len, OCIInterval *result ) ;
パラメータ
戻り値
OCI_SUCCESS
(成功した場合)、OCI_INVALID_HANDLE
(errがNULL
の場合)、OCI_ERROR
(無効な時間隔型、またはタイム・ゾーン・エラーがある場合)。
コメント
入力文字列は、[+/-]TZH:TZMまたは'TZR [TZD]'の形式であることが必要です。
28.3.42 OCIIntervalGetDaySecond()
時間隔から日、時、分、秒の値を取得します。
用途
時間隔から日、時、分、秒の値を取得します。
構文
sword OCIIntervalGetDaySecond (void *hndl, OCIError *err, sb4 *dy, sb4 *hr, sb4 *mm, sb4 *ss, sb4 *fsec, const OCIInterval *interval );
パラメータ
戻り値
OCI_SUCCESS
、OCI_INVALID_HANDLE
(err
がNULL
ポインタの場合)。
28.3.43 OCIIntervalGetYearMonth()
時間隔から年と月を取得します。
用途
時間隔から年と月を取得します。
構文
sword OCIIntervalGetYearMonth ( void *hndl, OCIError *err, sb4 *yr, sb4 *mnth, const OCIInterval *interval );
パラメータ
戻り値
OCI_SUCCESS
、OCI_INVALID_HANDLE
(err
がNULL
ポインタの場合)。
28.3.44 OCIIntervalMultiply()
時間隔をOracle NUMBER
で乗算して、時間隔を生成します。
用途
時間隔をOracle NUMBER
で乗算して、時間隔を生成します。
構文
sword OCIIntervalMultiply ( void *hndl, OCIError *err, const OCIInterval *inter, OCINumber *nfactor, OCIInterval *result );
パラメータ
戻り値
OCI_SUCCESS
、OCI_INVALID_HANDLE
(err
がNULL
ポインタの場合)、OCI_ERROR
(次のいずれかの場合)。
-
結果の年が
SB4MAXVAL
を超える場合。 -
結果の年が
SB4MINVAL
を下回る場合。
関連トピック
28.3.45 OCIIntervalSetDaySecond()
時間隔に日、時、分、秒を設定します。
用途
時間隔に日、時、分、秒を設定します。
構文
sword OCIIntervalSetDaySecond ( void *hndl, OCIError *err, sb4 dy, sb4 hr, sb4 mm, sb4 ss, sb4 fsec, OCIInterval *result );
パラメータ
戻り値
OCI_SUCCESS
、OCI_INVALID_HANDLE
(err
がNULL
ポインタの場合)。
28.3.46 OCIIntervalSetYearMonth()
時間隔に年と月を設定します。
用途
時間隔に年と月を設定します。
構文
sword OCIIntervalSetYearMonth ( void *hndl, OCIError *err, sb4 yr, sb4 mnth, OCIInterval *result );
パラメータ
戻り値
OCI_SUCCESS
、OCI_INVALID_HANDLE
(err
がNULL
ポインタの場合)、OCI_ERROR
(次のいずれかの場合)。
-
結果の年が
SB4MAXVAL
を超える場合。 -
結果の年が
SB4MINVAL
を下回る場合。
28.3.47 OCIIntervalSubtract()
2つの時間隔を減算し、その結果を時間隔に格納します。
用途
2つの時間隔を減算し、その結果を時間隔に格納します。
構文
sword OCIIntervalSubtract ( void *hndl, OCIError *err, OCIInterval *minuend, OCIInterval *subtrahend, OCIInterval *result );
パラメータ
戻り値
OCI_SUCCESS
、OCI_INVALID_HANDLE
(err
がNULL
ポインタの場合)、OCI_ERROR
(次のいずれかの場合)。
-
結果の年が
SB4MAXVAL
を超える場合。 -
結果の年が
SB4MINVAL
を下回る場合。 -
入力された2つの時間隔が相互に比較可能でない場合。
関連トピック
28.3.48 OCIIntervalToNumber()
時間隔をOracle NUMBER
に変換します。
用途
時間隔をOracle NUMBER
に変換します。
構文
sword OCIIntervalToNumber ( void *hndl, OCIError *err, OCIInterval *interval, OCINumber *number );
パラメータ
コメント
変換されたOracle NUMBER
には、日付の小数部分(たとえば、選択した単位が時間の場合は分と秒)が含まれます。精度を超える部分は切り捨てられます。
戻り値
OCI_SUCCESS
、OCI_INVALID_HANDLE
(err
がNULL
ポインタの場合)。
28.3.49 OCIIntervalToText()
時間隔が指定されている場合、その時間隔を表現する文字列を生成します。
用途
時間隔が指定されている場合、その時間隔を表現する文字列を生成します。
構文
sword OCIIntervalToText ( void *hndl, OCIError *err, const OCIInterval *interval, ub1 lfprec, ub1 fsprec, OraText *buffer, size_t buflen, size_t *resultlen );
パラメータ
- hndl (IN)
-
OCIユーザー・セッション・ハンドルまたは環境ハンドルです。
- err (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
をコールして診断情報を取得します。 - interval (IN)
-
変換する時間隔です。
- lfprec (IN)
-
先行フィールド精度を指定します。(先行フィールドを表すのに使用される桁数です)。
- fsprec (IN)
-
時間隔の小数秒精度(小数秒を表すのに使用される桁数)です。
- buffer (OUT)
-
結果を保持するバッファです。
- buflen (IN)
-
buffer
の長さです。 - resultlen (OUT)
-
buffer
に格納された結果の長さです。
コメント
時間隔リテラルは、INTERVAL YEAR TO MONTH
時間隔の'年'または'[年-]月'、およびINTERVAL
DAY
TO
SECOND
時間隔の'秒'、'分[:秒]'、'時間[:分[:秒]]'または'日[ 時間[:分[:秒]]]'として出力されます(大カッコで囲まれているフィールドはオプションです)。
戻り値
OCI_SUCCESS
、OCI_INVALID_HANDLE
(err
がNULL
ポインタの場合)、OCI_ERROR
(バッファ領域が不足しているため結果を保持できない場合)。