histutil is a collection of routines for working with student history information. Utilities are provided for creating, and deleting student history information.
histutil hides the details of how the student history sub-system organizes and maintains the data. Therefore, application programs should be using histutil services as much as possible to limit the specifics of manipulating student history data within the boundaries of this utility.
The following is a catalog of the availble services with a brief discussion of what the service provides and the parameters available to it. Some things you should know about when reading the service specifications are:
Note: If you are going to use any of the services that in any way will update stu-* records, you are strongly encouraged to hold the stu-base record EXCLUSIVEly, to enforce single-threaded processing.
DEFINE [NEW]
This must be present in any module which will be using any if the
histutil services. The instantiating procedure must use the
NEW keyword. Any child procedures should omit the NEW keyword or they will
start another instance of histutil.
CLEAN_UP
This must be invoked by the procedure that created the current instance of
histutil. It releases all allocated resources and terminates
the instance associated with the current procedure. Generally, the module
that used DEFINE NEW is the same one that should have a CLEAN_UP call.
You must make sure that all exit paths in your program properly invoke the CLEAN_UP service. If not, your program will consume an unnecessarily large amount of memory which can only be freed by exiting the Progress session completely!
CREATE EVENT stu-hist-buff create-ok
This service allows you to save all the *changes* that are contained in
this history event. (You will have to physically create the stu-history
record) (TRANSACTION SENSITIVE) If any of the building-dependent fields
are among the changes (grade-id, house-id, personnel-id, room-id), you
*must* also pass the bldg-id, even if the building was not a change
itself.
The CREATE service is the only service that works with a non-complete stu-history buffer. All other services require the stu-history buffer to be fully populated.
PUSH EVENT stu-hist-buff
This service allows you to override all corresponding changes from
posterior events that were preventing the changes in this event from
showing in the student most up-to-date information. Note that stu-year
based changes are pushed through the stu-year record for the given school
year. (Other stu-year records of that student are never affected)
DELETE EVENT stu-hist-buff delete-ok
This service allows you to remove a stu-history record completely. This
means the integrity of the other stu-history records, as well as the
corresponding stu-year record, and the stu-base record will be maintained.
At the end, the stu-history record is deleted for you. Reasons for
failure are:
MODIFY EVENT-DATE stu-hist-buff new-hist-date modify-ok
This service allows you to change the history date of an event. Because
changing the history date of an event is somewhat tricky, this service was
designed to do just this.
CHECK ONLY-EVENT stu-hist-buff only-event
This service allows you to know whether this is the only/last event
present for the student for the given school year.
CHECK CHANGES-CURRENT stu-hist-buff changes-current-list
This service allows you to know whether a particular history event has any
of its changes affecting the corresponding stu-year data in the given
school year, and/or the stu-base data. The list that is returned to you
is composed of the tokens described in the GET CHANGED-FIELD-LIST service.
CHECK FIRST-EVENT stu-hist-buff first-event
This service allows you to know whether the particular record you are
manipulating is the first event time-wise on file for the given student
in the given school year.
CHECK LAST-EVENT stu-hist-buff last-event
This service allows you to know whether the particular record you are
manipulating is the last event time-wise on file for the given student in
the given school year. (All the data contained in this event is the data
appearing in the corresponding stu-year record)
GET FIRST-EVENT stu-year stu-hist-recid
This service allows you to get the RFA of the first history event time-wise
for a student in a specific school year, as specified by stu-year.
GET LAST-EVENT stu-year stu-hist-recid
This service allows you to get the RFA of the last history event time-wise
for a student in a specific school year, as specified by stu-year.
GET CHANGED-FIELD-LIST stu-hist-buff changed-field-list
This service allows you to know what bits of information changed from the
previous history event time-wise. For school year based data, this
service will work within the given school year. This means that the first
event of this school year will *never* have any changed data. For
non-school year based data, this service will work across school years.
Thus, the first event of a school year group may have some changed data.
The list that is returned to you can contain any of the following (In parentheses are listed the corresponding stu-year/stu-base fields):
SET PUSH-TO-CURRENT push-to-current
This service allows you to specify that all CREATE EVENT or MODIFY
EVENT-DATE operations should have all changes from a history event
override all changes from posterior events, i.e. all changes from the
history event would affect the corresponding stu-year record and the
stu-base record. For school year based data, the overriding is limited to
the given school year. For non-school year based data, the overriding is
performed across school years.
Below are briefly described how some tasks you may need to perform can be implemented using the services from this utility.
If you want to delete a history event:
If you want to move a history event through time, i.e. change the history date of the event:
If you want to add a history event:
Anyone using this utility should have some basic knowledge of how the history data is organized. All stu-history records for a student are partitioned into school year groups. (Each group of stu-history records is identified by its school-year-id.) There is one stu-year record corresponding to each stu-history group. By definition, the last stu-history record of any given school year group, time-wise (i.e. by school-year-id, history-date, and history-seq), is carbon copy of the corresponding stu-year record. histutil will always manipulate school year based data only within one specific school year group, i.e. changes will never spill over from one school year to posterior school years. Note that history dates are not bound to the school year their events are created into.
Since there is only one stu-base record per student, histutil will manipulate non-school year data will be done across all school year groups.
The first stu-history record of a new group is created only by promoting a student; Student promotion is the time when a new stu-year record is created for the student, with a new school-year-id. To visualize how the history data is organized and processed:
January 16, 1996: