Prof.Dr.Godfried-Willem RAES

<GMT> & Harmony Library Reference Manual: Module 6: File Management Functions

 CHAPTER 6: HARM_FIL

Procedures for file I/O

Files: all included now in g_file.dll

The functions contained in this module are not required for the functionality of any other module in the harmony library. They are provided as an interface to file handling: writing and reading score data, conversion to standardmidi-file format etc., as well as for reading <GMT> specific initialisation data from ascii files.

Harmony file functions:

The harmony related file-handling procedures and functions often require that the user opens the file in his code prior to calling these functions and procedures. Only the unique number under which the file was opened should be handed to the procedures and functions. The functions use a binary file-format, explained further, wherein all events get an absolute time-stamp with a cs (hundreths of seconds) resolution. The timestamping is part of the file-writing procedures and guarantees that files are always arranged in chronological order, unlike the standard midi-file coding which compromizes real-time file handling seriously. Conversion to midi-file format is possible using the procedures provided, but this process should never be part of real-time code, let alone multitasking code design.

GMT- file functions:

Used for reading application / composition specific initialisation files. The required keywords are explained together with the functions. These functions reside in the DLL.

Alphabetical list of functions and procedures:

FUNCTION ReadHarFile& (H AS Harmtype, track%, filenumber%)

SUB Har2Mid (seqfilenr%, midfilenr%) [removed here, now in separate program file: H2M.EXE ]

WriteHar2File (H AS HarmType, Track%, Filenumber%)

ExistFile (f AS STRING) AS BYTE

SUB P2Har (H AS HarmType, i&, p%())

SUB ShowHarmFuz ()

SUB ShowMelFuz ()

FUNCTION mmioFOURCC (a$,b$,c$,d$) AS DWORD

SUB DeleteIfEmpty (f AS STRING)

Specific gmt file functions:

FUNCTION CreateDefaultIniFile () AS LONG (indexed)
FUNCTION ReadKeyFromFile (f AS STRING, keyword AS STRING) AS WORD(indexed)
FUNCTION ReadDiapasonFromFile (f AS STRING) AS SINGLE (indexed)
FUNCTION ReadAppDataFromFile (f AS STRING, App AS ApplicationType) AS LONG (indexed)
FUNCTION ReadAudioDataFromFile (f AS STRING,AudioFader() AS AudioFaderType) AS LONG (indexed)
FUNCTION ReadDaqParamsFromFile (f AS STRING, DAQparams AS DataAcquisitionParameters) AS LONG (indexed)
FUNCTION ReadFlagDataFromFile (f AS STRING, App AS ApplicationType) AS LONG (indexed)
FUNCTION ReadTaskDataFromFile (f AS STRING, App AS ApplicationType) AS LONG (indexed)
FUNCTION ReadCockpitControlDataFromFile (f AS STRING, App AS ApplicationType) AS LONG (indexed)
FUNCTION ReadMidiFlagsFromFile (f AS STRING) AS LONG (indexed, see also gmt_midi.html)
SUB ReadWaveFileListFromFile (f AS STRING, SampleList() AS ASCIIZ * 50) (indexed)
SUB ReadPatternSequencesFromFile (f AS STRING, BYREF PatternSeq() AS PatternSequenceType) (indexed o.k.)
SUB ReadMidiGroups (f AS STRING, BYREF MidiGearGroups() AS ASCIIZ * 15) (indexed o.k.)
SUB ReadMidiEquipmentChoices (f AS STRING, BYREF Meq() AS MidiEquipment) (indexed o.k.)

SUB ReadCockpitLabelsFromFile (BYVAL h AS LONG, Filenaam AS STRING, CockpitLayo AS CockpitLabels) (indexed)

Users guide

FUNCTION CreateDefaultIniFile () AS LONG

Creates a default "gmt.ini" file if on starting gmt, no gmt.ini file was found. You can edit this file using notepad or any other ascii editor, such as the PowerBasic editor itself.

FUNCTION ReadKeyFromFile (f AS STRING, keyword AS STRING) AS WORD

Retrieves and returns the numeric value as word found immediately after the keyword specified in the file passed by name.

FUNCTION ReadDiapasonFromFile (f AS STRING) AS SINGLE

Reads the tuning base used throughout both GMT and the harmony library and returns it as a floating point number. This function must be called on initialisation of the library since it also sets some other floating point constants the program needs (Pi, Pi2, dB calculation numbers... etc...). The keyword in the file can be any of these tokens: "DIAPASON", "PITCH", "[DIAPASON]", "[PITCH]", $PITCH

FUNCTION ReadAppDataFromFile (f AS STRING, App AS ApplicationType) AS LONG

