Programmer Guide/Command Reference/LOAD: Difference between revisions

From STX Wiki
Jump to navigationJump to search
No edit summary
 
(31 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{DISPLAYTITLE:{{SUBPAGENAME}}}}
The <code>LOAD</code> command is used to load macro code, spu code and sound files, making them available for use in the {{STX}} programming environment.
==Introduction==
The <code>LOAD</code> command is used to load macro code, spu code, and sound files, making them available for use in the {{STX}} programming environment.


Macros, signal processing units and sound files must be loaded before they can be used!
;Note: Macros, signal processing units and sound files must be loaded before they can be used.


See also:
;See also: [[Programmer_Guide/Introduction#Application Environment|Application Environment]], commands [[../UNLOAD|UNLOAD]] and [[../LIST|LIST]], macros [[Programmer_Guide/Macro_Library/SOURCEFILE|SOURCEFILE]] and [[Programmer_Guide/Macro_Library/BSF|BSF]]
:[[Programmer_Guide/Introduction#Application Environment]]
:commands [[../UNLOAD|UNLOAD]] and [[../LIST|LIST]]
:macros [[Programmer_Guide/Macro_Library/SOURCEFILE|SOURCEFILE]] and [[Programmer_Guide/Macro_Library/BSF|BSF]]


==LOAD SOURCECODE==
==LOAD SOURCECODE==
;<code>LOAD SOURCECODE <var>file1</var> [ <var>file2</var> ... ] [ /Nolog [[Programmer_Guide/Command_Reference_Options/Silent|/Silent]] /Zombie /Conditional /Define=<var>ppvar</var> ...]</code>: Load all source code from the specified source files (''file1'' etc). The command loads all sections containing source code, preprocesses them and adds them to the shell environment.


====Load Source files====
:Note: An argument can also be the name of a [[Programmer_Guide/Shell_Items/Table|simple table item]] containing the source code.
<code>LOAD SOURCECODE <var>file1</var> [ <var>file2</var> ... ] [ /N /S /Z /C /D=<var>ppvar</var> ...]</code>
Load all source code from the specified source files (<var>file1</var> etc). The command loads all sections containing source code, preprocesses them and adds them to the shell environment.


:Note: An argument can also be the name of a [[Programmer_Guide/Shell_Items/Table|simple table item]] containing the source code.
:;<code>/Nolog</code>:
::If specieifed, not output is written to the log window.
::otherwise: error and warning messages are written to the log window.


;<code>/N<code> (no log):  
:;<code>[[Programmer_Guide/Command_Reference_Options/Silent|/Silent]]</code> or <code>/?</code>:  
:If specieifed, not output is written to the log window.
::If specified, errors will generate warning messages rather than error messages
:otherwise: error and warning messages are written to the log window.


;<code>/S</code> or <code>/?</code> (silent):  
:;<code>/Zombie</code> (no owner):  
:If specified, errors will generate warning messages rather than error messages
::If specified, no owner is assigned to the source files
::otherwise: the shell executing the command is the owner of the source files (see [[Programmer_Guide/Command_Reference/UNLOAD|UNLOAD /U/O]])


;<code>/Z</code> (no owner):  
:;<code>/Conditional</code>:
:If specified, no owner is assigned to the source files
::If specified, a section of a source file is only loaded if the source file is not already loaded
:otherwise: the shell executing the command is the owner of the source files (see [[Programmer_Guide/Command_Reference/UNLOAD|UNLOAD /U/O]]
::otherwise: the sections of a source are always loaded


;<code>/C</code> (conditional):
:;<code>/Define=<var>ppvar</var></code>: Define the {{STX}} prepecessor variable <var>ppvar</var>.
:If specified, a sections of a source file are only loaded, if the source file is not already loaded
:otherwise: the sections of a source are always loaded


;<code>/D=<var>ppvar</var> (define): Define the prepecessor variable ''ppvar''.
See the [[../SHELL/]] command for an example.


====Add a source file to a library====
==LOAD SOURCEFILE==
<code>LOAD SOURCEFILE <var>srcfile</var> <var>libfile</var> /M [ /N /S /D=<var>ppvar</var> ...]</code>
;<code>LOAD SOURCEFILE <var>srcfile</var> <var>libfile</var> /Makelib [ /Nolog [[Programmer_Guide/Command_Reference_Options/Silent|/Silent]] /Define=<var>ppvar</var> ...]</code>: Add all code sections of the source file ''srcfile'' to the (new or existing) compressed {{STX}} library ''libfile''. The sections of ''srcfile'' are not loaded! This command can be used to create a library file containing the source codes from multiple source files. {{STX}} library files can be loaded like normal source files.
Add all code sections of the source file ''srcfile'' to the (new or existing) compressed {{STX}} library ''libfile''. The sections of ''srcfile'' are not loaded! This command can be used to create a library file containing the source codes from multiple source files. {{STX}} library files can be loaded like normal source files.


;/M (make library): This option is mandatory.  
:;<code>/Makelib</code> (make library): This option is mandatory.  


;/N, /S, /D: see descriptions above
:;<code>/Nolog</code>, <code>[[Programmer_Guide/Command_Reference_Options/Silent|/Silent]]</code>, <code>/Define</code>: see the descriptions above


==LOAD SOUNDFILE==
==LOAD SOUNDFILE==
Line 46: Line 42:
The <code>LOAD SOUNDFILE</code> command loads a sound file into the shell's sound file list and make it the current sound file. Once you have finished with a sound file, you can unload it with the <code>[[Programmer Guide/Command Reference/UNLOAD|UNLOAD]]</code> command.
The <code>LOAD SOUNDFILE</code> command loads a sound file into the shell's sound file list and make it the current sound file. Once you have finished with a sound file, you can unload it with the <code>[[Programmer Guide/Command Reference/UNLOAD|UNLOAD]]</code> command.


<code>LOAD SOUNDFILE <var>soundfilepath</var> [ <var>srate channels code start</var> ] [/R|W] [ /S ]</code>
=== The concept of the active soundfile ===
{{:Programmer_Guide/Concepts/Current_Soundfile}}
 
=== Load or activate ===
<code>LOAD SOUNDFILE <var>soundfilepath</var> [ <var>srate channels code start</var> ] [ /Readonly | /Write ] [ [[Programmer_Guide/Command_Reference_Options/Silent|/Silent]] ]</code>


Load a sound file or activate an already loaded sound file (make it the current sound file). The access-mode options (/R|W) are only processed if the sound file is not already loaded. If the parameters <var>srate</var>, <var>channels</var>, <var>code</var> and <var>start</var> are specified, this file is treated as a non-standard-format sound file.
Load a sound file or activate an already loaded sound file (make it the current sound file). The access-mode options (/R|W) are only processed if the sound file is not already loaded. If the parameters <var>srate</var>, <var>channels</var>, <var>code</var> and <var>start</var> are specified, this file is treated as a non-standard-format sound file.


;<var>soundfilepath</var>
;<var>soundfilepath</var>
:The name of the file to open (including a relative or absolute path).
:The name of the file to open (including a relative or absolute path).


;<var>srate</var>
;<var>srate</var>
 
:The sampling rate in Hertz (&ge; <code>1</code>).
:The sampling rate in Hertz (>= <code>1</code>).


;<var>channels</var>
;<var>channels</var>
 
:The number of channels (&ge; <code>1</code>).
:The number of channels (>= <code>1</code>).


;<var>code</var>
;<var>code</var>
:The sample code. The following sample codes are supported: <code>PCM8</code>, <code>PCM16</code>, <code>PCM24</code>, <code>PCM32</code> or <code>FLOAT</code> (32 bit).
:The sample code. The following sample codes are supported: <code>PCM8</code>, <code>PCM16</code>, <code>PCM24</code>, <code>PCM32</code> or <code>FLOAT</code> (32 bit).


;<var>start</var>
;<var>start</var>
:The header size (&ge; 0); This is the offset of first signal sample from the beginning of the file.


:The header size (>=0); This is the offset of first signal sample from the beginning of the file.
;<code>/Readonly</code> or <code>/Write</code>
:Specify whether the sound file should be opened in read-only (/Readonly) or read/write mode (/Write). The default mode is read/write.


;<var>/R|W</var>
;[[Programmer_Guide/Command_Reference_Options/Silent|<code>/Silent</code>]]
:If specified, errors will generate warning messages rather than error messages. See [[Programmer_Guide/Command_Reference_Options/Silent|The Silent Flag]] for details.


:Specify whether the sound file should be opened in read-only (/R) or read/write mode (/W). The default mode is read/write.
=== Activate a soundfile already loaded ===
 
<code>LOAD SOUNDFILE <var>index</var> | <var>name</var> /Index | /Select [ [[Programmer_Guide/Command_Reference_Options/Silent|/Lent]] ]</code>
/S
 
:If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.
 
<code>LOAD SOUNDFILE <var>index</var>|<var>name</var> /Index|Select [ /L ]</code>


Activate (make it the current sound file) a loaded sound file, identified by its (zero-based) <var>index</var> or <var>name</var>. This command can be used in macros to check if a sound file is already open/loaded.
Activate (make it the current sound file) a loaded sound file, identified by its (zero-based) <var>index</var> or <var>name</var>. This command can be used in macros to check if a sound file is already open/loaded.


;<var>/L</var>
;<var>[[Programmer_Guide/Command_Reference_Options/Silent|/Lent]]</var> (silent)
:If specified, errors will generate warning messages rather than error messages. See [[Programmer_Guide/Command_Reference_Options/Silent|The Silent Flag]] for details.


:If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.
=== Create and activate a new soundfile ===
 
<code>LOAD SOUNDFILE <var>soundfilepath srate channels code type</var> /Create [ [[Programmer_Guide/Command_Reference_Options/Silent|/Silent]] ]</code>
<code>LOAD SOUNDFILE <var>soundfilepath srate channels code type</var> /Create [ /S ]</code>


Create and load a new (empty) sound file (make it the current sound file). See <code>LOAD SOUNDFILE</code> above for a description of the parameters <var>soundfilepath</var>, <var>srate</var>, <var>channels</var> and <var>code</var>. Note that this command will fail if the sound file <var>soundfilepath</var> already exists.
Create and load a new (empty) sound file (make it the current sound file). See <code>LOAD SOUNDFILE</code> above for a description of the parameters <var>soundfilepath</var>, <var>srate</var>, <var>channels</var> and <var>code</var>. Note that this command will fail if the sound file <var>soundfilepath</var> already exists.


;<var>type</var>
;<var>type</var>
:The file format. The following formats are supported: <code>WAVE</code> (Windows WAVE format), <code>ST5</code> (old S_TOOLS 5 file format) or <code>BINARY</code> (raw format, without header).
:The file format. The following formats are supported: <code>WAVE</code> (Windows WAVE format), <code>ST5</code> (old S_TOOLS 5 file format) or <code>BINARY</code> (raw format, without header).


;<var>/Create</var>
;<var>/Create</var>
:This option is mandatory.
:This option is mandatory.


/S
;<var>[[Programmer_Guide/Command_Reference_Options/Silent|/Silent]]</var>:
:If specified, errors will generate warning messages rather than error messages. See [[Programmer_Guide/Command_Reference_Options/Silent|The Silent Flag]] for details.


:If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.
<code>LOAD SOUNDFILE <var>table</var> /Directory [ /Load ] [ [[Programmer_Guide/Command_Reference_Options/Silent|/Silent]] ]</code>
 
<code>LOAD SOUNDFILE <var>table</var> /Directory [ /Load ] [ /S ]</code>


Attach a directory table <var>table</var> to a sound file. Only one table can be attached to a sound file. The table must be created with the /Directory option (e.g. with: <code>NEW TABLE * /Directory</code>). The directory table of a sound file can be accessed by all shells! Use the option /Load if {{STX}} should try to load the directory stored in the sound file (only for files created by S_TOOLS 5).
Attach a directory table <var>table</var> to a sound file. Only one table can be attached to a sound file. The table must be created with the /Directory option (e.g. with: <code>NEW TABLE * /Directory</code>). The directory table of a sound file can be accessed by all shells! Use the option /Load if {{STX}} should try to load the directory stored in the sound file (only for files created by S_TOOLS 5).


;<var>/S</var>
;<var>[[Programmer_Guide/Command_Reference_Options/Silent|/Silent]]</var>
 
:If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.
:If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.
Information about the currently active sound file is stored in the variables <code>CSF</code> (= fullfilepath) and <code>CSFH</code> (= srate channels samples code type mode). If no sound file is active, the variable <code>CSF</code> is empty. See Shell Environment for more details.Sound files opened with write access (/Write) cannot be shared with other users or processes.The sound file management is normally performed by the application {{STX}} . All other applications should use the {{STX}} APPMSG interface to attach or select sound files.The script library <code>BSF</code> implements a set of functions for using sound files and segments in scripts.

Latest revision as of 11:10, 29 February 2016

Introduction

The LOAD command is used to load macro code, spu code, and sound files, making them available for use in the STx programming environment.

Note
Macros, signal processing units and sound files must be loaded before they can be used.
See also
Application Environment, commands UNLOAD and LIST, macros SOURCEFILE and BSF

LOAD SOURCECODE

LOAD SOURCECODE file1 [ file2 ... ] [ /Nolog /Silent /Zombie /Conditional /Define=ppvar ...]
Load all source code from the specified source files (file1 etc). The command loads all sections containing source code, preprocesses them and adds them to the shell environment.
Note: An argument can also be the name of a simple table item containing the source code.
/Nolog
If specieifed, not output is written to the log window.
otherwise: error and warning messages are written to the log window.
/Silent or /?
If specified, errors will generate warning messages rather than error messages
/Zombie (no owner)
If specified, no owner is assigned to the source files
otherwise: the shell executing the command is the owner of the source files (see UNLOAD /U/O)
/Conditional
If specified, a section of a source file is only loaded if the source file is not already loaded
otherwise: the sections of a source are always loaded
/Define=ppvar
Define the STx prepecessor variable ppvar.

See the SHELL command for an example.

LOAD SOURCEFILE

LOAD SOURCEFILE srcfile libfile /Makelib [ /Nolog /Silent /Define=ppvar ...]
Add all code sections of the source file srcfile to the (new or existing) compressed STx library libfile. The sections of srcfile are not loaded! This command can be used to create a library file containing the source codes from multiple source files. STx library files can be loaded like normal source files.
/Makelib (make library)
This option is mandatory.
/Nolog, /Silent, /Define
see the descriptions above

LOAD SOUNDFILE

The LOAD SOUNDFILE command loads a sound file into the shell's sound file list and make it the current sound file. Once you have finished with a sound file, you can unload it with the UNLOAD command.

The concept of the active soundfile

Information about the currently active sound file is stored in the following two variables:

CSF - containing the full path of the file

CSFH - a string of the format "srate channels samples code type mode", indicating the respective properties of the sound file

If no sound file is active, the variable CSF is empty. See Shell Environment for more details.

Sound files opened for write access (/Write) cannot be shared with other users or processes. The sound file management is normally performed by the application STx. All other applications should use the STx APPMSG interface to attach or select sound files.

The script library BSF implements a set of functions for using sound files and segments in scripts. Namely the function BSF SELECT may be used to designate a sound file as the current sound file.

You can retrieve a list of loaded sound files with the LIST SOUNDFILE command. The sound file list is globally available. The current sound file, however, is dependent on the shell environment.

Load or activate

LOAD SOUNDFILE soundfilepath [ srate channels code start ] [ /Readonly | /Write ] [ /Silent ]

Load a sound file or activate an already loaded sound file (make it the current sound file). The access-mode options (/R|W) are only processed if the sound file is not already loaded. If the parameters srate, channels, code and start are specified, this file is treated as a non-standard-format sound file.

soundfilepath
The name of the file to open (including a relative or absolute path).
srate
The sampling rate in Hertz (≥ 1).
channels
The number of channels (≥ 1).
code
The sample code. The following sample codes are supported: PCM8, PCM16, PCM24, PCM32 or FLOAT (32 bit).
start
The header size (≥ 0); This is the offset of first signal sample from the beginning of the file.
/Readonly or /Write
Specify whether the sound file should be opened in read-only (/Readonly) or read/write mode (/Write). The default mode is read/write.
/Silent
If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.

Activate a soundfile already loaded

LOAD SOUNDFILE index | name /Index | /Select [ /Lent ]

Activate (make it the current sound file) a loaded sound file, identified by its (zero-based) index or name. This command can be used in macros to check if a sound file is already open/loaded.

/Lent (silent)
If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.

Create and activate a new soundfile

LOAD SOUNDFILE soundfilepath srate channels code type /Create [ /Silent ]

Create and load a new (empty) sound file (make it the current sound file). See LOAD SOUNDFILE above for a description of the parameters soundfilepath, srate, channels and code. Note that this command will fail if the sound file soundfilepath already exists.

type
The file format. The following formats are supported: WAVE (Windows WAVE format), ST5 (old S_TOOLS 5 file format) or BINARY (raw format, without header).
/Create
This option is mandatory.
/Silent
If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.

LOAD SOUNDFILE table /Directory [ /Load ] [ /Silent ]

Attach a directory table table to a sound file. Only one table can be attached to a sound file. The table must be created with the /Directory option (e.g. with: NEW TABLE * /Directory). The directory table of a sound file can be accessed by all shells! Use the option /Load if STx should try to load the directory stored in the sound file (only for files created by S_TOOLS 5).

/Silent
If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.
Retrieved from "https://mediawiki.kfs.oeaw.ac.at/stx/docs/wiki/index.php?title=Programmer_Guide/Command_Reference/LOAD&oldid=8943"

Navigation menu

Personal tools