packages icon



 CAL(1)                   USER COMMANDS                     CAL(1)



 NAME
      cal - display a calendar

 SYNOPSIS
      cal [ options ] [ [ num_month ] year ]
      cal [ options ] [ [ word_month ] year ]

 DESCRIPTION
      cal is an enhanced version of the Unix cal command.   It  is
      compatible  to  the  Unix  version  in that it uses the same
      input arguments and its output may be  piped  or  redirected
      anywhere.

      cal displays a calendar for a specified  year,  a  specified
      month  and  year,  or  for the current date.  By default, it
      displays a calendar for the current system-date month,  with
      the current day hilighted.  It correctly handles the transi-
      tion from the Julian to  Gregorian  calendars  in  September
      1752.

 ARGUMENTS
      A verbally-specified month may be entered without specifying
      a  year  in  the  argument list; however, a single numerical
      argument will be interpreted as a year.  Only  the  first  3
      characters   of   the  month  name  are  significant  for  a
      verbally-specified month.  The command `cal 10' refers to 10
      AD, not October, and not 1910.

      The options are explained more  fully  in  the  ENHANCEMENTS
      sections below.  The available options are:

      -nod[ata]
           Do not try to read any appointment data file.

      -d[ata-file]=filename
           Read appointments from `filename' (default  appointment
           data  filename  depends  on operating system).  You may
           use -d up to 8 times in a commandline to specify multi-
           ple data file names.

      -f[uture]
           If current month is displayed, then  show  only  future
           appointments  from  the  appointment file, not appoint-
           ments that are past. NOTE:  This switch was -d in  pre-
           vious versions.

      -t[oday]
           If current month is displayed, then show only  appoint-
           ments for today from the appointment file.

      -e[urope]
           Use European format (first weekday is Monday).



 Sun Release 4.1   Last change: 11 January 1996                  1






 CAL(1)                   USER COMMANDS                     CAL(1)



      -m[axappts]
           Maximum number of appointments to display.  Minimum  is
           8, maximum is 50, default is 24.

      -p[ause]
           Pause before exiting and prompt for a keystroke.

      -8[bit]
           Allows the use 8 bit extended  ASCII  (code  page  437)
           characters  in  Unix  version.  It is always allowed in
           DOS and OS/2 versions

      -noc[olor]
           Inhibit the use of colors.

      -c[olor-file]=filename
           Read color definitions from `filename'  (default  color
           filename depends on operating system).

 COMMAND EXAMPLES
      cal -f -d=my_dates
           display  the  current  month  and  future  appointments
           defined in file `my_dates'

      cal 1996
           display the entire year of 1996

      cal 9 1752
           display the month of September 1752

      cal sep 1752
           same as above

      cal January
           display January of the current year

      cal help
           help message displayed for unrecognized arguments

 ENHANCEMENTS OVER STANDARD `CAL' COMMAND
      If displaying the single-month format, cal will look  for  a
      date file (the default file or whatever you specify with the
      -d option).  If found, cal will read the file,  looking  for
      special  date  descriptions  for  that  month  which will be
      displayed to the right of the calendar.  By default,  up  to
      24  appointments  (number  may  be  changed  with -m) may be
      displayed per month.  If the current date happens to fall on
      one  of these special dates, it will be flagged by an aster-
      isk.  If there is room, appointments for the next month  may
      also  be  displayed  (next  month's dates having definitions
      like "2nd Thursday" will be skipped).




 Sun Release 4.1   Last change: 11 January 1996                  2






 CAL(1)                   USER COMMANDS                     CAL(1)



      The special date descriptions specified in the date file are
      single lines, formatted as follows:

       YYYY MM DD NW xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

      where

      YYYY is the year,

      MM   is the month (01 - 12),

      DD   is the day (00 if the NW field is used),

      NW   is the weekday-of-month code (00 if  the  DD  field  is
           used)

      xxxx is the description; it will be truncated  as  necessary
           to fit

      The data MUST occupy the character fields as shown.  If YYYY
      is  specified  as  -999, the month and day are assumed to be
      annual events such as holidays, and the description will  be
      displayed  for  any year.  If MM is specified as -9, the day
      is assumed to be a monthly event for the specified year.  In
      the weekday-of-month code NW, N signifies on which weekday W
      the special date occurs.   For  example,  31  indicates  the
      third  sunday.  Values of W range from 1 to 7, for Sunday to
      Saturday, respectively.  A value of 9 for N indicates "last"
      as in 95 for "last thursday."

      If ALL of the fields contain a positive number and the  year
      is  at  least  1970,  then  the description is assumed to be
      periodic, starting at the given date,  with  the  period  in
      days  specified  in  NW (e.g. 1995 01 06 14 will display the
      description every 2nd Friday using 6  January  1995  as  the
      base date).  The base date does not get displayed.

      You can display birthdays and anniversaries by  putting  the
      year  of  birth  (or other special event) inside brackets or
      braces, in the description.  This number is converted to the
      number of years since the year you indicate and the brackets
      or braces are removed from the output.   If  braces  {}  are
      used  the  number  will  have an ordinal suffix, as in 21st,
      32nd, 43rd, 54th, etc.  If the number in brackets or  braces
      is  greater  than  the  current  year,  the  number  will be
      displayed unchanged.  Example: "Alex's {1961} birthday" will
      display  as  "Alex's  34th birthday" (if the current year is
      1995).  If you need to include brackets or  braces  in  your
      output  then you can escape them by prefixing it with a ''.
      Example: "Alex's 1961 birthday"  will  be  displayed  as
      "Alex's {1961} birthday".




 Sun Release 4.1   Last change: 11 January 1996                  3






 CAL(1)                   USER COMMANDS                     CAL(1)



      NOTE:  If cal is invoked with the -europe switch, then the W
      values  1-7  denote  Monday(1) to Sunday(7) rather than Sun-
      day(1) to Saturday(7).

      A line in cal.dat must start with -999 or a  4-digit  number
      to  be  considered  as  data.   The data lines may be in any
      order.  All these appointments will be displayed in  chrono-
      logical order, regardless of the ordering in the appointment
      data file.

      If compiled with the USE_REMINDER flag, cal will also search
      for the files dates and .dates in the same places as for the
      caldat equivalents.  The dates file  is  used  by  the  rem-
      inder(1)  program  and is an alternate, less-powerful format
      for specifying descriptions.  A file in this  format  cannot
      be specified with the -data-file= option.

      The reminder format consists  of  text  lines  of  length  <
      screen width in the following format:

        DDDDDDDD:N:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:yyyyyy:S

      where

      DDDDDDDD
           is the date in one of the following formats:

       M/D/Y
           an event occurring on a specific day (year can  be  two
           or  four  digits, but must be two for backward compati-
           bility with reminder)

       M/D an event occurring every year

       D   an event occurring every month

       DDD an event occurring every  week  (day  of  the  week  is
           'Sun', 'Mon', etc.)

      N    is the number of days notice of the event to  give  the
           user (ignored by cal)

      xxxxx
           the event description

      yyyyy
           an optional receptor of the event (e.g. Mr. Jones)

      S    status flag, either N for  normal  event  or  D  for  a
           deleted (not displayed) event





 Sun Release 4.1   Last change: 11 January 1996                  4






 CAL(1)                   USER COMMANDS                     CAL(1)



      Blank lines are ignored.  A line otherwise not in the  above
      format  is  assume to specify a file name from which to read
      more events.  The file is searched for in the usual places.

      The -f commandline switch causes any date description  older
      than  today's  date  to  be ignored, thereby giving room for
      other descriptions with future dates to  be  displayed.   As
      time progresses through the month, old descriptions are dis-
      carded and newer ones are used.  The -f switch affects  only
      the display for the current month, and not other months.

      There is an optional environment variable that can  be  used
      by cal if found.  If CALOPT is set then cal will read it and
      use any valid command line options found.  This  allows  any
      commonly  used  switches  to  be set in your environment and
      always used (e.g. -europe).   Cal  will  produce  its  usage
      screen when run if any invalid options are set in this vari-
      able.

 ENHANCEMENTS SPECIFIC TO MS-DOS and OS/2
      Under MS-DOS or OS/2, commandline arguments may begin with a
      '/' instead of a '-' character.  It works either way.

      The default name for the date file under MS-DOS and OS/2  is
      called  cal.dat.  It will first look for this file (or what-
      ever you specify with the -d option) in the  current  direc-
      tory  and  if  that fails it will look in the directory that
      the cal program is located in.

      cal modifies the display attributes  behind  its  output  in
      order to display the calendar in attractive colors.  Display
      manipulation is not done if cal's output is redirected to  a
      file.   When  cal  starts  up,  it  looks  for a file called
      cal.col (or whatever you specify with the -c option),  first
      in  cal's  originating  directory,  and  then in the current
      directory.  The colors have their own defaults if  the  file
      is not found.

 ENHANCEMENTS SPECIFIC TO UNIX
      Under  Unix  the  default  filenames  and  places  that  are
      searched for are different.  For the calendar date file, cal
      searches for the file .caldat in the users  home  directory.
      If it is not found cal will then look for the file caldat in
      the current directory and then look for it in /usr/lib.

      For the default color file, it will look first in the user's
      home directory for the file .calcol.  It then looks for cal-
      col in the current directory and then in /usr/lib.

 COLOR ATTRIBUTES
      Example of a color definition file:




 Sun Release 4.1   Last change: 11 January 1996                  5






 CAL(1)                   USER COMMANDS                     CAL(1)



       15 02   video colors for month name
       01 03   video colors for weekday header
       07 01   video colors for normal calendar days
       13 01   video colors for sundays
       14 02   video colors for current day
       07 06   bkgd for yearly calendar (space between months)
       11 00   video colors for special day descriptions
       12 08   video colors for * indicating descr.=today

      FG BG

      Color definitions must appear as above, as  a  two-character
      field  for  the  foreground color, followed by a space, fol-
      lowed by a two-character field  for  the  background  color.
      The color definitions must start on the first line, and must
      not contain blank lines.   Comments  may  appear  after  the
      second  field,  provided that the total line length does not
      exceed 80 characters.

      Possible colors:

        black           0
        blue            1
        green           2
        cyan            3
        red             4
        violet          5
        orange          6
        light gray      7

        dark gray       8
        bright blue     9
        bright green    10
        bright cyan     11
        bright red      12
        bright violet   13
        yellow          14
        white           15

      Specifying a background color from 8 to 15 will result in  a
      background color of 0 to 7, with flashing text.

 FILES
      cal.dat             DOS and OS/2 date file
      cal.col             DOS and OS/2 color file
      ~/.caldat           Unix local date file
      ~/.calcol           Unix local color file
      caldat
      /usr/lib/caldat     Unix global date files
      calcol
      /usr/lib/calcol     Unix global color files
      ~/.dates            date  file  used  with   Unix   reminder



 Sun Release 4.1   Last change: 11 January 1996                  6






 CAL(1)                   USER COMMANDS                     CAL(1)



                          program and can be used with cal.

 AUTHOR
           Alex Matulich  -  matulich_a@seaa.navsea.navy.mil

           ...with enhancements and modifications by other
           contributors.

           (c) 1995 by Unicorn Research Corporation.  All rights
           reserved.  Inspired by an Amiga program by
           Gary L. Brant.

 SEE ALSO
      date(1), reminder(1), rs(1)









































 Sun Release 4.1   Last change: 11 January 1996                  7