Retrieve Time Zone Description (QWCRTVTZ) API

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:

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:

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.

Format RTMZ0200

The RTMZ0200 format returns the following information for the specified time zone description.

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:

Daylight Saving Time end - month. The month in which Daylight Saving Time ends. The possible values are:

Daylight Saving Time end - relative day of month. The relative day of the month on which Daylight Saving Time ends. The possible values are:

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.

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:

Daylight Saving Time start - month. The month in which Daylight Saving Time starts. The possible values are:

Daylight Saving Time start - relative day of month. The relative day of the month on which Daylight Saving Time starts. The possible values are:

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.

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). The offset following std is required. If no offset follows dst, 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 form Mm.n.d. time is formatted as hh: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 form Mm.n.d. time is formatted as hh: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

[ Back to top | Date and Time APIs | APIs by category ]