gradutil is a collection of routines for working with student grading information. Utilities are provided for extracting labels, extracting grades and setting grades into a student record for both a specific grading period and a range of grading periods.
gradutil hides the details of how various grades are enabled and used for a given course in a given building and grading period. Because there is a great deal of variation in how all the items come together, your should never access anything directly from the stu-grade, grading-period, or any of the mark related fields from building if you can get the same information via this service.
In the future, additional mechanisms may appear that determine which courses are enabled for what grades. Any such changes will be automatically updated within gradutil. If you use gradutil, future changes should be transparent.
The following is a catalog of the availble services with a brief discussion of what the service provides and the parameters available to it. Optional parameters to a given service are enclosed in square brackets ([like this]).
DEFINE [NEW]
This must be present in any module which will be using any if the
gradutil services. The instantiating procedure must use the
NEW keyword. Any child procedures should omit the NEW keyword or they will
start another instance of gradutil.
CLEAN_UP
This must be invoked by the procedure that created the current instance of
gradutil. 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!
SET PRIMARY-PERIOD
grading-period
This service is used to set the grading period being used for subsequent
services so we weren't always passing a buffer around. It implicitly sets the
building so that we could know when a course if from the current building or
not. It must be invoked before any other services are used.
SET COURSE
master-schd
Used only when dealing with groups of grades from a specific course. If not
used, the the building data from PRIMARY-PERIOD is used. If you are
doing something that has the scope of the entire building (like the grades
area or printing a report card), you shouldn't bother with this. If you are
doing something that is specific to a course (like printing grade scan sheets
or verification reports), you should change this as you process each course.
SET GRADING-POLICY policy
Used to constrain grade being passed and returned by
gradutil to a specific grading policy. Usually, the
grading policy is determined on an individual course/schedule
basis. This will override the course/schedule setting and force all
interactions with gradutil to be of the passed
grading policy.
Supported graing policies are 'Letter', 'Pass/Fail' or 'Numeric'. To cause gradutil to return to honoringthe grading policy of the individual course/schedule, pass a grading policy of ? (NULL, not a quoted question mark).
GET PERIOD-LABELS
start
end
short?
periodlabels
Returns a list of mark labels for the range of grading periods inclusive of
start and end. short? controls whether the shorter or
longer mark labels are used. periodlabels is a comma delimited list
returned with the mark labels for the period range. These labels are all per
the 'primary' building, so this is best suited for listers or column headings.
GET PERIOD-MARKS
stu-schedule
start
end
periodmarks
What PERIOD-LABELS does for columnar labels, PERIOD-MARKS
does for a list of grades for a given course. It will pass back as many
entries as there are needed for the grades of the course, but never more than
what was passed back by PERIOD-LABELS (it might pass back less if the
trailing marks would all be blank).
GET COURSE-ENABLED
master-schd
enabled?
Passed a master-schd record, returns TRUE if the course has at least
one mark enabled for the primary grading period.
GET STUDENT-MARK-LABELS
stu-grade
short?
marklabels
Passed the stu-grade buffer, it will return a list of labels for those
marks. If short is TRUE, the short labels are returned. Otherwise,
the verbose labels are returned. Labels are returned as a comma delimited
list in marklabels
GET STUDENT-MARK-IDENTS
stu-grade
markidents
Passed a stu-grade record, this would return a comma delimited list of
mark identifiers that are enabled for the course given the current building
and grading period (suitable for use with the SET/GET STUDENT-MARK services).
Marks identifiers are returned in a numeric strings and may be negative
if the mark is considered a 'Required' mark. Mark identifiers are simply
numbers used within gradutil for referencing location of
marks. These should be used only for calling other gradutil
services. By themselves, they mean nothing.
GET MARK-IDENT
grading-mark
markident
This will take a passed grading-mark record and translate it
into an ident string that be used with SET/GET STUDENT-MARK-GRADE. The
purpose behind this is for use when you need to access a specific mark
from a student or students and don't want to parse through the normal list.
The return ident is just like the idents returned by GET STUDENT-MARK-IDENTS, but only one mark is described. The resultant mark is stable in that once fetched it can be used repeatedly until you need to change the primary grading-period (i.e. it doesn't have to be called between each student unless there is such a change).
If the passed grading mark is not enabled for the primary grading-period, the returned mark ident will be ? (NULL).
GET STUDENT-MARK-GRADE
stu-grade
markident
marktext
Return the text for a given markident as passed back from the GET
COURSE-MARK-IDENTS. The identifier can be positive or negative, so you
needn't convert it before passing. A textual mark, based on the appropriate
building and course-level/marking format is returned in marktext and is
suitable for display.
GET STUDENT-MARK-GRADE-LEVEL
stu-grade
markident
gradebuff
Return a course-level-grade record in gradebuff for the passed
markident or the passed stu-grade buffer (as passed back
from the GET COURSE-MARK-IDENTS). The identifier can be
positive or negative, so you needn't convert it before passing. If
there is in fact a grade for the specified mark, the
course-level-grade record of that grade is returned. If there is no
grade, the buffer is cleared of any record and made NOT AVAILABLE.
SET STUDENT-MARK-GRADE
stu-grade
markident
marktext
ok?
Passed the given stu-grade record, a markident (positive or
negative) and the user entered text in marktext, we will try to save
the mark into the student record. If we are successfull, ok? is passed
back TRUE. If there is a problem, the grade isn't changed and FALSE is returned.
Typical reasons for failure are
You can 'clear' a mark by passing an empty string in marktext. This will fail if the specified mark is required (and cannot be set to blank). It can also fail if the mark is disabled.