Note that this Wiki is a work in progress, items may not be updated or may disappear entirely as the pages are updated.

PAL Objects

From SpacialAudio

Jump to: navigation, search

Link To Other PAL Articles

Table of Contents   Quick Start Guide   PAL Scripting 101   Objects   Script Examples    Music1 24 Hour PAL Script    Music 1 Hourly PAL   CBS News Scripts    Write some useful scripts


This section covers the basics. For more information about the objects and there methods and properties. Check the PAL Help
Normally located in C:\Program Files\SpacialAudio\SAMBC\Help
Also From SAM the Help Menu Drop down, PAL Scripting Reference also PAL Quick Start
This section will cover the basics of the most used objects, but not all objects. Again look at the Pal Scripting Reference.


Objects

PAL is a fully OOP language. Although you will most likely not use much OOP yourself, PAL contains many objects which you need to be able to use.
(OOP = Object Orientated Programming)

Objects are almost like variables, except that objects can also perform actions via methods. Objects also store data via properties. Some properties are read only though, i.e. they can only be used to read values, not change the values.

Properties and Methods

In general properties represent information about an object, whereas methods represent actions an object can take.

List of Objects used in PAL

TStringList maintains a list of strings.

Use a string list object to store and manipulate a list of strings. TStringList implements the abstract properties and methods introduced by TStrings, and introduces new properties, events, and methods to 

·	Sort the strings in the list.
·	Prohibit duplicate strings in sorted lists.
·	Respond to changes in the contents of the list.
·	Control whether strings are located, sorted, and identified as duplicates in a case-sensitive or case-insensitive manner.

Properties:
Duplicates (Read/Write)
Sorted (Read/Write)

Methods
Find
Locates the index for a string in a sorted list and indicates whether a string with that value already exists in the list.

Sort
Sorts the strings in the list in ascending order.

Top

TDataSet

This object is used to access the results of a SQL query.

PAL allows you to directly access the database via SQL queries, and query result sets. Be careful when working with the database directly - although this can be very useful, it is also easy to make mistakes that can corrupt your database or cause you to lose data. Make backups of your database before you start developing and testing new scripts. You will need to become familiar with SQL.
This section assumes you have a good knowledge of SQL statements. Teaching you SQL is beyond the scope of this document. You will find many good resources on SQL on the web. We recommend buying a good SQL book when you start learning SQL.


SQL parameters Before we jump into the actual SQL code we first need to explain the usage of SQL parameters inside SQL queries. Usually a query looks something like:

SELECT * FROM songlist WHERE (ID = 123) AND (date_played < '2005-01-01')

Notice how the values "123" and "2005-01-01" is hardcoded into the SQL string. This makes updating SQL queries hard & cumbersome. To solve this PAL introduces SQL parameters ... think of them as variables for SQL.

For example the above query could be done like this in PAL: 

var Q : TDataSet;
Q := Query('SELECT * FROM songlist WHERE (ID = :ID) AND (date_played < :DatePlayed)',[123,'2005-01-01'],True);

Notice how easy it is to replace the actual values now! For example, let’s use an actual date for the "DatePlayed": 

Q := Query('SELECT * FROM songlist WHERE (ID = :ID) AND (date_played < :DatePlayed)',[123,Now],True);

SQL commands In PAL there are two main SQL commands: function Query(Sql: String; Params: Array of Variant; ReadOnly: Boolean): TDataSet; function ExecSQL(SQL: String; Params: Array of Variant): Integer;

ExecSQL is used to execute an SQL statement that does not return any data. This function returns the number of rows affected by the query.

Examples: 

{Reset the balance of songs to zero}
var cnt : Integer = 0;
cnt := ExecSQL('UPDATE songlist SET balance = 0',[]);
WriteLn(IntToStr(cnt)+' tracks were updated');
{Delete a certain artist from the songlist}
var cnt : Integer = 0;
cnt := ExecSQL('DELETE FROM songlist WHERE artist LIKE :artist',['Blink182']);
WriteLn(IntToStr(cnt)+' tracks were updated');

The Query command is used exclusively with the SELECT SQL command which always returns a result set. This result set is encapsulated inside a TDataSet class object. Using this object you can browse the resulting rows of data, and even change the data.

Check the PAL Quick Start for more examples and usage. Check the PAL Script Reference guide for Properties and Methods

TSongInfo

The TSongInfo object is used to store information about a song.

Example (more examples and methods can be found in the PAL Quick Start)

Reading currently playing song information

This script will read the song information of the track loaded into DeckA, and then print out the information. 

var Song : TSongInfo;
Song := DeckA.GetSongInfo;
if Song = nil then
 WriteLn('No song loaded into DeckA!')
else
 begin
 WriteLn('Artist: '+Song['artist']);
 WriteLn('Title: '+Song['title']);
 WriteLn('Album: '+Song['album']);
 WriteLn('Duration: '+Song['duration']);
end;
Song.Free;

Notice how we test if the Song = nil, because if that is the case trying to read information on the song object will cause memory access violations since the object does not exist!


Top

TPlayer

TPlayer object is used to play songs inside SAM Broadcaster.

Use this object to control a player. DeckA, DeckB, Aux1, Aux2, Aux3 and SoundFX are all player types (Class TPlayer) This means that all of the same operations apply to all of these players.
PAL comes with some very handy built-in functions you can use. These provide you with direct access to the correct player object. (Between DeckA & DeckB only!)

ActivePlayer - This returns the player object considered the "active" player. If only one deck is player a track, then this track will be the active player. If both decks are playing a track, then the deck with the longest duration remaining is considered the active deck. If NEITHER DeckA or DeckB have any tracks playing, then this function returns NIL. It is very important that you check for the NIL value, unless you are certain that there will always be an active deck.

IdlePlayer - A Deck is considered Idle if no song is queued up in the deck, and the deck is not actively playing any tracks. If both decks are idle, DeckA is returned as the idle object. If both decks are queued up, or actively playing a track - then this function will return NIL!

QueuedPlayer - A player is considered in Queued mode if the Deck has a song object loaded into the Deck, but the Deck is not currently actively playing any tracks. If both decks are either idle or active, then this function will return NIL! Otherwise it will return the first Queued deck.

Overall the ActivePlayer function is used much more than any of the others. Most of our examples will deal with this function.



TPlayer ..Properties and Methods

Check the PAL Quick Start for more information on usage and the Reference guide for methods and properties.


Top

Link To Other PAL Articles

Retrieved from "http://support.spacialaudio.com/wiki/PAL_Objects"
Personal tools