Retrieve Time Zone Description (QWCRTVTZ) API
Required Parameter Group:
1 | Receiver variable | Output | Char(*) |
2 | Length of receiver variable | Input | Binary(4) |
3 | Format name | Input | Char(8) |
4 | Time zone description | Input | Char(10) |
5 | Error Code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve Time Zone Description (QWCRTVTZ) API retrieves information about one or more time zone descriptions. A time zone description contains information that is used to calculate a local time.
Authorities and Locks
- Time Zone Description Authority
- *USE
- Message File Authority
- *USE is required to retrieve the abbreviated and full names
if a message is specified in the time zone description.
- QSYS Library Authority
- *USE
- Message File Library Authority
- *EXECUTE is required to retrieve the abbreviated and full names
if a message is specified in the time zone description.
- Time Zone Description Lock
- *SHRNUP
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The variable to receive the information about the time zone descriptions.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable. The length must be at least 8 bytes.
- Format name
- INPUT; CHAR(8)
The format of the time zone description information. The possible format name is:
RTMZ0100 | Returns the properties of the time zone description. See Format RTMZ0100 for details on the time zone description information returned. |
RTMZ0200 | Returns the TZ string derived from the time zone description properties that are associated with the current date and time of the job. See Format RTMZ0200 for details on the time zone description information returned. |
- Time zone description
- INPUT; CHAR(10)
The name of the time zone description for which information is to be retrieved. This name can be a simple object name, a generic name or the following special value:
*ALL | Retrieve information for all time zone descriptions. |
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format RTMZ0100
The RTMZ0100 format returns the following information for the specified time zone description.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | BINARY(4) | Bytes returned |
4 | 4 | BINARY(4) | Bytes available |
8 | 8 | BINARY(4) | Number of time zone descriptions available |
12 | C | BINARY(4) | Offset to time zone descriptions |
16 | 10 | BINARY(4) | Number of time zone descriptions returned |
20 | 14 | BINARY(4) | Length of a time zone description entry |
24 | 18 | CHAR(*) | Reserved |
These fields repeat, in the order listed, for the number of time zone descriptions returned. | CHAR(10) | Time zone description name | |
CHAR(1) | Local system time indicator | ||
CHAR(1) | Daylight Saving Time indicator | ||
BINARY(4) | Offset from UTC | ||
CHAR(10) | Standard Time abbreviated name | ||
CHAR(50) | Standard Time full name | ||
CHAR(10) | Daylight Saving Time abbreviated name | ||
CHAR(50) | Daylight Saving Time full name | ||
CHAR(7) | Standard Time message | ||
CHAR(7) | Daylight Saving Time message | ||
CHAR(10) | Message file name | ||
CHAR(10) | Message file library name | ||
CHAR(2) | Daylight Saving Time start - month | ||
CHAR(1) | Daylight Saving Time start - day | ||
CHAR(1) | Daylight Saving Time start - relative day of month | ||
CHAR(6) | Daylight Saving Time start - time | ||
CHAR(2) | Daylight Saving Time end - month | ||
CHAR(1) | Daylight Saving Time end - day | ||
CHAR(1) | Daylight Saving Time end - relative day of month | ||
CHAR(6) | Daylight Saving Time end - time | ||
CHAR(50) | Text description | ||
BINARY(4) | Daylight Saving Time shift | ||
BINARY(4) | Year offset | ||
CHAR(128) | Alternate name | ||
CHAR(*) | Reserved |
Format RTMZ0200
The RTMZ0200 format returns the following information for the specified time zone description.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | BINARY(4) | Bytes returned |
4 | 4 | BINARY(4) | Bytes available |
8 | 8 | BINARY(4) | Number of time zone descriptions available |
12 | C | BINARY(4) | Offset to time zone descriptions |
16 | 10 | BINARY(4) | Number of time zone descriptions returned |
20 | 14 | CHAR(*) | Reserved |
These fields repeat, in the order listed, for the number of time zone descriptions returned. | BINARY(4) | Length of this time zone description entry | |
BINARY(4) | Displacement to TZ string | ||
BINARY(4) | Length of TZ string | ||
CHAR(10) | Time zone description name | ||
CHAR(*) | Reserved | ||
CHAR(*) | TZ string |
Field Descriptions
Alternate name. The descriptive name that provides additional information about the time zone description. If the time zone description does not have an alternate name, this field is blank.
Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.
Bytes returned. The number of bytes of data returned.
Daylight Saving Time abbreviated name. The abbreviated name used with the time zone when Daylight Saving Time is being observed. If the time zone description does not support Daylight Saving Time, this field is blank. If the time zone description uses a message to specify the abbreviated name and the message cannot be retrieved, this field returns *N. This can occur when the caller of the API is not authorized to the message file or its library, the message file cannot be found or the message does not exist in the specified message file.
Daylight Saving Time end - day. The day of the week on which Daylight Saving Time ends. The possible values are:
blank | This time zone description does not support Daylight Saving Time. |
1 | Daylight Saving Time ends on a Monday. |
2 | Daylight Saving Time ends on a Tuesday. |
3 | Daylight Saving Time ends on a Wednesday. |
4 | Daylight Saving Time ends on a Thursday. |
5 | Daylight Saving Time ends on a Friday. |
6 | Daylight Saving Time ends on a Saturday. |
7 | Daylight Saving Time ends on a Sunday. |
Daylight Saving Time end - month. The month in which Daylight Saving Time ends. The possible values are:
blank | This time zone description does not support Daylight Saving Time. |
01 | Daylight Saving Time ends in January. |
02 | Daylight Saving Time ends in February. |
03 | Daylight Saving Time ends in March. |
04 | Daylight Saving Time ends in April. |
05 | Daylight Saving Time ends in May. |
06 | Daylight Saving Time ends in June. |
07 | Daylight Saving Time ends in July. |
08 | Daylight Saving Time ends in August. |
09 | Daylight Saving Time ends in September. |
10 | Daylight Saving Time ends in October. |
11 | Daylight Saving Time ends in November. |
12 | Daylight Saving Time ends in December. |
Daylight Saving Time end - relative day of month. The relative day of the month on which Daylight Saving Time ends. The possible values are:
blank | This time zone description does not support Daylight Saving Time. |
1 | Daylight Saving Time ends on the first occurrence of the specified day of the week. |
2 | Daylight Saving Time ends on the second occurrence of the specified day of the week. |
3 | Daylight Saving Time ends on the third occurrence of the specified day of the week. |
4 | Daylight Saving Time ends on the fourth occurrence of the specified day of the week. |
L | Daylight Saving Time ends on the last occurrence of the specified day of the week. |
Daylight Saving Time end - time. The time of day at which Daylight Saving Time ends. The time is specified in the form hhmmss, where hh = hours, mm = minutes and ss = seconds. If the time zone description does not support Daylight Saving Time, this field is blank.
Daylight Saving Time full name. The full name of the time zone when Daylight Saving Time is being observed. If the time zone description does not support Daylight Saving Time, this field is blank. If the time zone description uses a message to specify the full name and the message cannot be retrieved, this field returns *N. This can occur when the caller of the API is not authorized to the message file or its library, the message file cannot be found or the message does not exist in the specified message file.
Daylight Saving Time indicator. Indicates whether or not the time zone description supports Daylight Saving Time.
0 | This time zone description does not support Daylight Saving Time. |
1 | This time zone description supports Daylight Saving Time. |
Daylight Saving Time message. The message that contains the abbreviated and full names of the time zone when Daylight Saving Time is being observed. If the time zone description does not support Daylight Saving Time, this field is blank. If a message was not specified when the time zone description was created or last changed, this field returns *NONE.
Daylight Saving Time shift. The number of minutes that local time moves forward when Daylight Saving Time starts or moves backward when Daylight Saving Time ends. If the time zone description does not support Daylight Saving Time, this field returns -1.
Daylight Saving Time start - day. The day of the week on which Daylight Saving Time starts. The possible values are:
blank | This time zone description does not support Daylight Saving Time. |
1 | Daylight Saving Time starts on a Monday. |
2 | Daylight Saving Time starts on a Tuesday. |
3 | Daylight Saving Time starts on a Wednesday. |
4 | Daylight Saving Time starts on a Thursday. |
5 | Daylight Saving Time starts on a Friday. |
6 | Daylight Saving Time starts on a Saturday. |
7 | Daylight Saving Time starts on a Sunday. |
Daylight Saving Time start - month. The month in which Daylight Saving Time starts. The possible values are:
blank | This time zone description does not support Daylight Saving Time. |
01 | Daylight Saving Time starts in January. |
02 | Daylight Saving Time starts in February. |
03 | Daylight Saving Time starts in March. |
04 | Daylight Saving Time starts in April. |
05 | Daylight Saving Time starts in May. |
06 | Daylight Saving Time starts in June. |
07 | Daylight Saving Time starts in July. |
08 | Daylight Saving Time starts in August. |
09 | Daylight Saving Time starts in September. |
10 | Daylight Saving Time starts in October. |
11 | Daylight Saving Time starts in November. |
12 | Daylight Saving Time starts in December. |
Daylight Saving Time start - relative day of month. The relative day of the month on which Daylight Saving Time starts. The possible values are:
blank | This time zone description does not support Daylight Saving Time. |
1 | Daylight Saving Time starts on the first occurrence of the specified day of the week. |
2 | Daylight Saving Time starts on the second occurrence of the specified day of the week. |
3 | Daylight Saving Time starts on the third occurrence of the specified day of the week. |
4 | Daylight Saving Time starts on the fourth occurrence of the specified day of the week. |
L | Daylight Saving Time starts on the last occurrence of the specified day of the week. |
Daylight Saving Time start - time. The time of day at which Daylight Saving Time starts. The time is specified in the form hhmmss, where hh = hours, mm = minutes and ss = seconds. If the time zone description does not support Daylight Saving Time, this field is blank.
Displacement to TZ string. The displacement, in bytes, from the beginning of this time zone description to the TZ string.
Length of a time zone description entry. The length of a single time zone description entry in the receiver variable.
Length of this time zone description entry. The length of this time zone description entry. This value is the number of bytes from the start of the time zone description entry to the start of the next entry (if any) in the receiver variable.
Length of TZ string. The length in bytes of the TZ string, excluding the terminating null at the end of the string.
Local system time indicator. Indicates whether or not the time zone description is currently specified in the Time zone (QTIMZON) system value. The time zone description specified in the QTIMZON system value is used to calculate local system time and cannot be deleted.
0 | This time zone description is not currently specified in the QTIMZON system value. |
1 | This time zone description is currently specified in the QTIMZON system value. |
Message file library name. The name of the library containing the message file used to retrieve the Standard Time message and the Daylight Saving Time message. The field may contain *LIBL which means that the library list is searched to locate the message file. The library name is left-justified and padded with blanks on the right. If the message file name specifies *NONE, this field returns blanks.
Message file name. The name of the message file used to retrieve the Standard Time message and the Daylight Saving Time message. The message file name is left-justified and padded with blanks on the right. If a message was not specified when the time zone description was created or last changed, this field returns *NONE.
Number of time zone descriptions available. The number of time zone descriptions that match the time zone description name specified on the call to this API. This is the number of time zone descriptions which the caller of the API has *USE authority to.
Number of time zone descriptions returned. The number of time zone descriptions returned in the receiver variable.
Offset from UTC. The time difference, in minutes, between this time zone and Coordinated Universal Time (UTC). This value is subtracted from local time to obtain UTC time. A negative difference indicates that the time zone is west of UTC and a positive difference indicates that the time zone is east of UTC.
Offset to time zone descriptions. The offset in bytes from the beginning of the receiver variable to the first time zone description.
Reserved. An unused field.
Standard Time abbreviated name. The abbreviated name used with the time zone when Daylight Saving Time is not being observed. If the time zone description uses a message to specify the abbreviated name and the message cannot be retrieved, this field returns *N. This can occur when the caller of the API is not authorized to the message file or its library, the message file cannot be found or the message does not exist in the specified message file.
Standard Time full name. The full name of the time zone when Daylight Saving Time is not being observed. If the time zone description uses a message to specify the full name and the message cannot be retrieved, this field returns *N. This can occur when the caller of the API is not authorized to the message file or its library, the message file cannot be found or the message does not exist in the specified message file.
Standard Time message. The message that contains the abbreviated and full names of the time zone when Daylight Saving Time is not being observed. If a message was not specified when the time zone description was created or last changed, this field returns *NONE.
Text description. The user text, if any, used to briefly describe the time zone description.
Time zone description name. The name of the time zone description object.
TZ string. A null-terminated character string that describes the time zone in a format compatible with industry standards. The returned string may be used to set IBM® i PASE environment variable TZ, and has this format (spaces inserted for readability):
std offset dst offset , start/time , end/time
An example of a TZ string for time zone QN0600CST (USA Central time) is "<CST>6<CDT>,M4.1.0,M10.5.0". The TZ string for time zone QP1245UTC2 (Chatham Islands time) is "<UTC+12x45S>-12:45<UTC+12x45D>,M10.1.0/02:45:00,M3.3.0/03:45:00". Daylight Saving Time specifications (dst, offset, start/time, and end/time) are omitted if the time zone does not use Daylight Saving Time.
std
- This is the Standard Time abbreviated name. The first character shall be the less-than ( '<' ) character and the last character shall be the greater-than ( '>' ) character. All characters between these delimiting characters shall be alphanumeric characters, the plus-sign ( '+' ) character, or the minus-sign ( '-' ) character. Trailing blanks are removed, and any character not allowed by standards is replaced with a lower case x ( 'x' ). The value for this field does not include the delimiting characters.
offset
- Hours and minutes behind Coordinated Universal Time (UTC). Minutes are omitted if the time zone is an integral number of hours behind UTC.
offset
is formatted as hh:mm if minutes are included, and has a leading minus sign if the value is negative. A negative value indicates the time zone is east of UTC, which is the opposite of the Offset from UTC field (in format RTMZ0100). Theoffset
followingstd
is required. If nooffset
followsdst
, Daylight Saving Time is assumed to be one hour ahead of Standard Time. dst
- This is the Daylight Saving Time abbreviated name. The first character shall be the less-than ( '<' ) character and the last character shall be the greater-than ( '>' ) character. All characters between these delimiting characters shall be alphanumeric characters, the plus-sign ( '+' ) character, or the minus-sign ( '-' ) character. Trailing blanks are removed, and any character not allowed by standards is replaced with a lower case x ( 'x' ). The value for this field does not include the delimiting characters.
start/time
- Specifies when Daylight Saving Time starts.
start
includes the month (1-12), week number (1-5), and day (0-6, for Sunday-Saturday) in the formMm.n.d
.time
is formatted ashh:mm:ss
, but is omitted if Daylight Saving Time starts at 2:00:00. end/time
- Specifies when Daylight Saving Time ends.
end
includes the month (1-12), week number (1-5), and day (0-6, for Sunday-Saturday) in the formMm.n.d
.time
is formatted ashh:mm:ss
, but is omitted if Daylight Saving Time ends at 2:00:00.
Year offset. The number of years that the current year in the calendar system used with this time zone differs from the current Gregorian year.
Error Messages
Message ID | Error Message Text |
---|---|
CPF24B4 E | Severe error while addressing parameter list. |
CPF3CF1 E | Error code parameter not valid. |
CPF3CF2 E | Error(s) occurred during running of &1 API. |
CPF3C19 E | Error occurred with receiver variable specified. |
CPF3C21 E | Format name &1 is not valid. |
CPF3C24 E | Length of the receiver variable is not valid. |
CPF3C90 E | Literal value cannot be changed. |
CPF8130 E | Time zone description &1 damaged. |
CPF9801 E | Object &2 in library &3 not found. |
CPF9802 E | Not authorized to object &2 in &3. |
CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V5R3