The conflict utilities is a package designed to allow you to check for conflicts in time between various master schedule courses. In addition to checking the courses, you can also apply a chronological ranges for the comparisons as well as room and teach restrictions.
DEFINE {NEW}
Define a new instance of confutil
CLEAN_UP
Release confutil context. You *MUST* do this before exiting your
program, regardless of why you are exiting your program!!!
SET SCHOOL_YEAR (yearid)
Set the school year (via it's ID) that the conflict utilities are
going to use for checking. The default is the 'current' school
year (as marked in the school-year file). You should do this before doing
anything else!
SET BLDG (bldgid)
Set a specific building for the scheudler to use. You should NOT set
this unless you get errors saying the district time table is too
complex. What this does is restrict the system to using only the
time tables of the specific building (presumably, the one you intend
on scheduling in).
If you set a building, the time routines will only be able to handle master-schd records for that building. That means that you cannot attempt to schedule students with requests fromother building (it'll fail).
'bldgid' is the ID of the building to work with or '?' if you want to support all buildings (this is the default).
You should not set this unless you really understand what you are doing.
SET SPARSE_CATALOG (flag)
Unless otherwise set, the district time tables are created 'sparsely'
(that is, there may be 'holes' in the table, but there is nothing
important missing). You can override this and build fully populated
district time tables. The cost is that the tables may involve too
many items for the scheduling algorithims to handle.
'flag' is a logical which indicates whether to create a sparse (TRUE) or full (FALSE) time table. This must be set before the REBUILD TIME_TABLES section (or before your first invocation of a routine that would implcitly rebuild the time tables. Also, if you really need a sparse or full time table, you might want to consider setting the 'force rebuild' flag on the REBUILD TIME_TABLES line to force it (a time table will not be rebuilt simply because you wanted a time table different from what is there and there is no way to determine what kind of time table was last built (short of shelping though it yourself - yecho)).
Genrally, you should not fiddle with the option unless you really understand why and what you are about to do.
SET MAP_CONFLICTS (flag)
If 'flag' is passed as true, then a conflicting course or course meeting
is still added to the students time tables. If passed as FALSE, then
the course or course-meets is not added to the time table. Either way,
a conflicting course will still set the 'Conflict' flag on the
appropriate CHECK call.
The default is to not map conflicts.
SET LOCAL_JOURNAL (flag)
If 'flag' is passed as TRUE, then a local journal of course section/meeting
will be enabled and used for rollback purposes if a conflict is encountered.
If set FALSE, then it is assumed that you are starting/stopping rollback
journaling and will use the 'JOURNAL x' options. The default is TRUE
(enable local journalling with rollback on conflicts).
GET BLDG (bldgid)
Return the bldg-id field last set via SET BLDG. This will usually be
? meaning that the conflict utilities will allow mappings from any
building in the district. If it is not ?, then a specific building
was enabled and the ID of it is returned. If bldgid is not ?, then
it usually indicates that the district has a very complicated time
table and the 'SETter' was minimizing the number of options used.
GET SPARSE_CATALOG (flag)
Returns the current sparse catalog flag. See SET SPARSE_CATALOG for
a description of it's meaning.
GET MAP_CONFLICTS (flag)
Returns the current MAP_CONFLICTS flag. See SET MAP_CONFLICTS for
a description of it's meaning.
GET LOCAL_JOURNAL (flag)
Returns the current LOCAL_JOURNAL flag. See SET LOCAL_JOURNAL for
a description of it's meaning.
REBUILD TIME_TABLES (forceflag) (silentflag)
Checks to see if the district time tables should be rebuilt. These
are the district wide scheduling period, period catalog and master
schedule meets records. If they need to be rebuilt, then a message
is put up on the users screen (unless the 'silentflag' is TRUE). If
'forceflag' is passed, the tables are rebuilt, regardless whether they
need it or not.
NOTE: If you do not rebuild the tables and they need it, they will be rebuilt as a side-effect of the first call you make to any other confutil routine. You should do this yourself in a place the user would expect/understand the possible delay caused by a rebuild. Also, a 'implicit' rebuild is never silent (the user will get a message).
CLEAR COURSES
Clears all previously mapped/checked courses and prepares the internal
logic for a new set of courses to check.
CLEAR TAG_VALUE (tagvalue)
Clears the usage flags for any time entry marked with a value matching
the passed 'tagvalue'. This can be very slow as it needs to visit
every item in the time table.
CHECK COURSE_SECTION (msbuff) (tag) (confflag) (conflictrecid)
You pass the buffer of a master-schd record and confutil will take
the course and see if it conflicts with any of the previosuly checked
courses. 'tag' is an integer that can be used to attach an arbitrary
tagging value (perhaps grouping value?) to the course as it's mapped.
You can use that value later to work with all the groups of a particular
tag value. 'confflag' allows you to override conflicts and require
the course be mapped, even it would cause conflicts. If FALSE, then
the last 'SET MAP_CONFLICT' flag will be in effect. If it conflicts,
'conflictrecid' of the first master-schd-meets record it conflicts with is
returned (which can be used to get back to the master-schd record).
If there is no conflict, then is is returned as ?.
CHECK COURSE_MEETING (msbuff) (msmbuff) (tag) (confflag) (conflictrecid)
You pass the buffer of a master-schd and related master-schd-meets
record and confutil will take the meeting and see if it conflicts with
any previously checked courses or course meetings. 'tag' is an integer
that can be used to work with all the items of a particular 'group'.
'confflag' allows you to override the last setting of MAP_CONFLICTS
and map the meeting record even if it does conflict. If passed as
FALSE, then the last setting of 'SET MAP_CONFLICTS' is in effect. If
there is a conflict, the RECID() of the conflicting master-schd-meets
record is returned in 'conflictrecid'. If there are no conflicts, then
? is returned.
JOURNAL START
Start a rollback journal to record all attempts to map courses. This
will keep track of all mapping attempts between it and and a subsequent
JOURNAL DISCARD or ROLLBACK call. Upto 128 journals can be running at a
time. If you start a journal, you *MUST* either DISCARD it or ROLLBACK
the journal.
JOURNAL DISCARD
Discard the last started journal. Journals operate in a stack like
fashion, so you can only discard the most recently started. All the
journal data is lost (though not rolled back). You *MUST* DISCARD or
ROLLBACK each and every journal you START.
JOURNAL ROLLBACK
Rolls back the changes made since the last journal open. All previously
mapped courses are flagged as unmapped. Rolling back a journal also
implicitly DISCARDs it.