Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Description

V119 is an Assembly Language commuter module that supports eight different types of operations depending on the first parameter passed. V119 can be used to

...

Data that is not part of the sort string (called satellite data) can be included at the end of the fields to be sorted. The most common example of satellite data is a record key.

Syntax

V119 (FUNCTION_CODE, SORT_FILE, BYS, JUSTS, WORK, FLAG)

16-bit OpenInsight Remarks

V119 can sort strings up to a total string length of 65,533 bytes. If the data to be sorted exceeds this length, V119 can be used to create and merge individual blocks of sort data. The blocks are temporarily stored in an operating system file.

...

You can choose any operating system file you wish to hold blocks of data. However, the system function Get.Sort.File( ) can be used to return a unique filename for this purpose. Get.Sort.File( ) uses the environment setting for the sort path, and creates a temporary sort filename that includes the station number.

Parameters

V119 accepts a total of six parameters. The first parameter is a one-letter code that determines what V119 is to do. It is the only parameter that is always required.

...

Function CodeDescription
D

causes the external sort file to be deleted.

ParameterDescription
SORT_FILESet to the drive, path, and filename of the operating system file.
BYSNull.
JUSTSNull.


E

Indicates an extract operation to return satellite data from the sort array. This is useful when the sort operation has been performed with record keys as satellite data. A list of record keys is then returned.

ParameterDescription
SORT_FILENull.
BYSNull.
JUSTSNull.
WORKA dynamic array in the same format as in the sort operation. WORK returns the last fields of each record separated by field marks.
FLAGNull.


I

Initializes an operating system file that is used to hold sort data temporarily while sorting.

ParameterDescription
SORT_FILESet to the drive, path, and filename of the operating system file.
BYSNull.
JUSTSNull.
WORKNull.
FLAGZero if there was a problem in file i/o and non-zero if the operation was successful.


L

Indicates a list operation. This operation is similar to the Extract operation. This operation gets the keys back from the merged external sort file in blocks of 32K.

ParameterDescription
SORT_FILEThe drive, path, and filename of the external sort file.
BYSNull.
JUSTSNull.
WORKPassed null. Returns a 32K block of field mark delimited of keys.
FLAGZero if there was a problem in file i/o and non-zero if the operation was successful.


M

Indicates a merge operation. This operation is used to fully sort the external sort file after all of the sorted blocks of data have been written to it.

ParameterDescription
SORT_FILEThe drive, path, and filename of the external sort file.
BYSThe same value as when the data was sorted during the Sort operation.
JUSTSThe same value as when the data was sorted during the Sort operation.
WORKNull.
FLAGZero if there was a problem in file i/o and non-zero if the operation was successful.

Note: This operation immediately doubles the size of the operating system file. If disk space is tight, this is the most vulnerable operation.

S

Sorts an array of records.

ParameterDescription
SORT_FILENull.
BYSA or D for each sort field. A represents an ascending sort for the field and D represents a descending sort. For example, if BYS equals ADA, V119 does an ascending sort on the first field in WORK, descending on the second field, and ascending on the third field even though there may be satellite data.
JUSTSWorks the same way as BYS but refers to the justification of each sort field and consequently whether an alpha or numeric sort is performed. L and R are the only valid characters representing left and right justification, respectively.
WORKA dynamic array of data to be sorted. Each piece of data to sort is separated by a record mark (ASCII 255). A final record mark is required, but not a beginning one.

If a multiple level sort is to be performed, fields are defined within each record separated by field marks (ASCII 254). The first field is sorted first (the primary sort), the second field is sorted next, and so forth.

There may be fields in the record that are not sorted (satellite data), because only as many fields will be sorted as there are characters in the BYS or JUSTS parameters. All sort fields must be contiguous at the beginning of each record. All satellite data must be contiguous at the end of each record. There is no way to skip the sorting of a field.

WORK returns in the same format as it was passed, but the records are in sorted order

FlagNull


V

Denotes a value operation. This operation is like the List operation in that it returns data in 32K blocks from an external sort file after it has been merged. However, the data returned is like that of a sort operation rather than an extract operation.

ParameterDescription
SORT_FILEThe drive, path, and filename of the external sort file.
BYSNull.
JUSTSNull.
WORKNull when passed. Returns a 32K block of sorted records by whatever criteria were specified when the external sort file was merged.
FLAGReturns zero if there was a problem in file i/o and non-zero if the operation was successful.


