Oracle
 sql >> Base de données >  >> RDS >> Oracle

Fonction TO_TIMESTAMP_TZ() dans Oracle

Dans Oracle Database, le TO_TIMESTAMP_TZ() la fonction convertit son argument en une valeur de TIMESTAMP WITH TIME ZONE type de données.

Syntaxe

La syntaxe ressemble à ceci :

TO_TIMESTAMP_TZ(char [ DEFAULT return_value ON CONVERSION ERROR ]
  [, fmt [, 'nlsparam' ] ])

Le char l'argument peut être n'importe quelle expression qui correspond à une chaîne de caractères de CHAR , VARCHAR2 , NCHAR , ou NVARCHAR2 type de données.

Le fmt facultatif l'argument spécifie le format de char . Si vous omettez fmt , puis char doit être au format par défaut du TIMESTAMP WITH TIME ZONE type de données, qui est déterminé par le NLS_TIMESTAMP_TZ_FORMAT paramètre d'initialisation (voir Comment vérifier le format de date de votre session Oracle).

Le 'nlsparam' facultatif L'argument spécifie la langue dans laquelle les noms et abréviations des mois et des jours sont fournis. Il prend la forme suivante :

'NLS_DATE_LANGUAGE = language'

Exemple

Voici un exemple de base pour illustrer :

SELECT 
    TO_TIMESTAMP_TZ(
        '25-Aug-2030 18:10:35.123456789 +09:30', 
        'DD-Mon-RRRR HH24:MI:SS.FF TZH:TZM'
    )
FROM DUAL;

Résultat :

25/AUG/30 06:10:35.123456789 PM +09:30

Le format du résultat est déterminé par le NLS_TIMESTAMP_TZ_FORMAT de votre session paramètre. Nous pouvons vérifier la valeur du NLS_TIMESTAMP_TZ_FORMAT paramètre en interrogeant le V$NLS_PARAMETERS afficher :

SELECT VALUE
FROM V$NLS_PARAMETERS
WHERE PARAMETER = 'NLS_TIMESTAMP_TZ_FORMAT';

Résultat :

DD/MON/RR HH12:MI:SSXFF AM TZR

La valeur par défaut du NLS_TIMESTAMP_TZ_FORMAT le paramètre est dérivé du NLS_TERRITORY paramètre. Dans mon cas, le NLS_TERRITORY le paramètre est AUSTRALIA .

Voici ce qui se passe lorsque je modifie le NLS_TERRITORY paramètre vers un autre territoire, puis appelez TO_TIMESTAMP_TZ() encore :

ALTER SESSION SET NLS_TERRITORY = 'AMERICA';
SELECT 
    TO_TIMESTAMP_TZ(
        '25-Aug-2030 18:10:35.123456789 +09:30', 
        'DD-Mon-RRRR HH24:MI:SS.FF TZH:TZM'
    )
FROM DUAL;

Résultat :

25-AUG-30 06.10.35.123456789 PM +09:30

Cette fois, le résultat est renvoyé dans un format différent.

Vous pouvez également modifier la valeur du NLS_TIMESTAMP_TZ_FORMAT paramètre directement. Cela modifiera ce paramètre sans affecter les autres paramètres. Voir Comment changer le format de date dans votre session Oracle pour plus d'informations et d'exemples.

Format par défaut

Dans cet exemple, j'omets le fmt argument :

SELECT 
    TO_TIMESTAMP_TZ(
        '25-AUG-30 06.10.35.123456789 PM +09:30'
    )
FROM DUAL;

Résultat :

25-AUG-30 06.10.35.123456789 PM +09:30

Dans ce cas, l'argument doit être au format par défaut du TIMESTAMP WITH TIME ZONE type de données, qui est déterminé par le NLS_TIMESTAMP_TZ_FORMAT paramètre.

Voici un exemple de ce qui se passe lorsque nous passons une valeur qui n'est pas conforme à ce format :

SELECT 
    TO_TIMESTAMP_TZ(
        '25-Aug-2030 18:10:35.123456789 +09:30'
    )
FROM DUAL;

Résultat :

Error report -
ORA-01849: hour must be between 1 and 12

Dans ce cas, j'ai passé une valeur qui utilise l'heure de 24 heures, mais mon NLS_TIMESTAMP_TZ_FORMAT Le paramètre spécifie une horloge de 12 heures avec l'indicatif AM/PM.

Pour résoudre ce problème, je devrais soit modifier mon entrée, soit modifier la valeur du NLS_TIMESTAMP_TZ_FORMAT paramètre.