Reads fields for the App structure used in a GMT application. Look into the Application type declaration for the fields. The string constants used as tokens can be found in gmt_kons.bi. This function internally calls ReadTaskDataFromFile f, App
ReadCockpitControlDataFromFile f, App , in this order before reading its own specific tokens. So you do not have to call abovementioned procs. separately.

FUNCTION ReadAudioDataFromFile (f AS STRING,AudioFader() AS AudioFaderType) AS LONG

The string constants for the tokens recognized by this function can be found in gmt_kons.bi

FUNCTION ReadDaqParamsFromFile (f AS STRING, DAQparams AS DataAcquisitionParameters) AS LONG

This procedure reads all relevant parameters for data acquisition hardware from the filename passed. It fills the fields of the DAQparams structure, documented and declared in GMT_type.bi. Samples can be found in bom.bi as well as in the code module gmt_ii.inc

FUNCTION ReadFlagDataFromFile (f AS STRING, App AS ApplicationType) AS LONG

Reads the flags to be set in the corresponding field for task-types from a file. The data block in the file must start with the $Flags_Start keyword (defined in gmt_kons.bi). The data block ends with the $Flags_End keyword. Note that the DLL has access to the pointers to the Task() structures.

FUNCTION ReadTaskDataFromFile (f AS STRING, App AS ApplicationType) AS LONG

Reads the data block starting with $TSK_START.
The is seaches following tokens and reads the appropriate fields:
$TSK_WRISEQ '"WRITE_SEQUENCE_TASK_NUMBER"
filling: App.WriteSeqScoreTaskNr
$TSK_RDSEQ '"READ_SEQUENCE_TASK_NUMBER"
filling: App.ReadSeqScoreTaskNr
$TSK_GLOBHAR '"GLOBAL_HARMONY_TASK_NUMBER"
filling: App.GlobalHarmonyTaskNr
$TSK_SHOWHAR '"SHOW_GLOBAL_HARMONY_TASK_NUMBER"
filling: App.ShowGlobalHarmonyTaskNr
$TSK_PROMIL '"PROMIL_TASK_NUMBER"
filling: App.PromilTaskNr
$TSK_KRONO '"RUNTIME_TASK_NUMBER"
filling: App.MTSpeedTaskNr
$TSK_MTSPEED '"MT_SPEED_TASK_NUMBER"
filling: App.RunTimeTaskNr
$TSK_WAVPLY '"WAVE_PLAY_TASK_NUMBER"
filling: App.WavePlayTaskNr
$TSK_DEBUG '"DEBUG_TASK_NUMBER"
filling: App.DebugTaskNr
The data block should end with the token: $TSK_END

FUNCTION ReadCockpitControlDataFromFile (f AS STRING, App AS ApplicationType) AS LONG

Reads the datablock delimited with the $COCKPIT keyword from the filename passed. This determines the number of sliders, up-down controlls etc. that appear in the cockpit window.

FUNCTION ReadMidiFlagsFromFile (f AS STRING) AS LONG

Reads the flags after the keyword $FlagSysEx (= "Receive_Sysex") into the appropriate type for the sysex procedure inside the DLL. If you use sysex, a call to this function is mandatory.

SUB ReadWaveFileListFromFile (f AS STRING, SampleList() AS ASCIIZ * 50)

This procedure reads a list of file-names for sample wave files used in an application into an array SampleList() passed by reference. The array is dimensioned in the procedure.

The keyword sought after can be any one of these:

• "NROFSAMPLEFILES","NR_OF_SAMPLEFILES","NROFSAMPLES"

SUB ReadPatternSequencesFromFile (f AS STRING, BYREF PatternSeq() AS PatternSequenceType)

Reads the data in a PatternSeq() structure array, dimensioned on return. You have to pass an empty array to the procedure. So you should do: REDIM PatternSeq(0 TO 0) AS GLOBAL PatternSequenceType, prior to calling this procedure.

The (hardcoded) keywords recognized are:

"NROFSEQUENCES"

"INPUTTEMPO"

"DUURTOLERANCE"
"NOOTTOLERANCE"
"VELOTOLERANCE"
"SEQNR"
"NRNOTES"
"SEQTEMPO"
"SEQNOOTDATA"
"SEQDUURDATA"
"SEQVELODATA"

SUB ReadMidiGroups (f AS STRING, BYREF MidiGearGroups() AS ASCIIZ * 15)

Called on initialisation of GMT to prepare the menus with appropriate choices.

SUB ReadMidiEquipmentChoices (f AS STRING, BYREF Meq() AS MidiEquipment)