W

Indicates a write operation. This is used to write a block of sort data to the temporary sort file.

ParameterDescription
SORT_FILEThe drive, path, and filename of the operating system file.
BYSNull.
JUSTSNull.
WORKA dynamic array to write. This is most likely the return value of WORK from a sort operation. Thus, the external sort file becomes a series of sorted blocks of data.
FLAGReturns zero if there was a problem in file i/o and non-zero if the operation was successful.


See Also

Get.Sort.File()

Example: Sorting by One Column

Code Block
/* Sort by Customer Number (Right Justified), Ascending , then Descending */
 
declare subroutine V119
/* Customer Number, Region, Customer Name, Total Sales */
Record1 = "42" : @fm : "West" : @fm : "Acme Corporation"    : @fm : 5000
Record2 = "1"  : @fm : "East" : @fm : "Zeta Corporation"    : @fm : 200
Record3 = "3"  : @fm : "East" : @fm : "Midland Corporation" : @fm : 3500
Record4 = "2"  : @fm : "West" : @fm : "Orland Corporation"  : @fm : 300
SortData = Record1 : @rm : Record2 : @rm : Record3 : @rm : Record4 : @rm
 
/*  ascending sort  */
Bys   = 'A'
Justs = 'R'
V119('S', '', Bys, Justs, SortData, '')
 
/*  descending sort */
Bys  =  'D'
V119('S', '', Bys, Justs, SortData, '')

Example: Sorting by Two Columns

Code Block
/* Sort by Region (Ascending-Left), then Total Sales (Descending-Right) */
 
declare subroutine V119
/* Region, Total Sales, Customer Number, Customer Name */
Record1 = "West" : @fm : 5000 : @fm : "42"     : @fm : "Acme Corporation"
Record2 = "East" : @fm :  200 : @fm : "1"      : @fm : "Zeta Corporation"
Record3 = "East" : @fm : 3500 : @fm : "3"      : @fm : "Midland Corporation"
Record4 = "West" : @fm :  300 : @fm : "2"      : @fm : "Orland Corporation"
SortData = Record1 : @rm : Record2 : @rm : Record3 : @rm : Record4 : @rm
 
Bys   = 'AD'
Justs = 'LR'
V119('S', '', Bys, Justs, SortData, '')

Example: External Sort Logic

Code Block
/*   External sort  */
declare subroutine V119 , msg
declare function Get.Sort.File                                                       
$insert logical
 
/* Same data as Sorting by Two Columns Example */
Record1 = "West" : @fm : 5000 : @fm : "42"     : @fm : "Acme Corporation"
Record2 = "East" : @fm :  200 : @fm : "1"      : @fm : "Zeta Corporation"
Record3 = "East" : @fm : 3500 : @fm : "3"      : @fm : "Midland Corporation"
Record4 = "West" : @fm :  300 : @fm : "2"      : @fm : "Orland Corporation"
SortData = Record1 : @rm : Record2 : @rm : Record3 : @rm : Record4 : @rm
Bys   = 'AD'
Justs = 'LR'
 
flag = ''
/*  get a unique sort file name and initialize it */
SortFile = Get.Sort.File()
V119('I', SortFile, '', '', '', flag)
IF flag else
   TEXT = 'Error initializing sort file.'
   call msg(@window, TEXT)
  return FALSE$
END
 
/*  write the data to SortFile.  May be called multiple times
if data > 32K. Need to write in chunks.      */
V119('W', SortFile , '', '', SortData, flag)
if flag else
   TEXT = 'Error writing to sort file.'
   msg(@window, TEXT)
   gosub delete_sortfile
   return FALSE$
end
 
/*  Use the 'M' argument to sort the external file, after data has been written. */
V119('M', SortFile , Bys , Justs , '', flag)
 
/*  Use the 'L' argument to retrieve a list of sorted keys.
Use the 'E' argument to retrieve the last field, in sorted order.
*/
V119('L', SortFile , Bys , Justs , SortData , flag)
V119('E', SortFile , Bys , Justs , SortData , flag)
 
/*  Don't forget to delete the sort file when done!  */
Delete_SortFile:
V119('D', SortFile , '', '', '', flag)
IF FLAG ELSE
  TEXT = 'Error deleting sort file ': SORT_FILE
  call MSG(@window, TEXT)
END

...