# Working With Dates

## Working with Dates (and Timezones)

First of all the constructor:

```javascript
new Date()
```

…will make the same date no matter what timezone you are in.

So if you do `new Date()` in The Netherlands and at the same time somebody else does `new Date()` in USA, then that is the exact same date. Both represent the time in milliseconds after 1970 in UTC. This is called **Unix Time**.

The only thing that makes it look different is when you print or format it. The `toString()` of a date already formats it, so it shows the date and timezone you are currently in. But this does **not** mean that Dates have a timezone — that is not correct.

***

### Constructors

```javascript
new Date(year, month[, day[, hour[, minutes[, seconds[, milliseconds]]]]]);
```

Those arguments are then in your timezone. Just like formatting a string with `"yyyy/MM/dd HH:mm"` using your timezone in the formatter.

There is also:

```javascript
Date.UTC(year, month, date, hrs, min, sec, ms)
```

This function returns the milliseconds in UTC (you can wrap this in `new Date(number)`). So if you pass `hrs = 10` and you are in `+2`, then the date in your timezone will be 12.

***

### Local vs Server Time in Servoy

In Servoy the problem arises when you call methods like `Date#getHours()` because they use **local time**.

* The server could be in timezone `+2`
* The client could be in timezone `+3`
* Servoy code runs on the server, so `getHours()` will reflect the server's timezone (same as `toString()`).

***

#### Example: Local or UTC Time with `getHours()`

```javascript
var date1 = new Date(2019,10,1,12);
var date2 = new Date(Date.UTC(2019,10,1,12));

application.output(date1);
application.output(date2);
application.output(date1.getHours());
application.output(date2.getHours());
```

Output:

* `date1` prints `12` in both cases (constructed for local time).
* If you are in `+1`, then `date2` prints `13` because UTC 12 is 13 in Amsterdam.

⚠️ But this is always based on the server timezone, not the client (which may be different again).

***

### Getting the Client's Hours (NGClient and SmartClient)

You can use:

```javascript
application.output(utils.dateFormat(date1, "HH"));
```

This uses the client's timezone (from the browser).

Example:

* Server in `+1`
* NGClient in `+2`
* The code prints `13`, since `12:00` in the server's timezone is `13:00` in the client's.

***

### Use as LocalDateTime

In NGClient, the **Use as LocalDateTime** option (date format dialog) controls how dates are sent.

* **Default (unchecked):**\
  Sent as ISO-8601 with timezone, e.g.\
  `2019-11-01T12:00:00+01:00` (server in +1).\
  Client in `+2` shows it as `2019-11-01 13:00`.\
  (Milliseconds don't change — purely formatting.)
* **Checked (Use as LocalDateTime):**\
  Sent without timezone, e.g.\
  `2019-11-01T12:00:00`\
  Client assumes it's in its timezone and shows `2019-11-01 12:00`.

⚠️ Problem: now the milliseconds **do** change, since the date was shifted by the difference between server and client timezone.

***

### `application.getTimeStamp()`

If you are using **Use as LocalDateTime**, you may need a date that represents "now" on the client.

* `new Date()` on the server (timezone `+1`) could give `2019-11-28 23:00`.
* `application.getTimeStamp()` in the client (timezone `+2`) would give `2019-11-29 00:00`.

This ensures the date matches the client's actual local "now."

***

### Searching Between Dates

When searching (e.g. "everything from yesterday"), you need dates relative to the **client's** timezone.

Example in `+2`:

```javascript
var startDate = utils.parseDate("2019-11-28 00:00", "yyyy-MM-dd HH:mm", null);
var endDate   = utils.parseDate("2019-11-28 23:59", "yyyy-MM-dd HH:mm", null);
```

* The `null` argument (new in Servoy 2019.12) tells it to use the client's timezone.
* If you omit it, the server timezone is used.

Server in `+1`, client in `+2` would produce:

```
Wed Nov 27 23:00:00 CET 2019
Thu Nov 28 22:59:00 CET 2019
```

If sent back to the client (with *Use as LocalDateTime = false*), the browser adds back the difference (1 hour), so the date correctly represents the client's "yesterday."


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.servoy.com/guides/develop/programming-guide/working-with-data/working-with-dates.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.