Documentation for sortutil

sortutil will produce a key file ( sortfile) which has a list of all the records meeting a users selective criteria in the users chosen sort order. A 'StuRecID' points back to a specific record. Which record depends on the QUERY_TYPE (discussed below).

The following sections are available:

• Overview of sortutil and how to use it
• A sortutil API reference
• A list of support sort field/tags
• A definition and explanation of the returned sort file

DEFINE {NEW}
Define shared temp-table and init sortutil

SET DATE effective_date
Sets the effective date sortutil should use for extracting/selecting records. Many sortutil sort/select options are 'time sensitive' in that depending on when a extraction is done for, the result for the student may change. The 'Enrolled' selective is a prime example of this.

SET DATE will establish the date sortutil uses to perform checks and sorts. If you don't dall SET DATE, then todays date, as extracted from 'menu-date' is used.

SET BLDG buff
Set the year/building for extract based on passed building buffer

SET QUERY_TYPE
Set type of query to extract on. Options are:

• STUDENT - Returns 'stu-year' RECID in StuRecID
• REQUESTS - Returns 'stu-request' RECIDs
• SCHEDULE - Returns 'stu-schedule' RECIDs
• BEHAVIOR - Returns 'stu-behave' RECIDs
• HONOR-ROLL - Returns 'stu-honor-roll' RECIDs
• TRANSCRIPT - Returns 'stu-transcript' RECIDs

All query types automatically inherit the STUDENT query type (except, of course, the STUDENT query type itself).

For more information of the sort/select fields available with each query type, please see the Query Type Tag Listing.

SET NO_USER_SELECT
Disable user choosable selectives

SET NO_USER_SORT
Disable user choosable sorts

SET ENABLE_BREAKS [PAGE_BREAKS]
Enable support for user breaks. When so enabled, the user will be able to mark selected sort fields with a 'B' character. Those fields so marked will cause the breaking mechanism of sortutil to kick in and detect where those breaks are. Any record that is part of a break will cause the appropriate break flags in the SortFile temp table to be set. A field marked with a break flag can be cleared by the user typing a space character in.

If PAGE_BREAKS is included, support allowing the user to select page breaks (as well as regular breaks) is enabled. This is manifested by having a third option for the user. Usually, they can mark a sort field with a 'B' (for a break) or space (to clear a break). In addition, with PAGE_BREAKS selected, they can enter a 'P' to indicate a page break. Other than causing an additional flag to be set in the SortFile temp table, the act exactly the same (and have the same effect/set the same flags) as a normal break.

Page breaks are, of course, up to your program to implement. Whenever a break occurs that is related to a page break, the 'PageBreakFlag' field is set in the SortFile temp table. Other than this one distinction, page breaks behave exactly as normal breaks.

SET SCAN_BATCH buff
For Scan form related extractions. Pass a scan-form-batch record that will be used for the sorts & selectives. Only needed for scan form related sorts

SET SCAN_DATASET #
For scan form related extractions. Pass an integer which represents which scan dataset the extraction will depend on.

SET GRADING_PERIOD buff
For grading period/report card oriented extractions. Pass a grading-period buffer that will be used for the sorts and selections.

