!=============================================================================!
!  DIVISION   I	:				     HELP MODULE DECLARATION  !
!=============================================================================!
!									      !
!      -----------------------------------------------------------------      !
!      SECTION 01 :					 INITIAL VERSION      !
!      -----------------------------------------------------------------      !
!									      !
!      File Specification: ACCSRC_ACC:[HELP.ENDUSERS]CALENDAR.HLP	      !
!      Author		 : Marlys A. Nelson				      !
!      Initial version	 : 01.00.00 18-AUG-1985	VMS 4.1			      !
!									      !
!      -----------------------------------------------------------------      !
!      SECTION 02 :				    MODIFICATION HISTORY      !
!      -----------------------------------------------------------------      !
!									      !
!									      !
!=============================================================================!
!  DIVISION  II	:				  HELP MODULE SPECIFICATIONS  !
!=============================================================================!
!									      !
!      Key 1 (Command name)............	CALENDAR			      !
!	 Key 2 ........................	  Parameters			      !
!	 Key 2 ........................	  Qualifiers			      !
!	 /qualifier ...................	    /BEGINNING=date		      !
!	 /qualifier ...................	    /ENDING=date		      !
!	 /qualifier ...................	    /INPUT=text-file		      !
!	 /qualifier ...................	    /OUTPUT=list-file		      !
!	 /qualifier ...................	    /SINGLE			      !
!	 Key 2 ........................	  Significant_Dates_File	      !
!	 Key 2 ........................   Errors			      !
!									      !
!=============================================================================!
!  DIVISION III	:					       SPECIAL NOTES  !
!=============================================================================!
!									      !
!									      !
!=============================================================================!
!
!
!=============================================================================!
! Key 1								     CALENDAR !
!=============================================================================!
!
1 CALENDAR
CALENDAR will produce monthly calendars for any given month and year.

Format:

     CALENDAR	[significant-dates-file]

Each month calendar fits on a single sheet of paper and may be printed
on  the  line  printer  or  on the DIABLO letter quality printer.  The
calendar contains a large square for each  date  suitable  for  adding
hand-written information.  Also, you may specify a file which contains
additional information which should be printed in these  date  squares
when the calendar is produced.
!
!=============================================================================!
! Key 2								   Parameters !
!=============================================================================!
!
2 Parameters
significant-dates-file

  Specifies  the  significant  dates  file  to  be  searched for added
  information to be printed in the date  squares  of  the  calendar(s)
  printed.   This  file  must  be formatted correctly for CALENDAR.  A
  standard text file can be transformed into  this  type  of  file  by
  using the /INPUT qualifier.

  This  parameter is not required.  If not specified, the date squares
  on  the  calendars  printed  will   not   contain   any   additional
  information.   The  squares  will  contain space for the addition of
  hand-written information however.

  If  /INPUT is not specified, a significant dates file is not assumed
  unless explicitly specified as a parameter.  If /INPUT is specified,
  a  default filespec of CALENDAR.DAT is used if this parameter is not
  provided.
!
!=============================================================================!
! Key 2								   Qualifiers !
!=============================================================================!
!
2 Qualifiers
/BEGINNING

  /BEGINNING[=date]

  Specifies the date of the first calendar month to be printed.   This
  must  be  specified  as  a  valid  date in the standard VAX/VMS date
  format (i.e. dd-mmm-yyyy).  The day portion of the date  is  ignored
  by  CALENDAR  however.   You  may  not  print  calendars for partial
  months.  If you do not specify a beginning date, the  current  month
  and year are used.

/ENDING

  /ENDING[=date]

  Specifies  the  date of the last calendar month to be printed.  This
  must be specified as a valid  date  in  the  standard  VAX/VMS  date
  format  (i.e.  dd-mmm-yyyy).  The day portion of the date is ignored
  by CALENDAR however.   You  may  not  print  calendars  for  partial
  months.  If you do not specify an ending date, the current month and
  year are used.

/INPUT

  /INPUT[=filespec]

  Specifies the  name  of  a  source  significant  dates  file.   This
  qualifier  requests CALENDAR to read the specified file and create a
  properly formatted significant dates  file  for  use  in  subsequent
  CALENDAR  commands.   If  you  specify  /INPUT, but do not specify a
  source filespec, the default is  CALENDAR.TXT.   If  you  specify  a
  filename  but  not a filetype, the default is .TXT.  The name of the
  result significant dates file is specified as the first,  and  only,
  parameter.   No other qualifiers may be used if /INPUT is specified.
  Also, no actual calendars are created when this qualifier is used.

