Documentation for tranutil

tranutil is a collection of routines for working with student transcript information. Utilities are provided for extracting labels, extracting grades and setting grades into a student record.

There are two primary flavors of calls to tranutil - trancriptable grades and the entire grade set for a course. The transcriptable version return only grades that are for marks flagged as 'transcript' marks. This tends to be a summary of the students course achievment and what is often passed on to the outside world (colleges, employers, etc). The other flavor of services allows you to work with the entire set of grades for a course. This usually includes period grades, exams, average grades, etc.

tranutil hides the details of how various grades are used for a given course. As such, you should never directly manipulate the stu-transcript-mark records - only use tranutil. If the underlying format of the grade storage changes, you will be safely isolated.

tranutil requires that when a stu-transcript-course record is passed to it, the school year, building, course and course level are all set. A record with any of these items blank may cause tranutil to fail.

Implementation

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 tranutil services. The instantiating procedure must use the NEW keyword. Any child procedures should omit the NEW keyword or they will start another instance of tranutil.

CLEAN_UP
This must be invoked by the procedure that created the current instance of tranutil. 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 GRADING-POLICY policy
Used to constrain grade being passed and returned by tranutil 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 tranutil to be of the passed grading policy.

Supported graing policies are 'Letter', 'Pass/Fail' or 'Numeric'. To cause tranutil to return to honoring the grading policy of the individual course/schedule, pass a grading policy of ? (NULL, not a quoted question mark).

GET TRAN-LABEL-LIST year-id bldg-id label-list
Returns a list of labels for the transcriptable marks as defined for the passed school year and building. The school year and building are passed as ID values. label-list is returned as a comma delimted list of labels for the transcriptable marks.

GET TRAN-IDENT-LIST year-id bldg-id ident-list
Returns a list of 'idents' for the transcriptable marks as defined for the passed school year and building. The Year and building are both passed as ID values. The return ident-list is a comma delimited list of ident values for the transcriptable marks.

Idents are used when you need to access a specific label or grade or need to update a specific grade. If you look at them, they may look numeric, but you would be putting yourself into a bad spot if you tried to treat them as numbers. The interpretation of them may change in the future.

All you know about idents is the Nth ident in a list uniquely identifies the Nth label returned from TRAN-LABEL-LIST or the Nth grade returned by TRAN-GRADE-LIST. If you are not planning on updating the grades or doing some really odd processing, you will probably never need to use idents.

GET TRAN-GRADE-LIST stu-tran-course grade-list
Returns a list of 'grades' for the transcriptable marks as defined for the passed stu-transcript-course buffer. The passed 'stu-transcript-course' buffer must have the building, stu-seq, course-id, course-level-id and school-year-id set before being used for this service. The return grade-list is a comma delimited list of grades values for the transcriptable marks. If a grade was not recorded or available, a blank or empty entry in the list is still reserved to keep the association with the labels or idents returned by the TRAN-LABEL-LIST and TRAN-IDENT-LIST services.

GET TRAN-DISPOSITION-LIST stu-tran-course disposition-list
Returns a list of 'dispositions' for the transcriptable marks as defined for the passed stu-transcript-course buffer. The passed 'stu-transcript-course' buffer must have the building, stu-seq, course-id, course-level-id and school-year-id set before being used for this service. The return disposition-list is a comma delimited list of disposition values for the transcriptable marks. If a mark doesn't use a disposition then a value of "" if returned for the mark. If a mark uses a disposition, but it hasn't been set then "?" will be returned.

GET MARK-LABEL-LIST year-id bldg-id label-list
Returns a list of labels of all the marks for the passed school year and building. The school year and building are passed as ID values. label-list is returned as a comma delimted list of labels for all the marks associated with the year.

Unlike TRAN-LABEL-LIST, this will return all marks, including the period marks, exam or average marks, transcriptable mark and final marks. This is generally useful only within the district - the outside world doesn't usually see these.

GET DISPOSITION-IDENT-LIST year-id bldg-id ident-list
Returns a list of 'idents' of all the marks with enabled dispositions for the passed school year and building. The Year and building are both passed as ID values. The return ident-list is a comma delimited list of ident values of all enabled marks possible for the year.

Idents are used when you need to access a specific label, grade or disposition, or need to update a specific grade. If you look at them, they may look numeric, but you would be putting yourself into a bad spot if you tried to treat them as numbers. The interpretation of them may change in the future.

GET MARK-IDENT-LIST year-id bldg-id ident-list
Returns a list of 'idents' of all the marks for the passed school year and building. The Year and building are both passed as ID values. The return ident-list is a comma delimited list of ident values of all marks possible for the year.

Idents are used when you need to access a specific label or grade or need to update a specific grade. If you look at them, they may look numeric, but you would be putting yourself into a bad spot if you tried to treat them as numbers. The interpretation of them may change in the future.

All you know about idents is the Nth ident in a list uniquely identifies the Nth label returned from MARK-LABEL-LIST or the Nth grade returned by MARK-GRADE-LIST. If you are not planning on updating the grades or doing some really odd processing, you will probably never need to use idents.

GET MARK-GRADE-LIST stu-tran-course grade-list
Returns a list of 'grades' of all the marks for the passed stu-transcript-course buffer. The passed 'stu-transcript-course' buffer must have the building, stu-seq, course-id, course-level-id and school-year-id set before being used for this service. The return grade-list is a comma delimited list of grades values of all marks for the school year associated with the passed buffer. If a grade was not recorded or available, a blank or empty entry in the list is still reserved to keep the association with the labels or idents returned by the MARK-LABEL-LIST and MARK-IDENT-LIST services.