SET TRANSCRIPT yearbuff trannamebuff
For transcript related oriented extractions. Pass a school year buffer and a transcript-name buffer. Only students who have the passed transcript (with at least one year of records and one course) and are enrolled in the passed year are printed (enrolled means their status code has include-transcript set true.

SET REQUIRE_SORT tag TOP|BOTTOM breakflag [pageflag]
Marks a field as required for sorting. The field will not appear in the user choosable list of fields. The TOP/BOTTOM indicates the field should be prefixed or appended to the sort list. If there are multiple TOP or BOTTOM fields, they will appear in the order they were added. 'breakflag' is a logical value and should be set TRUE if this field should be a 'break' sort field

If pageflag is passed (it is optional), it is a logical value that indicates if the field should be treated not only as a break, but as a page break. Note that if you pass this true, then the field becomes a break field, even if 'breakflag' is passed false.

For more info on page breaks, look over the info for SET ENABLE_BREAKS

SET REQUIRE_SELECTIVE tag negateflag
Marks a field as a required selective. The field will not appear in the user choosable list of fields. If 'negateflag' is TRUE, the selective will be reveresed (i.e. if you had a selective grade range, only students IN the range would be chosen. If 'Negate' only students NOT IN the range would be chosen)

GET RECORD_CNT reccnt
Pass back the # of selected records in reccnt

GET SORT_FLD_CNT fldcnt
Pass back the # of user-chosen sort fields is fldcnt

GET SELECT_FLD_CNT fldcnt
Pass back the # of user-chosen selective fields in fldcnt

GET SORT_FLD_TAG fldnum sorttag
Returns the tag name for the passed sort field #

GET SORT_FLD_DESC fldnum sortdesc
Returns the descriptive name of the sort field #

GET SORT_FLD_BREAK fldnum breakflag [pageflag]
Returns Yes/No is the passed sort field # is a break. If you pass the optional pageglag parameter, it is set TRUE is the field is not only a break field, but a page break field.

GET SELECT_FLD_TAG fldnum selecttag
Return the tag for a given selective field

GET SELECT_FLD_DESC fldnum selectdesc
Return the descrtiption for the selective field

GET SELECT_FLD_RANGE fldnum lowrange highrange
Return the low/high range for a passed selective field. The low and high ranges are returned as character strings.

QUERY_USER
Query the user for sort/selection info. Returns TRUE if user canelled

EXTRACT
Extract the records. Returns TRUE if user cancelled Parm #2 can be 'NO_BREAKS' to supress setting of user breaks.

MARK_BREAKS
Can be used to (re)evaluate the break criteria for the last extract command.

CLEAN_UP
Must execute done. You must execute this, so be sure all your cleanup paths exit through it.

The temp-table SortFile is a shared temp-table and the way that sortutil communicates the resultant record list back to you. Typically, you run this file in order by it's index. Each record is returned in the order sorted by the user selections. Information about breaks, the particular keys of a sorted record, etc are all available along with the most important part - the RECID of the target record.

There are some arrays in the SortFile. As we don't want to put limits on anything, please use the constants MAX_SORT_FLD and MAX_SELECT_FLD as array limits - don't use hard coded numbers.

The layout of the SortFile is:

    TEMP-TABLE SortFile NO-UNDO
      FIELD StuRecID       AS RECID
      FIELD FirstRecord    AS LOGICAL
      FIELD LastRecord     AS LOGICAL
      FIELD SortKey1       AS CHARACTER
      FIELD SortKey2       AS CHARACTER
      FIELD SortKey3       AS CHARACTER
      FIELD SortKey4       AS CHARACTER
      FIELD SortKey5       AS CHARACTER
      FIELD SortKey6       AS CHARACTER
      FIELD SortKey7       AS CHARACTER
      FIELD SortKey8       AS CHARACTER
      FIELD SortKey9       AS CHARACTER
      FIELD SortKey10      AS CHARACTER
      FIELD SortItemKey    AS CHARACTER  EXTENT {&MAX_SORT_FLD}
      FIELD BreakFlag      AS LOGICAL
      FIELD PageBreakFlag  AS LOGICAL
      FIELD FirstOfFlag    AS LOGICAL
      FIELD LastOfFlag     AS LOGICAL
      FIELD PageBreak      AS LOGICAL    EXTENT {&MAX_SORT_FLD}
      FIELD BreakFirstOf   AS LOGICAL    EXTENT {&MAX_SORT_FLD}
      FIELD BreakLastOf    AS LOGICAL    EXTENT {&MAX_SORT_FLD}
      INDEX SortKey IS PRIMARY
        SortKey1
        SortKey2
        SortKey3
        SortKey4
        SortKey5
        SortKey6
        SortKey7
        SortKey8
        SortKey9
        SortKey10.

Detail of the fields

• StuRecID is the actual RECID() of the target record. This is often a stu-year RECID, but depending on the sort, it could be a stu-behave, stu-honor-roll or stu-transcript RECID. Consult the QUERY_TYPE table for more detail.

• FirstRecord is a logical which is set only for the first record in the returned list of records. This is set regardless of whether breaks are enabled or not.

• LastRecord is a logical which is set only for the very last record in the returned list of records. This is set regardless of whether breaks are enabled or not.

• SortKey1 - SortKey10 are the individual key components used to construct the index used for sorting the returned records. In combination with the GET SORT_FLD and related services, you can look at the components that made up the sort.

  For example, if a sort was run by gender, grade and student name, then SortKey1 would hold a sortable text version of the related students gender, SortKey2 would hold a sortable, text version of the students grade and SortKey3 would hold a sortable, text version of the student name.

  One thing to be aware of is that the 'sortable, text version' of a field might not be one that matters much to a human being. For example, when the students grade is selected for sorting, the grade-catalog.grade-order field is used for creating the text version as that field is the sort order for grades, not the grade names themselves.

  This is usually pretty easy to get around since if you really are interested, you can find out which (if any) sort field the grade was selected for and look the grade-catalog record up on your own after fetching the related stu-year record.

• SortItemKey is an array that mirrors the SortKeyn fields. This is done to make programatic access easier. For example, SortKey3 is the same as SortItemKey[3].

• BreakFlag is a logical which indicates if one or more the break flags 'PageBreakFlag', 'BreakFirstOf', 'BreakLastOf', 'FirstOfFlag' or 'LastOfFlag' are set. It is generally used as a quick test to see if the record warrants further examination. This field can only be set if SET ENABLE_BREAKS has been executed.

• PageBreakFlag indicates that one or more of the breaks for this record were initiated by a break field that was flagged as a page break field.

• FirstOfFlag is a summary flag that indicates that one or more of the BreakFirstOf flags has been set. This flag is used to indicate a 'FIRST-OF()' break has occured. The program may find out exactly which field broke (there can be more than one) by interrogating the 'BreakFirstOf' array.

• LastOfFlag is a summary flag that indicates that one or more of the BreakLastOf flags has been set. This flag is used to indicate a 'LAST-OF()' break has occured. The program may find out exactly which field broke (there can be more than one) by interrogating the 'BreakLastOf' array.

• PageBreak is an array that indicates exactly which sort field components (defined y SortItemKey[] or SortKeyn) is responsible for a page break.

• BreakFirstOf is an array that indicates exactly which sort field components (defined by SortItemKey[] or SortKeyn) is responsible for a break. Note that all fields 'lower' than a break field are marked as 'breaking' too (i.e. if BreakFirstOf[6] is set due to a break of it's sort key, items 1-5 will also be set).

• BreakLastOf is an array that indicates exactly which sort field components (defined by SortItemKey[] or SortKeyn) is responsible for a break. Note that all fields 'lower' than a break field are marked as 'breaking' too (i.e. if BreakLastOf[6] is set due to a break of it's sort key, items 1-5 will also be set).

• SortKey is the index built of the individual index components and used to provide an order when iterating through the SortFile table.

Some tags can only be used for sorting, some only for selection. Other tags are 'hidden'. A hidden tag will never be presented to the user for selection, but can only be selected using the SET REQUIRE_SORT service.

All query types automatically get the fields/tags associated with the STUDENT query type (except for the STUENT query type itself).

Supported Tags for STUDENT:

  Tag Name               Srt Sel Hdn Description                            
  ---------------------- --- --- --- -------------------------------------- 
  STU_NAME               Yes No  No  Student Name                           
  STU_ID                 Yes No  No  Student ID #                           
  STU_GRADE              Yes Yes No  Students Grade                         
  STU_STATUS             Yes Yes No  Status code                            
  STU_HOME_ROOM          Yes Yes No  Home Room                              
  STU_ETHNIC             Yes Yes No  Ethnic Code                            
  STU_COUNSELOR          Yes Yes No  Counselor                              
  RANDOM                 Yes No  No  Randomizer                             
  STU_ENROLLED           No  Yes No  Student Enrolled?                      
  STU_GENDER             Yes Yes No  Gender                                 
  TEACHER_FOR_PERIOD     Yes No  No  Teacher for selected period
  COURSE_FOR_PERIOD      Yes No  No  Course for a selected period
  ROOM_FOR_PERIOD        Yes No  No  Room for a selected period
  RQST_SCAN_RTND         No  Yes Yes Returned Request Sheets                
  RQST_VRFY_RTND         No  Yes Yes Returned Request Verification          

Supported Tags for BEHAVIOR:

  Tag Name               Srt Sel Hdn Description                            
  ---------------------- --- --- --- -------------------------------------- 
  BEHAVE_CODE            Yes Yes No  Behavior code of an incident
  BEHAVE_DATE            Yes Yes No  Date of behavior incident
  BEHAVE_PRSN            Yes Yes No  Person reporting the incident
  ACTION_CODE            Yes Yes No  Action code for the incident
  ACTION_DATE            Yes Yes No  Date of disposition for the incident
  ACTION_PRSN            Yes Yes No  Person reviewing the incident

Supported Tags for HONOR-ROLL:

  Tag Name               Srt Sel Hdn Description                            
  ---------------------- --- --- --- -------------------------------------- 
  HONOR_ROLL             Yes Yes No  Name of the honor roll

Supported Tags for TRANSCRIPT:

  Tag Name               Srt Sel Hdn Description                            
  ---------------------- --- --- --- -------------------------------------- 
                              (none)

Last updated March 4, 1996