Museum

CAL_$DECODE_ASCII_TZDIF           Domain/OS            CAL_$DECODE_ASCII_TZDIF


NAME
     cal_$decode_ascii_tzdif - decode an ASCII time zone

SYNOPSIS (C)
     #include <apollo/base.h>
     #include <apollo/cal.h>

     void cal_$decode_ascii_tzdif(
          char *tz_string,
          short &string_length,
          short *tz_dif,
          cal_$tz_name_t *tz_name,
          status_$t *status)

SYNOPSIS (Pascal)
     %include '/sys/ins/base.ins.pas';
     %include '/sys/ins/cal.ins.pas';

     procedure cal_$decode_ascii_tzdif(
          in tz_string: univ cal_$string_t;
          in string_length: integer;
          out tz_dif: integer;
          out tz_name: cal_$tz_name_t;
          out status: status_$t);

SYNOPSIS (FORTRAN)
     %include '/sys/ins/base.ins.ftn'
     %include '/sys/ins/cal.ins.ftn'

           integer*2 string_length, tz_dif
           integer*4 status
           character tz_string*80, tz_name*4

           call cal_$decode_ascii_tzdif(tz_string, string_length,
          &                             tz_dif, tz_name, status)

DESCRIPTION
     Cal_$decode_ascii_tzdif translates the supplied ASCII string into an
     offset from Coordinated Universal Time (UTC), in units of minutes.  The
     ASCII string can contain a time zone name or a time zone difference.

     tz_string
          An ASCII time zone name or time zone difference.  A time zone name
          can be one of the following strings designating UTC (or Greenwich
          Mean Time), and the eight standard U.S. time zones:
                        ________________________________________
                        |Time Zone |         Time Zone          |
                        |  Name    |        Represented         |
                        |__________|____________________________|
                        |   CDT    | Central Daylight Time      |
                        |   CST    | Central Standard Time      |
                        |   EDT    | Eastern Daylight Time      |
                        |   EST    | Eastern Standard Time      |
                        |   GMT    | Greenwich Mean Time        |
                        |   MDT    | Mountain Daylight Time     |
                        |   MST    | Mountain Standard Time     |
                        |   PDT    | Pacific Daylight Time      |
                        |   PST    | Pacific Standard Time      |
                        |   UTC    | Coordinated Universal Time |
                        |__________|____________________________|

          A time zone difference is a value which, when added to UTC, produces
          the local time.  Specify a time zone difference in the following
          form:  "HOUR:MINUTE", where HOUR is a decimal integer between -12
          and 12, and MINUTE is either 0 or 30.  For example, Eastern Daylight
          Time can be represented as "-4:00".

     string_length
          The number of bytes in tz_string.

     tz_dif
          The offset in minutes from UTC of the time zone specified in
          tz_string.  Tz_dif will be negative for time zones west of the
          Greenwich Meridian and positive for time zones east of the Greenwich
          Meridian.

     tz_name
          The name of the time zone specified in tz_string.  If tz_string con-
          tains a time zone name, this procedure returns that name in tz_name.
          If tz_string contains a time zone difference, this procedure returns
          spaces in tz_name.

     status
          The completion status.  If cal_$decode_ascii_tzdif fails, it may
          return one of the following values in status:

          cal_$bad_syntax
               The string is not in the proper format.

          cal_$empty_string
               The string length is 0 or the string contains only spaces.

          cal_$invalid_tzdif
               The string contains an invalid time zone difference.

          cal_$unknown_timezone
               The string contains an unknown time zone name.