Called on initialisation of GMT to prepare the menus with appropriate choices. The data block should start with the token $Midi_Start.

SUB ReadCockpitLabelsFromFile (BYVAL h AS LONG, Filenaam AS STRING, CockpitLayo AS CockpitLabels)

Reads the datablock delimited with the $COCKPIT keyword from the filename passed.

File handling procedures for HARM_FIL functions:

SUB DeleteIfEmpty (f AS STRING)

This procedure deletes the file passed by its filename if it contains zero bytes.

FUNCTION ExistFile (f AS STRING) AS BYTE

This function returns the constant defined as true (%True = 1) if the file passed in f could be found. The f string may contain a complete path. If the file could not be found, the function returns false. (0)

FUNCTION ReadHarFile& (H As HarmType, track%, fnr%)

This function returns the next time counter value in centisesonds (1/100"). At the same time it will return the harmony string for the specified track% in the filenumber passed in the H.vel field. Make sure the H-type variable has been dimensioned before calling the function. The function works sequentially. When the end of the file is reached for the track% given, the function returns -1. The resolution in cs may appear to be low at first sight, but do not forget that a single time-tick value may specify changes for up to 128 notes and any number of tracks. In this respect the resolution is way beyond the capabilities of midi-datatransfer anyway. Although the timing is expressed in absolute time values, the user has of course the full freedom of selecting different tempi in his own playback or read code.

Example:

OPEN "MyMusic.SEQ" FOR INPUT AS #1

DIM testhar AS HarmType

testhar.vel = STRING$(128, 0)

DO

tel& = ReadHarFile&(testhar, 0, 1)

IF tel& = -1 THEN EXIT DO

LOCATE 1, 5: PRINT "Tik="; tel&; " ";: ' display tick-counter

ShowHar testhar, 50, 400, 1 :' display the harmony string

SOUND 20000, 9 :' wait so the user can see...

LOOP

CLOSE 1

FUNCTION WriteHar2File(H As HarmType, track%, fnr%)

This procedure writes a harmonystring to the filenumber passed and lets the user specify the track it should be witten to. Timestamping is an internal part of the procedure and time starts the first time the procedure is called. The fileformat -we strongly advize users to stick to the *.SEQ naming convention for this format- is always sequential which is why it performs very fast on any reasonable hardware platform.

The most common problem we encountered using these functions in real-time applications are related to system settings on the users machine: if you have harddisk-sleep mode enabled, the hard-disk maybe in an inactive state until the writebuffer forces it to a wake-up state. This 'wake-up' time causes serious time imprecisions in the timestamping. The user should either disable power-saving features on his computer or else force the disk to an active state through his software (For example by reading an arbitrary directory to a dummy file before running the code...) .

Time stamping is in integer centisesonds (1/100"). . The resolution in cs may appear to be low at first sight, but do not forget that a single time-tick value may specify changes for up to 128 notes and any number of tracks. In this respect the resolution is way beyond the capabilities of midi-datatransfer anyway.

Example:

OPEN "MyMusic.SEQ" FOR OUTPUT AS #1

DIM Voice(0 TO 5) AS HarmType

DIM Oldsit(0 TO 5) AS HarmType

' code where the voice data are assigned to the harmony strings

FOR track%= 0 TO UBOUND(Voice)

' write only if a change has occured:

IF Voice(track%).vel$ <> OldSit(track%).vel% THEN

WriteHar2File (Voice(track%), track%, 1)

OldSit(track%).vel= Voice(track%).vel

ENDIF

NEXT track%

' other code...

CLOSE 1 ' make sure you close the file at the end.

Note about the SEQ file format:

The date are written to the file as follows:

• track number (space (ASC 20) delimited integer value)
• tick& number (space delimited positive long integer or dword value)
• ASC-character H followed by 128 bytes corresponding to the contents of the harmony string and closed with CR-LF codes (2 bytes).
• The format can be extended to contain data for many more parameters. Thus we reserved following starting characters for specific uses:
• ASC character Z for note-off release information (128 byte string)
• ASC characted I for program change information (patch data)
• ASC character T for text-strings and comments (ASCIIZ string)
• ASC character C for controller information (2 byte: controller and value)
• ASC character A for key pressure information, followed by a complete 128-byte string
• ASC character P for pitch-bend information
• ASC character X for sysex-info (followed by the complete sysex string).

These files can be converted to the standard midi file format (SMF) using the utility program (click to download) H2M.EXE. Midi files are not suitable for real time composition applications, hence their direct use inside our software is discouraged.

Example files can be obtained on demand from the author.

Filedate: 971122- last updated: 2007-01-24