/OUTPUT

  /OUTPUT[=filespec]

  Specifies  a  file  to  contain  the  calendars.   By  default,  the
  calendars  are  written  to  a  new file named CALENDAR.LIS.  If the
  /OUTPUT qualifier is specified, all the calendars  will  be  written
  into  the  file  with the name specified.  The default file type for
  the file is .LIS.

/SINGLE

  /SINGLE
  /NOSINGLE (D)

  By default, all requested calendars are written into a single output
  file.  A formfeed precedes each calendar month.  If  this  qualifier
  is  selected,  each  calendar  month will be written into a separate
  output file.  The files are named CALENDAR_yyyymmm.LIS where  'yyyy'
  corresponds  to  the  calendar  year  and  'mmm'  corresponds to the
  calendar month name  abbreviation.   For  example,  a  calendar  for
  August  1985  would have the name CALENDAR_1985AUG.LIS.  The /OUTPUT
  qualifier is not allowed if /SINGLE is specified.   The  default  is
  /NOSINGLE.
!
!=============================================================================!
! Key 2						       Significant_Dates_File !
!=============================================================================!
!
2 Significant_Dates_File
This file contains additional information which CALENDAR will print in
the date  square  on  the  calendars  produced.   This  is an optional
feature.  By default, each calendar will contain  date  squares  which
look like the following:

     |-----------------|
     |                 |
     | 4               |
     |                 |
     |                 |
     |                 |
     |                 |
     |-----------------|

By creating a significant dates file, you can add up to two  lines  of
additional information in any day square.  For example:

     |-----------------|
     |                 |
     | 4               |
     |                 |
     | Mid-term Test   |
     | Basketweaving   |
     |                 |
     |-----------------|

The  significant  dates file must be specially formatted for CALENDAR.
The /INPUT qualifier provides a way to transform a  source  text  file
into  this special format.

The source text file must conform to the following guidelines:

     o The date must be the first item on a line.  It must be  in  the
       form "dd-mmm-yyyy" and must occupy positions 1-11 of the  line.
       It  must  be  a  valid date.  If CALENDAR encounters an invalid
       date when making the significant dates file, it  will  print  a
       warning message and ignore that source line.

     o The next 21 character positions of the source line are  ignored
       by CALENDAR.  These are columns 12-32.   This  portion  of  the
       line  may  be left blank or it may contain information of value
       to you.  The information will be transferred to the significant
       dates  file if you wish to read this file from another program.

     o The information to be printed in the day  square  occurs  next.
       The first line of information should be in positions 33-47  and
       the  second line should be in positions 48-62.  Note that there
       is no spacing between the two lines of information.

     o CALENDAR will not look at any information in  the  source  line
       beyond  position  62.   Information may be present for your own
       use.   This  information  will  not  be  transferred   to   the
       significant dates file however.

A  sample  source text file is shown below.  The row of numbers at the
top are provided for reference for determining the  positions  of  the
various items.  You should not include such lines in your file.

              11111111112222222222333333333344444444445555555555666
     12345678901234567890123456789012345678901234567890123456789012
     06-SEP-1985                     Classes Start
     24-SEP-1985                     Mom's Birthday SEND CARD!
     04-OCT-1985                     Mid-Term Test  Basketweaving
     18-NOV-1985     Ugh!            Finals start

Once you have created your source significant  dates  file,  you  must
transform  it  into  the  form  need by CALENDAR.  This can be done by
using the /INPUT qualifier of CALENDAR.  No  other  qualifier  may  be
used   with   /INPUT.    Assuming   you   named   your   source   file
IMPORTANT_DATES.TXT this can be done with the command:

     $ CALENDAR/INPUT=IMPORTANT_DATES.TXT IMPORTANT_DATES.DAT

The file IMPORTANT_DATES.DAT will be  created.   This  is  the  actual
significant dates file needed by CALENDAR in subsequent runs.  Now, if
you wish to print calendars for September through November,  including
your additional information, enter the command:

     $ CALENDAR/BEGIN=01-SEP-1985/END=01-NOV-1985 IMPORTANT_DATES.DAT
