Funções de Data e Hora
Introdução
Se você estiver usando essas funções em conjunto com o Now
ou Now_
funções, esteja ciente de que o fuso horário retornado é aquele configurado na máquina que executa o agente. Todos os Agentes em Nuvem estão em UTC. Os Agentes Privados variam de acordo com a máquina específica em que cada agente está sendo executado. Se você estiver usando uma função de conversão, leve isso em consideração se o seu projeto for projetado para rodar tanto na nuvem quanto em um Agente Privado.
Nota
Se você tiver a configuração Substituir fuso horário do Agente ativada nas políticas da sua organização, quaisquer scripts que usem funções de data e hora conforme descrito aqui não serão substituídos pelo fuso horário selecionado.
Códigos de Fuso Horário
Os parâmetros de fuso horário são um dos códigos de fuso horário padrão, seja um nome completo (código TZ), como "America/Los_Angeles"
, um deslocamento UTC como "UTC-8:00"
, ou uma abreviatura como "PST" (código de três letras). Os códigos de fuso horário diferenciam maiúsculas de minúsculas. Códigos TZ de nome completo são recomendados, se um fuso horário estiver sendo usado, pois "AST" pode se referir ao horário padrão "Atlântico" ou "Árabe".
- Os códigos TZ (uma lista não oficial) podem ser encontrados em https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.
- Os códigos de três letras estão listados em https://en.wikipedia.org/wiki/List_of_time_zone_abbreviations. Eles estão obsoletos pela IANA, embora atualmente suportado.
- Informações adicionais podem ser encontradas em https://www.iana.org/time-zones.
Convertendo UNIX Times em Datas
Se um horário UNIX for um número que inclui precisão de milissegundos, você poderá usar um código semelhante a este para converter um horário UNIX em uma data:
// If you have a UNIX timestamp with milliseconds such as
createdate = "1478119530707";
// You can convert it to a date by
// truncating the last three digits and using FormatDate:
date = double(Left(createdate, 10));
FormatDate(date, "yyyy-mm-dd");
ConvertTimeZone
Declaração
string ConvertTimeZone(date d, string fromTZ, string toTZ[, bool is_european_format, bool ignoreDST])
string ConvertTimeZone(string d, string fromTZ, string toTZ[, bool is_european_format, bool ignoreDST])
Sintaxe
ConvertTimeZone(<d>, <fromTZ>, <toTZ>[, <is_european_format>, <ignoreDST>])
Parâmetros Obrigatórios
date
: Uma data, como objeto de data ou como string de datafromTZ
: O fuso horário a ser convertido, expresso como código de fuso horáriotoTZ
: O fuso horário para o qual será convertido, expresso como código de fuso horário
Parâmetros Opcionais
-
is_european_format
: Este sinalizador opcional determina se o formato de data europeu deve ser usado. Quandotrue
, o formato é dia e depois mês; quandofalse
, o formato é mês e depois dia. -
ignoreDST
: Por padrão, o horário de verão é contabilizado na conversão entre os quatro principais fusos horários dos EUA. Defina este sinalizador opcional comotrue
para substituir esta ação.
Descrição
Pegue uma data e retorne-a convertida de um fuso horário para outro fuso horário.
Nota
Se você estiver usando ConvertTimeZone
em conjunção com Now
ou Now_
, esteja ciente de que o fuso horário retornado é aquele configurado na máquina que executa o agente. Todos os Agentes em Nuvem estão em UTC. Os Agentes Privados variam de acordo com a máquina específica em que cada agente está sendo executado. Se você estiver usando uma função de conversão, como ConvertTimeZone
, leve isso em consideração se o seu projeto for projetado para ser executado tanto na nuvem quanto em um Agente Privado.
Exemplos
ConvertTimeZone(Now(), "UTC", "America/Los_Angeles", false, false);
// If Now() returns "2017-03-10 18:34:37"
// returns "2017-03-10 10:34:37"
ConvertTimeZone("02/06/2017 5:25:00", "America/Los_Angeles", "America/New_York");
// Returns "2017-02-06 08:25:00" (shifts the time by 3 hours)
CVTDate
Declaração
string CVTDate(date d, string inputFormat, string outputFormat)
string CVTDate(string d, string inputFormat, string outputFormat)
Sintaxe
CVTDate(<d>, <inputFormat>, <outputFormat>)
Parâmetros Obrigatórios
d
: Um objeto de data ou string de datainputFormat
: Uma string de formato, especificando o formato da data de entradaoutputFormat
: Uma string de formato, especificando o formato da data de saída
Descrição
Converte um objeto de data ou sequência de data no formato de entrada em uma sequência de data no formato de saída.
Nota
Se você estiver usando CVTDate
em conjunção com Now
ou Now_
, esteja ciente de que o fuso horário retornado é aquele configurado na máquina que executa o agente. Todos os Agentes em Nuvem estão em UTC. Os Agentes Privados variam de acordo com a máquina específica em que cada agente está sendo executado. Se você estiver usando uma função de conversão, como CVTDate
, leve isso em consideração se o seu projeto for projetado para ser executado tanto na nuvem quanto em um Agente Privado.
Exemplos
Nestes exemplos, presume-se que todos os agentes estão em execução na nuvem e os horários retornados seriam UTC. "myDate"
é a data 19 de junho de 1994.
Fórmula | Entrada | Saída |
---|---|---|
CVTDate(myDate, "mmddyy", "yyyymmdd") | 061994 | 19940619 |
CVTDate(myDate, "mmddyy", "ShortDate") | 061994 | 6/19/94 |
CVTDate(myDate, "mmddyy", "LongDate") | 061994 | Sunday, June 19, 1994 |
CVTDate(Now(), "GeneralDate","dd-mmm-yy, HH:MM AP") | em 31/01/17 às 12h39 no MST | 31-Jan-17, 07:39 PM |
CVTDate(Now(), "GeneralDate","dd-mmm-yy, HH:MM.SS AP") | em 31/01/17 às 12h39min13s no MST | 31-Jan-17, 07:39:13 PM |
CVTDate(Now_(), "GeneralDate","ddmmmyyyy, HH:MM:SS.zzz AP") | em 31/01/17 às 12h39min13h310s no MST | 31Jan2017, 07:39:13.310 PM |
CVTDate(Now(), "GeneralDate","yyyy_mm_dd_HH_MM") | em 31/01/17 às 12h39min13h310s no MST | 2017_01_31_19_39_13 |
CVTDate(myDate, "mmddyy", "%Y%m%d%a") | 061994 | 19940619Sun |
CVTDate(myDate, "mmddyy", "%Y %m %d %a") | 061994 | 1994 06 19 Sun |
CVTDate(myDate, "mmddyy", "%Y %m %d %A") | 061994 | 1994 06 19 Sunday |
formato de Strings
O formato da sequência de data de entrada e da sequência de data de saída é especificado da mesma maneira usando caracteres para espaços reservados ou um dos quatro formatos de data predefinidos (GeneralDate, LongDate, MediumDate,
ou ShortDate
).
Para entradas, o ano, mês, dia, hora, minuto, segundo e AM/PM são lidos na sequência de data na posição onde y, m, d, H, M, S, SSS,
e AP
aparecem na string de formato de entrada.
Para saídas, a sequência de formato é copiada para a sequência de dados com o ano, mês, dia, hora, minuto e segundo substituindo os caracteres de y, m, d, H, M, S, SSS
, e AP
.
Alternativamente, as substituições usadas no método ANSI C strftime
pode ser usado. Por exemplo, a cadeia "%Y-%m-%d"
resultaria no formato de data ISO 8601 (yyyy-mm-dd
). Consulte a documentação externa em strftime
para obter uma descrição detalhada.
Esses códigos podem aparecer conforme necessário na string de formato para especificar como ler a entrada ou gravar a saída:
Formato | Entrada ou Saída |
---|---|
yyyy | Ano com 4 dígitos |
yy | (último) ano com 2 dígitos |
??yy | Ano com 2 ou 4 dígitos |
mmm | Janeiro, fevereiro, março, abril, maio, junho, julho, agosto, setembro, outubro, novembro, dezembro |
mm | Mês com 2 dígitos (01-12) |
?m | Mês com 1 ou 2 dígitos (1-12) |
ddd | Data juliana (001-366) |
dd | Dia de 2 dígitos (01-31) |
?d | Dia com 1 ou 2 dígitos (1-31) |
HH | Hora (00-23) ou (01-12) se AM/PM for especificado usando AP |
MM | Minuto (00-59) |
SS | Segundo (00-59) |
zzz | Milissegundo (0,001-0,999) |
AP | AM ou PM |
GeneralDate | 19/06/94 17:34:23 |
LongDate | Domingo, 19 de junho de 1994 |
MediumDate | 19 de junho de 1994 |
ShortDate | 19/06/94 |
DateAdd
Declaração
string DateAdd(string datePart, int number, date d)
string DateAdd(string datePart, int number, string d)
Sintaxe
DateAdd(<datePart>, <number>, <d>)
Parâmetros Obrigatórios
datePart
: Um código de parte que descreve a parte da data à qual aplicar a adiçãonumber
: Um número inteiro a ser adicionado à parte da datad
: O objeto de data ou uma string de data a ser operada
Descrição
Retorna uma string de data após adicionar um número a uma parte especificada de um objeto de data.
Estes códigos são usados para descrever as partes da data:
Parte da data | Código da peça |
---|---|
Ano | yyyy ou yy |
Mês | mm ou m |
Semana | ww ou wk |
Dia | dd |
Hora | hh |
Minuto | mi ou n |
Segundo | ss ou s |
Cuidado
Quando usado com versões de agente 10.83 / 11.21 ou anteriores, o DateAdd
função retorna o valor errado ao fornecer a parte da data do mês (mm
ou m
) e um número inteiro negativo que é um múltiplo de 12
(12
, 24
, 36
, etc.). Isso faz com que o ano da data retornada seja reduzido incorretamente em um ano adicional.
Exemplos
DateAdd("yyyy", 1, Now());
// Adding one year to a date
// If Now() returns 2017-03-10 18:46:41
// returns "2018-03-10 18:46:41"
DateAdd("dd", 1, "2017-03-10");
// Adding one day to a date
// Returns "2017-03-11"
DayOfMonth
Declaração
int DayOfMonth(date d)
int DayOfMonth(string d)
Sintaxe
DayOfMonth(<d>)
Parâmetros Obrigatórios
d
: Um objeto de data ou string de data
Descrição
Retorna o dia do mês (1-31) de um objeto de data ou sequência de data.
Exemplos
DayOfMonth(Now());
// Returns 25 if today is December 25
DayOfWeek
Declaração
int DayOfWeek(date d)
int DayOfWeek(string d)
Sintaxe
DayOfWeek(<d>)
Parâmetros Obrigatórios
d
: Um objeto de data ou string de data
Descrição
Retorna o dia da semana para um objeto de data ou sequência de data, com 0 para domingo, 1 para segunda-feira e 6 para sábado.
Esta definição é independente da localidade. Para saber o nome do dia da semana, ligue FormatDate
em vez de.
Exemplos
DayOfWeek(Now());
// Returns 0, if today is Sunday
Now() + (6 - DayOfWeek(Now()))*24*60*60;
// Returns the date object of the last day of the current week,
// assuming Saturday (day 6) is the last day of the week
FormatDate
Declaração
string FormatDate(date d, string format)
string FormatDate(string d, string format)
Sintaxe
FormatDate(<d>, <format>)
Parâmetros Obrigatórios
d
: Um objeto de data ou string de dataformat
: Uma string de formato, especificando o formato da data de saída
Descrição
Converte um objeto de data em uma string de acordo com um format string. Isto é semelhante ao CVTDate
função e usa as mesmas strings de formato.
Exemplos
FormatDate(Now(),"%w");
// Similar to DayOfWeek(Now()), except the return value
// is a string value of today's weekday name, such as "Wed"
FormatDate("2017-12-07","%A");
// Returns the weekday name of the date string, such as "Thursday"
LPadChar(String(Long(FormatDate(d, "yyyy")) - 1900), "0", 3) + FormatDate(d, "ddd");
// Returns, for a date d, a string formatted as a JD Edwards Date ("CYYDDD")
// If d = "2000-12-31" (a leap year), returns "100366"
// See https://docs.oracle.com/cd/E26228_01/doc.93/e21961/julian_date_conv.htm#WEAWX259
GeneralDate
Declaração
string GeneralDate(date d)
string GeneralDate(string d)
Sintaxe
GeneralDate(<d>)
Parâmetros Obrigatórios
d
: Um objeto de data ou string de data
Descrição
Retorna uma string no formato geral de data para um objeto de data ou string de data.
Exemplos
GeneralDate(Now());
// If Now() is 11:59:23 am on September 16, 2000,
// returns "09/16/2000 11:59:23 AM"
GeneralDate("2017-12-07");
// Returns "12/07/2017 12:00:00 AM"
GetUTCFormattedDate
Declaração
string GetUTCFormattedDate(date d, string time_zone_id[, bool is_european_format])
string GetUTCFormattedDate(string d, string time_zone_id[, bool is_european_format])
Sintaxe
GetUTCFormattedDate(<d>, <time_zone_id>[, <is_european_format>])
Parâmetros Obrigatórios
d
: Um objeto de data ou string de datatime_zone_id
: O fuso horário a ser convertido, expresso como código de fuso horário
Parâmetros Opcionais
is_european_format
: Este sinalizador opcional determina se o formato de data europeu deve ser usado. Quando verdadeiro, o formato é dia e depois mês; quando falso, o formato é mês e depois dia.
Descrição
Retorna uma string de data sem informações de hora. Converte um objeto de data ou sequência de data em uma sequência de acordo com um código de fuso horário.
Aviso
Se passar uma data com hora, o GetUTCFormattedDate()
função trunca o tempo antes de converter para UTC. Isso significa que os carimbos de data e hora posteriores à meia-noite UTC serão retornados como ocorridos na data anterior, conforme mostrado no exemplo acima para o "America/Los_Angeles"
fuso horário.
Nota
Se você estiver usando GetUTCFormattedDate
em conjunção com Now
ou Now_
, esteja ciente de que o fuso horário retornado é aquele configurado na máquina que executa o agente. Todos os Agentes em Nuvem estão em UTC. Os Agentes Privados variam de acordo com a máquina específica em que cada agente está sendo executado. Se você estiver usando uma função de conversão, como GetUTCFormattedDate
, leve isso em consideração se o seu projeto for projetado para ser executado tanto na nuvem quanto em um Agente Privado.
Exemplos
// If Now() is 2017-12-09 18:46:41, then:
GetUTCFormattedDate(Now(), "UTC", false);
// Returns "2017-12-09"
GetUTCFormattedDate(Now(), "America/Los_Angeles", false);
// Returns "2017-12-09"
GetUTCFormattedDateTime
Declaração
string GetUTCFormattedDateTime(date d, string time_zone_id[, bool is_european_format])
string GetUTCFormattedDateTime(string d, string time_zone_id[, bool is_european_format])
Sintaxe
GetUTCFormattedDateTime(<d>, <time_zone_id>[, <is_european_format>])
Parâmetros Obrigatórios
d
: Um objeto de data ou string de datatime_zone_id
: O fuso horário a ser convertido, expresso como código de fuso horário
Parâmetros Opcionais
is_european_format
: Este sinalizador opcional determina se o formato de data europeu deve ser usado. Quando verdadeiro, o formato é dia e depois mês; quando falso, o formato é mês e depois dia.
Descrição
Retorna uma string de data com informações de hora. Converte um objeto de data ou sequência de data em uma sequência de acordo com um código de fuso horário.
Nota
Se você estiver usando GetUTCFormattedDateTime
em conjunção com Now
ou Now_
, esteja ciente de que o fuso horário retornado é aquele configurado na máquina que executa o agente. Todos os Agentes em Nuvem estão em UTC. Os Agentes Privados variam de acordo com a máquina específica em que cada agente está sendo executado. Se você estiver usando uma função de conversão, como GetUTCFormattedDateTime
, leve isso em consideração se o seu projeto for projetado para ser executado tanto na nuvem quanto em um Agente Privado.
Exemplos
// If Now() is 2017-12-09 18:46:21, then:
GetUTCFormattedDateTime(Now(), "UTC", false);
// Returns "2017-12-09T18:46:21Z"
GetUTCFormattedDateTime(Now(), "America/Los_Angeles", false);
// Returns "2017-12-10T02:46:21Z"
LastDayOfMonth
Declaração
date LastDayOfMonth(date d)
date LastDayOfMonth(string d)
Sintaxe
LastDayOfMonth(<d>)
Parâmetros Obrigatórios
d
: Um objeto de data ou string de data
Descrição
Retorna um objeto de data que representa o último dia do mês para um objeto de data ou sequência de data.
Exemplos
LastDayOfMonth(Now());
// If today is in February of a leap year,
// returns the date object of February 29
LongDate
Declaração
string LongDate(date d)
string LongDate(string d)
Sintaxe
LongDate(<d>)
Parâmetros Obrigatórios
d
: Um objeto de data ou string de data
Descrição
Retorna uma string no formato de data longa para um objeto de data ou string de data.
Exemplos
LongDate(Now());
// If Now() is 11:59:23 am on September 16, 2000,
// returns "Saturday, September 16, 2000"
LongTime
Declaração
string LongTime(date d)
string LongTime(string d)
Sintaxe
LongTime(<d>)
Parâmetros Obrigatórios
d
: Um objeto de data ou string de data
Descrição
Retorna uma string no formato longo para um objeto de data ou string de data.
Exemplos
LongTime(Now());
// If Now() is 11:59:23 am on September 16, 2000
// returns "11:59:23 AM"
MediumDate
Declaração
string MediumDate(date d)
string MediumDate(string d)
Sintaxe
MediumDate(<d>)
Parâmetros Obrigatórios
d
: Um objeto de data ou string de data
Descrição
Retorna uma string no formato de data médio para um objeto de data ou string de data.
Exemplos
MediumDate(Now());
// If Now() is 11:59:23 am on September 16, 2000
// returns "16-Sep-00"
MediumTime
Declaração
string MediumTime(date d)
string MediumTime(string d)
Sintaxe
MediumTime(<d>)
Parâmetros Obrigatórios
d
: Um objeto de data ou string de data
Descrição
Retorna uma string no formato de hora média para um objeto de data ou string de data.
Exemplos
MediumTime(Now());
// If Now() is 11:59:23 am on September 16, 2000
// returns "11:59 AM"
MonthOfYear
Declaração
int MonthOfYear(date d)
int MonthOfYear(string d)
Sintaxe
MonthOfYear(<d>)
Parâmetros Obrigatórios
d
: Um objeto de data ou string de data
Descrição
Retorna o mês (1-12) para um objeto de data ou sequência de data.
Exemplos
MonthOfYear(Now());
// If Now() is 11:59:23 am on September 16, 2000
// returns "9"
Now
Declaração
date Now()
Sintaxe
Now()
Descrição
Retorna um objeto de data que representa os valores de data e hora no momento em que a função foi executada. A fração de segundo é truncada.
Nota
Esteja ciente de que o fuso horário da data retornada é aquele configurado na máquina que executa o agente. Todos os Agentes em Nuvem estão em UTC. Os Agentes Privados variam de acordo com a máquina específica em que cada agente está sendo executado. Se você estiver usando funções de conversão, leve isso em consideração se o seu projeto for projetado para rodar tanto na nuvem quanto em um Agente Privado.
Exemplos
Now();
// If Now() is 11:59:23 am on September 16, 2000,
// returns a date object representing 09/16/2000 11:59:23 AM
Now_
Declaração
date Now_()
Sintaxe
Now_()
Descrição
Retorna um objeto de data que representa os valores de data e hora no momento em que a função foi executada. O valor de tempo inclui a fração de segundo (milissegundos).
Nota
Esteja ciente de que o fuso horário da data retornada é aquele configurado na máquina que executa o agente. Todos os Agentes em Nuvem estão em UTC. Os Agentes Privados variam de acordo com a máquina específica em que cada agente está sendo executado. Se você estiver usando funções de conversão, leve isso em consideração se o seu projeto for projetado para rodar tanto na nuvem quanto em um Agente Privado.
Exemplos
Now_();
// If Now_() is 11:59:23.123 am on September 16, 2000
// returns a date object representing 09/16/2000 11:59:23.123 AM
ShortDate
Declaração
string ShortDate(date d)
string ShortDate(string d)
Sintaxe
ShortDate(<d>)
Parâmetros Obrigatórios
d
: Um objeto de data ou string de data
Descrição
Retorna uma string no formato de data abreviada para um objeto de data ou string de data.
Exemplos
ShortDate(Now());
// If Now() is 11:59:23 am on September 16, 2017
// returns "9/16/17"
ShortTime
Declaração
string ShortTime(date d)
string ShortTime(string d)
Sintaxe
ShortTime(<d>)
Parâmetros Obrigatórios
d
: Um objeto de data ou string de data
Descrição
Retorna uma string no formato de hora abreviada para um objeto de data ou string de data.
Exemplos
ShortTime(Now());
// If Now() is 11:59:23 am on September 16, 2017
// returns "11:59"