GET MARK-DISPOSITION-LIST stu-tran-course disposition-list
Returns a list of 'dispositions' for the marks for the passed stu-transcript-course buffer. The passed 'stu-transcript-course' buffer must have the building, stu-seq, course-id, course-level-id and school-year-id set before being used for this service. The return disposition-list is a comma delimited list of disposition values for the all marks for the school year associated with the passed bufffer. If a mark doesn't use a disposition then a value of "" if returned for the mark. If a mark uses a disposition, but it hasn't been set then "?" will be returned.

GET IDENT-LABEL year-id bldg-id ident the-label
Returns a specific label based on the passed 'ident' as it's applies to the passed year and building. The school year and building are passed as ID values. 'ident' is a string with a SINGLE identifier. Other than extracting identifiers from a list of identifiers, you should never try to interpret an identifer. Treat it as a black box or you'll be very sorry. The resulting label is returned in 'the-label'

GET IDENT-GRADE stu-tran-course ident the-grade
Returns a specific, single 'grade' for the passed stu-transcript-course buffer and the passed 'ident'. The passed 'stu-transcript-course' buffer must have the building, stu-seq, course-id, course-level-id and school-year-id set before being used for this service. The 'ident' is a SINGLE identifier extracted from a list of identifiers previously returned from the tranutil service. The returned grade may be blank if there was no corrosponding grade for the passed course.

GET IDENT-DISPOSITION stu-tran-course ident the-disposition
Returns a specific, single 'disposition' for the passed stu-transcript-course buffer and the passed 'ident'. The passed 'stu-transcript-course' buffer must have the building, stu-seq, course-id, course-level-id and school-year-id set before being used for this service. The 'ident' is a SINGLE identifier extracted from a list of identifiers previously returned from the tranutil service. The returned disposition may be blank if there was no corrosponding disposition for the passed course.

GET IDENT-GRADE-LEVEL stu-tran-course ident course-level-grade
This service is identical to IDENT-GRADE, except that instead of returning a textual grade, it returns a 'course-level-grade' buffer. This can be useful when you need to fetch other data related to a grade (such as grade points, rankability, etc). If there is no grade for the passed course, the returned buffer will be empty (i.e. NOT AVAILABLE).

GET IDENT-COURSE-DISPOSITION stu-tran-course ident course-disposition
This service is identical to IDENT-DISPOSITION, except that instead of returning a textual disposition, it returns a 'course-disposition' buffer. This can be useful when you need to fetch other data related to a disposition. If there is no disposition for the passed course, the returned buffer will be empty (i.e. NOT AVAILABLE).

SET IDENT-GRADE stu-tran-course ident the-grade okay
Used to set or modify grades for a passed stu-transcript-course buffer using the passed 'ident'. The passed 'stu-transcript-course' buffer must have the building, stu-seq, course-id, course-level-id and school-year-id set before being used for this service. The 'ident' is a SINGLE identifier extracted from a list of identifiers previously returned from the tranutil service. 'the-grade' must either be a valid grade for the given course or be NULL (a single, unquoted question mark) to write an empty grade for a mark. 'okay' is returned TRUE if the grade was successfully written or FALSE if there was an error. The most typical (>99.99% of the time) is a bad or unknown grade being passed. A bad 'ident' can also cause the problem.

SET IDENT-DISPOSITION stu-tran-course ident the-disposition okay
Used to set or modify dispositions for a passed stu-transcript-course buffer using the passed 'ident'. The passed 'stu-transcript-course' buffer must have the building, stu-seq, course-id, course-level-id and school-year-id set before being used for this service. The 'ident' is a SINGLE identifier extracted from a list of identifiers previously returned from the tranutil service. 'the-disposition' must either be a valid grade for the given course or be NULL (a single, unquoted question mark) to write an empty disposition for a mark. 'okay' is returned TRUE if the disposition was successfully written or FALSE if there was an error. The most typical (>99.99% of the time) is a bad or unknown disposition being passed. A bad 'ident' can also cause the problem.

GET COURSE-ATTRIBUTES stu-tran-course attr-list
This service returns a list of attributes that gives some information about the course passed. Whenever possible, you should rely on these attributes rather than trying to devine the information yourself.

Possible attributes are:

• AUTOMATIC - course is automatically maintained by SPM. Do NOT allow the user to edit the grades, attendance data, credits, grade points or anything other than the comments. Anything the user changes will be wiped out next time transcripts are updated from the students grades. This is mutually exclusive with 'MANUAL'.

• MANUAL - course was created by hand and does not exist in the students schedule. As such, the user should be allowed to edit the grades, attempted credits and comments. Earned credits and grade points are calculated and are always read-only. This flag is mutually exclusive of 'AUTOMATIC'

• MASTER - the course described in the passed buffer actually exists in the master schedule. This means you can extract additional information about the meetings of the course directly from the master schedule. This flag is mutually exclusive of 'CATALOG'.

• CATALOG - the course described in the passed buffer only exists in the course catalog. This means the section number, if any, is ficticious and should not be used for typical master schedule related checks and lookups. This flag is mutually exclusive of 'MASTER'.

GET YEAR-ATTRIBUTES stu-tran-year attr-list
This service returns a list of attributes that gives some information about the transcript year passed. Whenever possible, you should rely on these attributes rather than trying to devine the information yourself.

Possible attributes are:

• AUTOMATIC - The year is created and maintained via the transcript builder. The builder will leave manual entries alone, but any entries that corrospond to a students scheduled courses for that year will be rewritten whenever the transcript data is recalculated.

• MANUAL - year was created by hand (not via an automatic process) and there are no existing records associated with a students schedule for that year.

Last update: January 20, 1996