!
!=============================================================================!
! Key 2								       Errors !
!=============================================================================!
!
2 Errors
All the errors returned by CALENDAR are described below.
!
!
!
3 BADDATE
%CALENDAR-W-BADDATE, input source line ignored - invalid date

This error occurs only when you request CALENDAR to transform a source
significant  dates  file  into  an  actual  significant  dates   file.
CALENDAR  has  detected  an invalid date in positions 1-11 of a source
file line.  The invalid date will be  displayed  following  the  error
message.   Correct  the  source  file  and  reenter the CALENDAR/INPUT
command.
!
!
!
3 DUPDATE
%CALENDAR-W-DUPDATE, duplicate date - second use ignored

This error occurs only when you request CALENDAR to transform a source
significant  dates  file  into  an  actual  significant  dates   file.
CALENDAR  has  detected  a  duplicate date.  Two source lines have the
same date.  The date will be displayed following  the  error  message.
The  second  line  containing  this date will be ignored.  Correct the
source file and reenter the CALENDAR/INPUT command.
!
!
!
3 TOOSHORT
%CALENDAR-W-TOOSHORT, input source line ignored - must contain at
                      least a date in columns 1-11

This error occurs only when you request CALENDAR to transform a source
significant   dates  file  into  an  actual  significant  dates  file.
CALENDAR  has  detected  a  source  line  which  is  shorter  than  11
characters.   At  least  a  date is required on each source line.  The
invalid source line will be displayed  following  the  error  message.
Correct the source file and reenter the CALENDAR/INPUT command.
!
!
!
3 OPENIN
%CALENDAR-E-OPENIN, error opening <filespec> as input

The specified file could not be found.  This may  occur  if  you  have
specified a significant dates file or if you have specified the /INPUT
qualifier.  If the specified file in either case cannot  be  found  or
read, you will receive this error.
!
!
!
3 OPENOUT
%CALENDAR-E-OPENOUT, error opening <filespec> as output

The specified file could not be  accessed.   This  may  apply  to  the
significant  dates  file  if you are attempting to create a new one by
specifying the /INPUT qualifier.  Also,  this  error  may  occur  when
producing  calendars.   Make  sure  that  you  have  specified a valid
filespec.  Also, this error may indicate insufficient quota to  create
new files.
!
!
!
3 WRITERR
%CALENDAR-F-WRITERR, error writing to file <filespec>;
                     Pascal error %Xdddddddd

The  specified  file  could  not  be  accessed.  This may apply to the
significant dates file if you are attempting to create a  new  one  by
specifying  the  /INPUT  qualifier.   Also,  this error may occur when
producing calendars.  This  error  may  indicate  insufficient  quota.
Check  your  disk  quota.  If the error persists, contact the Academic
Computing Center.
!
!=============================================================================!
! Key 2								     Examples !
!=============================================================================!
!
2 Examples
If you wish to create a calendar for the current month, all  you  need
to do is enter the command:

     $ CALENDAR

The calendar for the current month and year will be placed in the file
CALENDAR.LIS.  You may then print this calendar on the line printer by
entering the command:

     $ PRINT CALENDAR.LIS

If you wish to get calendars for the entire school year, you can do so
by entering the command:

     $ CALENDAR/BEGINNING=01-SEP-1985/ENDING=01-MAY-1986

All  calendars  will  be placed in the file CALENDAR.LIS.  You can use
the PRINT command again to get  the  calendars  printed  on  the  line
printer.  There will be a total of 9 calendars.  A calendar is printed
for the month of May even though the day is specified as 01.  CALENDAR
ignores the day values in the specified dates.

If  you want all the calendars requested in the previous example to be
written to separate files, you should enter the command:

     $ CALENDAR/BEGINNING=01-SEP-1985/ENDING=01-MAY-1986/SINGLE

CALENDAR  will  create  9  files,  each  with  names   of   the   form
CALENDAR_yyyymmm.LIS (i.e. CALENDAR_1985SEP.LIS, CALENDAR_1985OCT.LIS,
CALENDAR_1985NOV.LIS, etc.).
!
!=============================================================================!
!							   END OF HELP MODULE !
!=============================================================================!