Fournir une valeur par défaut en cas d'erreur de conversion

Vous avez également la possibilité de fournir une valeur à renvoyer en cas d'erreur lors de la conversion de l'argument en un TIMESTAMP WITH TIME ZONE saisir.

Exemple :

SET NULL 'null';
SELECT 
    TO_TIMESTAMP_TZ(
    'Oops!'
    DEFAULT null ON CONVERSION ERROR
    )
FROM DUAL;

Résultat :

null

Dans ce cas, j'ai spécifié que null doit être renvoyé chaque fois qu'il y a une erreur de conversion. La valeur de retour peut être une expression ou une variable de liaison, et elle doit correspondre à une chaîne de caractères de CHAR , VARCHAR2 , NCHAR , ou NVARCHAR2 type de données, ou null . La fonction le convertit ensuite en TIMESTAMP WITH TIME ZONE . Si une erreur se produit lors de cette conversion, une erreur est renvoyée.

En ce qui concerne la première ligne de l'exemple ci-dessus, il s'agit simplement de spécifier ce qui doit être renvoyé à mon client chaque fois qu'un null valeur se produit. Par défaut, SQLcl et SQL*Plus renvoient un espace vide chaque fois que null se produit à la suite d'un SQL SELECT déclaration.

Cependant, vous pouvez utiliser SET NULL pour spécifier une autre chaîne à renvoyer. Ici, j'ai précisé que la chaîne null doit être retourné.

Le 'nlsparam' Argumentation

Le 'nlsparam' facultatif L'argument spécifie la langue dans laquelle les noms et abréviations des mois et des jours sont fournis. Il prend la forme suivante :

'NLS_DATE_LANGUAGE = language'

Exemple

SELECT 
    TO_TIMESTAMP_TZ(
        '25-agosto-2030 18:10:35.123456789 +02:00', 
        'DD-Month-RRRR HH24:MI:SS.FF TZH:TZM',
        'NLS_DATE_LANGUAGE = SPANISH'
    )
FROM DUAL;

Résultat :

25-AUG-30 06.10.35.123456789 PM +02:00

Notez que le résultat est toujours renvoyé en fonction du NLS_TIMESTAMP_TZ_FORMAT de la session en cours paramètre. C'est juste que l'entrée était dans une autre langue.

Voici ce qui se passe lorsque je change agosto au August tout en utilisant le même 'nlsparam' valeur :

SELECT 
    TO_TIMESTAMP_TZ(
        '25-August-2030 18:10:35.123456789 +02:00', 
        'DD-Month-RRRR HH24:MI:SS.FF TZH:TZM',
        'NLS_DATE_LANGUAGE = SPANISH'
    )
FROM DUAL;

Résultat :

Error report -
ORA-01843: not a valid month

Cela s'est produit parce que je n'ai pas fourni la date dans la langue spécifiée par le 'nlsparam' argument (espagnol).

Le changer en English résout ce problème :

SELECT 
    TO_TIMESTAMP_TZ(
        '25-August-2030 18:10:35.123456789 +02:00', 
        'DD-Month-RRRR HH24:MI:SS.FF TZH:TZM',
        'NLS_DATE_LANGUAGE = English'
    )
FROM DUAL;

Résultat :

25-AUG-30 06.10.35.123456789 PM +02:00

Voir Comment renvoyer une liste des langues prises en charge dans Oracle si cela vous aide.

Arguments nuls

Passer null donne null :

SET NULL 'null';
SELECT 
    TO_TIMESTAMP_TZ(null)
FROM DUAL;

Résultat :

null

Nombre d'arguments non valides

L'appel de la fonction sans passer d'arguments entraîne une erreur :

SELECT TO_TIMESTAMP_TZ()
FROM DUAL;

Résultat :

Error report -
SQL Error: ORA-00938: not enough arguments for function
00938. 00000 -  "not enough arguments for function"

Cependant, passer trop d'arguments ne semble pas poser de problème, tant que les trois premiers sont valides :

SELECT 
    TO_TIMESTAMP_TZ(
        '25-Aug-2030 18:10:35.123456789 +09:30', 
        'DD-Mon-RRRR HH24:MI:SS.FF TZH:TZM',
        'NLS_DATE_LANGUAGE = English',
        'Oops!',
        'Dang!',
        'Homer',
        'Symptom'
    )
FROM DUAL;

Résultat :

25-AUG-30 06.10.35.123456789 PM +09:30