opcode pathctalk guide 1997

7/30/2019 Opcode PathcTalk Guide 1997

1/37

Opcode Publication 1950906 - 1 - PatchTalk Guide

O P C O D EPUBLICATION

PatchTalk Guide

Overview

The Galaxy p ackage contains modules that enable it to wor k w ith awid e variety of syn th esizers and M IDI devices by describing h owGalaxy needs to int eract with a given syn thesizer. Galaxy also allows

you to create modules for oth er syn thesizers or MIDI devices thateither did nt exist at the t ime this version of Galaxy was created orthat we didnt kn ow about.

PatchTalk Basics

Before you attemp t to create your ow n custom modu les, you sh ould befamiliar w ith:

H ex ad ecim al n u mb er s.

The MIDI specification, particularly the format of system-exclu-sive messages.

How to read the section of MIDI device manufacturers manualsdealing w ith system-exclusive messages.

The basic concepts and p rinciples involved in programming. If you've never done any p rogramming, you might w ant to try learn-ing Hy perTalk (the langu age built into Ap ple's Hyp erCard) beforetry ing to learn PatchTalk; the languages are similar, and th ere aremany books and Hyp erCard stacks that you can learn from.

To create you r ow n cu stom (or u ser-defined) modu le:

Def ine the pa tch types that the device suppor ts. Crea te a new device that uses these pa tch types.

Wr it e t he scr ip t s for each pa tch type.

1950906


2/37

Opcode Publication 1950906

- 2 -

PatchTalk Guide

PatchTalk is th e langu age for describing how Galaxy should w orkwith a given MIDI device. To create a Galaxy modu le for a new MIDIdevice, you wr ite several small texts, called scripts, to d escribe th eways your MIDI device works for each patch type in the device.Scripts w ritten in Patch Talk describe:

Loading and sending a patch from a MIDI device.

(

Get Patch

an d Sen d Patch

scripts)

Loading and sending an entire bank of patches from a MIDIdevice.

(

Get Bank

an d Sen d Bank

scripts)

Translat ing the patch name in a patch to and from ASCII.

(

To Display N ame

an d To Device Nam e

scripts)

The numbering of the MIDI devices patches.

(

Patch N um ber script)

W hen Galaxy performs an operation w ith y our M IDI device, it followsthe instructions in one or more scripts that y ou h ave written t o findout h ow to interact w ith th e MIDI device. This is called r un ning ascript.

The descriptions that follow p rovide information about Galaxy an dPatchTalk that are necessary in ord er to write scripts and createcustom modules. However, you also need information about your par-ticular MIDI device and how it talks to compu ters over MIDI (oftenreferred to as its sy stem exclusive implement ation ). This informa-tion may be in th e manuals that came with your device, or you mayhave to requ est it from the company . In either case, be prep ared to

spend some time reading t he d ocumentation and experimenting withyour MIDI device to und erstand how it really w orks.

Skim th e examples of custom modules in t his section and on th eGalaxy disks. You sh ould find a device similar to y ours th at alreadyhas a custom module wr itten for it. Look at th e scripts and the infor-mation entered in d ialog boxes to get ideas for creating y our ow ncustom modu les. Learning from examples is prob ably th e clearest w ayto find out h ow to program your own modules.

N OTE: M any of t he modules included w it h Galaxy w ere not created in t hemanner described in this sect ion (many m odules w er e w r i tt en in C). A s a

resul t, the D ef ine Custom Pat ch T ype and D ef ine Custom D evi ce dial ogboxes for these patch types won't be accessible, and there are noPatchTalk scri pts t o read.


3/37


- 3 -

PatchTalk Guide

Defining Patch Types

To create a custom mod ule for Galaxy y ou create a custom d evice andone or more custom patch t yp es. This is done b y filling out d ialogbox es accessed from th e Galaxy Configur ation dialog box. Patch ty pesare created first, followed by the cu stom device. The following d iscus-sion details these two step s.

Each MIDI device can h ave one or more p atch ty pes. For examp le, asyn thesizer might h ave voices and set-ups; a dru m machine mighthave ton e parameters, patterns, and songs. Almost every d evice has asystem setup area th at can be implemented as a single patch ty pe. Foreach t yp e of information you r M IDI device has youll need t o create anew custom patch type.

To create a new custom patch t yp e:

ChooseSetup s> Galaxy Configu ration

.

Check Programm ing Mode

in th e lower left of the d ialog box.

Figure 1.1: Check Programming Mode; select Patch Types

Click th e Patch Type s

radio bu tton in the up per right of thedialog box .

Click th e Ne w Custom

bu tton to open th e Define Custom PatchType dialog box.


4/37


- 4 -

PatchTalk Guide

To make chang es to an existing patch ty pe:

Click th e Patch Type s

bu tton in th e Galaxy Configuration d ialogbox.

Select the patch t yp e and click th e Edit

bu tton to open t he Define

Custom Patch Ty pe d ialog box.Alternately, you could simply double-click the patch type.

Figure 2: Define Custom Patch Type Dialog Box

Fill in the fields of the Define Custom Patch Type dialog box asfollows:

Name

Enter the name of the patch type. This must be unique among all

patch typ es in y our system. Therefore, put th e device model numberin th e name, for example, DX7 Voices or Mu ltiVerb Patches.

Patches in Bank

Enter the n umb er of patches that th e MIDI device stores of this ty pe inits memory . Some devices can store more th an one b ank For examp le,there might b e an internal bank and a bank stored in a card. In thatcase, enter the nu mber of patches stored in one

of those bank s.

Rows/Columns inBank

These let you set th e numb er of rows (count d own th e screen) and col-umn s (count across the screen) in a bank win dow . Setting eithernu mber w ill set th e other nu mber to a useful value given th e numb er

of patches in a bank .


5/37


- 5 -

PatchTalk Guide

Patch Numbering

This is the w ay p atches are referred to on the M IDI device. Note thatwh ile MIDI always n umb ers patches from 0 to 127, most M IDI devicesuse a numb ering system that th e manufacturer t hinks w ill be moreconv enient for th e user. This option lets you set up the patch ty pe sothat Galaxy will use the same method in bank windows that the MIDIdevice uses. The options are:

0n-1

: The patches are numb ered and th e first one is 0. For exam-ple, there are 100 patches in a b ank and they are nu mbered 0

through 99

.

1 n

: The patches are numb ered and the first one is 1. For exam-ple, there are 64 patches in a b ank and they are nu mbered 1

through 64

.

1188

: The patches are nu mbered in group s of 8. For example,there are 16 patches in a bank and they are nu mbered:

11, 12, 13,14, 15, 16, 17, 18, 21, 22, 23, 24, 25, 26, 27, 28

.

Custom

: The patches are nu mbered in some other scheme. For

example, the patch es might b e named IA-6

, or P22

. This optiontells Galaxy to use a script y ou w rite to generate the num bering. Ifyou w ant to get going q uickly, you can choose the most appropri-ate option from one of the thr ee preset options, and come back tothe custom option later.

Device ID Range

The first nu merical defines w heth er th e device ID is 0 or 1 b ased. Th esecond nu merical defines th e highest d evice ID numb er possible forthat d evice. If your d evice doesnt appear to hav e a setting for adevice ID then its prob ably th e same as the M IDI chann el w ithin th erange 1

to 16

.

Handshake onSend

This option tells Galaxy if th e MIDI device needs to commun icate backto Galaxy even w hen Galaxy is only send ing patch information to th edevice. If you need to use any of the Receive

commands in y our Send

scripts (see PatchTalk Commands, later in t his section), then set th is toy es

.

N OTE: Galaxy w il l not work pr operl y wi th M I DI patchers and yourcustom patch t ype i f thi s opti on is not set corr ectly.

Size of Patch

Enter th e numb er of bytes in a single patch . This will generally b e the

nu mber of data by tes that th e MIDI device sends for each p atch. SomeMIDI devices, however, t ransmit tw o byt es for each b yte in a patch(this is called n ibblized data) and th erefore th e size of the p atch isonly h alf of wh at is sent. Furt hermore, a few MIDI devices requ ire youto get several pieces of information for each ind ividu al patch. In t hiscase you ll need to add up th e sizes of each p iece. Consult t he man ualfor your MIDI device carefully when choosing this number.


6/37


7/37


- 7 -

PatchTalk Guide

Display NameLength

If the nu mber of characters used for a name by Galaxy is differentthan t he nu mber of bytes stored in the patch d ata (ifScript

is selectedfor name conversion

) or th ere is no n ame in t he p atch d ata at all (

No t InPatch

selected), th en th is is the n umb er of characters Galaxy shoulduse to display the patch name.

Total Patch Size

This value is cann ot be set. It simply report s the total numb er of bytesGalaxy w ill be using t o save each p atch.

Has Edit Buffer

This indicates w heth er th e MIDI device has an ed it bu ffer for th epatch t yp e. An edit bu ffer is a separate area from the bank of patchesin w hich many MIDI devices store the current p atch being played andedited. If your d evice has one, and y ou set this to yes

, then when yousend an ind ividu al patch from Galaxy, t he edit bu ffer w ill be used (theSen d Patch

script w ill create th e UseEditBuffer

variable and set it totru e). Otherw ise, Galaxy will use the last patch location, w hich w illoverwrite that patch.

Defining Custom Devices

After you have created a new patch t yp e for each of the MIDI dev icespatch ty pes, you w ill need to create a new device type that u ses them.A device typ e defines the dev ices name, which p atch ty pes occur in adevice, and in w hat bank s the patch typ es occur.

To define a custom d evice:

Choose Setup s> Galaxy Configu ration .

Click th e Devices bu tton in th e Galaxy Configuration Dialog Box.

Click New Custom to open the Define Custom Device dialog box.

To make changes to an existing device typ e:

Click th e Devices bu tton in t he Galaxy Configuration d ialog box.


8/37


Select th e device typ e and click the Edit bu tton to open t he DefineCustom Device dialog box.

Alternately, you could simply double-click the device type.

Figure 3: Define Custom Device Dialog Box

Fill in t he Manufacturer an d M o d e l fields with the appropriatenames.

Click Ad d to add b anks.

You w ill see a dialog b ox of p atch ty pes to ch oose from.

Figure 4: Banks to Add Dialog Box


9/37


New b anks are added after th e selected b ank, or at th e beginn ingwh en no existing ban k is selected. You can click on any entr y in th ebank list and change its name by ty ping in th e lower text box labeledSelected bank s tit le. This will change only th e way th e label app earsin bu nd les, wh ere it is conv enient not to h ave the model numberrepeated again (since the model numb er is usually p art of the patch

typ e name, as described in th e Define Custom Patch Typ e section).

Fur th ermore, some MIDI devices have several bank s of the same patchtyp e. In th is case, you can add t he same patch ty pe tw o or more times(once for each ban k), as long as y ou ch ange each n ame. For examp le asyn thesizer may h ave an intern al ban k and a card b ank of voices. Firstadd t he patch t yp e for voices to the dev ice, rename it to intern alvoices, th en add the patch ty pe again and rename the second one tocard voices.

PatchTalk ScriptsAfter you h ave created a device and its patch ty pes, youll need tocreate a set of scripts for each p atch ty pe:

Crea te a new bank for the new patch type by choosing File>NewBank .

Th e Custom menu appears next to the Load/Send menu. It con-tains a command for each script .

Ch oose an it em fr om th e Custom menu t o edit the script for it.

A text editing w indow containing that script opens so you can

enter and edit th e script.

Figure 5: Script Editing Window

Get Patch and SendPatch

You w rite these scripts to describe how to tran sfer a single patch t o orfrom the MIDI device. They u sually instr uct Galaxy to send sy stemexclusive data to th e MIDI device and, in th e case ofGet Patch , toreceive it as w ell. There m ight also be PatchTalk instr uctions fordecoding or encod ing th e data before and after transmission overMIDI.


10/37

Opcode Publication 1950906 - 1 0 - PatchTalk Guide

Typ ical format for a Get Patch script:

Send a System Exclusive requ est to th e MIDI device.

Receive th e patch d ata using Receive or ReceivePackets.

Process the d ata received if necessary.

Store the received d ata int o the v ariable Patch.

Typ ical format for a Sen d Patch script:

Process the p atch d ata if necessary.

Send the d ata out in t he format that th e MIDI device expects.

The ty pes of processing that may b e necessary include b it conv ersionsor rearranging th e data into an easily u sable format. It is recom-mended that you use ReceivePackets wh en receiving data from thedevice because this command can automatically str ip off header and

trailer b yt es from th e system exclusive data. Galaxy p atches usuallydo not contain header/trailer b ytes or checksum. W hen sending d atato the device you may have to checksum the data sent. PatchTalkhas commands that handle a wide variety of checksum methods.


11/37


Get Bank and SendBank

These scripts are similar to th e Get and Send Patch scripts, except theydescribe how t o transfer a wh ole bank of patches at a time. They areoptionalif you leave them blank t hen t he patch scripts will be calledrepeatedly for each patch in th e bank , althou gh th is will be somewhatslower.

To Display Nameand To Device

Name

Some MIDI devices do not store th e name of a patch in a w ay th eGalaxy can read (which is a standard code called ASCII). In thesecases, you w rite these scripts to describe how to conv ert to and fromthe particular code t he M IDI dev ice uses. Because of th e special natu reof this script, saving th is script can take a long time.

Patch Number Many MIDI devices do not number their patches in one of thecommon numbering schemes that Galaxy knows (1n, 0n-1, or1188). For example, some use a scheme that runs A1, A2, A8, B1,etc. In t hese cases, you can wr ite this script t o instruct Galaxy how tonu mber th e patches the way you r MIDI dev ice does. Because of th especial natur e of this script, saving th is script can t ake a long time.

Saving and Exporting PatchTalk Modules

The patch an d d evice ty pes you create with Galaxy are stored in a filecalled Galaxy Librarian M odu les. Script s are treated as parts of a p atchtyp e. For safe backup of your w ork, and to be able to share it withothers, you ll pr obably w ant to make copies of your custom patch esand devices.

To save a copy of a custom device and the p atch ty pes it contains:

Open th e Galaxy Configuration d ialog by choosingSetup s> Galaxy Configu ration .

Click th e Devices bu tton, if its not already the cur rent ch oice.

Select the dev ice you wan t to expor t.

Only custom devices, mark ed by asterisks, are exp ortable.

Click th e Export button.

Name the file in th e stand ard w ay, and click the Export button in

th e stand ard Save As dialog box t o save th e module.

Modu les that you create in this way will always contain one deviceand all of the patch typ es contained in it. You (or a friend) can r e-install th ese modu les into Galaxy in th e same manner t hat y ouinstalled th e modules that came with Galaxy .


12/37


Send Opcode YourModules!

Opcode w ill periodically r elease additional Galaxy modu les. W e hop ethat even tu ally MIDI manu factu rers will w rite them before theyrelease new dev ices but , in the meantime, if you w ant to share you rwor k w ith other Galaxy users, send u s your mod ules. Well be collect-ing th em for p ossible inclusion w ith fut ur e versions of Galaxy.

PatchTalk Help

A summary of PatchTalk is available as on-line h elp. To open a helpwind ow, choose PatchTalk from the System 7 Help men u.

(

Figure 6: System 7 help menu icon appears on upper right of Macintosh

screen.

PatchTalk Commands

Commands are the instru ctions you w rite in PatchTalk scripts. Theyinstru ct Galaxy to perform very specific functions. W hen a script isru n, each command in th e script is executed in sequen ce. Rememberthat w hile Galaxy tries to do as much for you as possible, wh en itsrunning a script, it can only do exactly what is stated.

The following list of command s describes both h ow t o use them in ascript and w hat they d o wh en run by Galaxy . The format of the com-

mand is given first, then a description of what th e command does,followed b y some examples. Keep these points in mind wh en lookingat th e format lines:

W o rd s in b old face, su ch as Receive , are typed just as they appear.

Words in italics are replaced by one or more words that are appro-pr iate, for example ListOfValuesmay be replaced by 3 + 4.

Groups of words in b races, such a s {into | after} are ch oices sepa-rated b y th e vertical bar. You can choose one of th e options.

A n y tex t aft er t w o d ash es (- - ) is a commen t. Galaxy w ill ignor ew hatever is there thr ough t he end of th e line. A long d ash will also

work (, typed as Option-Shift-dash). Some parts of a command are optional. This is noted in a comment.

Note that if you includ e optional parts you mu st write them in th eorder they appear in the format line.

Upper and lower case let ters make no difference: p u t, Pu t, andPUT are all the same.


13/37


Wh ile some formats are shown on several lines for clari ty,PatchTalk commands are w ritten on e line p er command. (SeePatchTalk Notes for a way t o get around this limitation.)

Send SendListOfValuesThis transmits the data in the ListOfValuesto th e MIDI device. Anydata may b e sent : system exclusive commands, n ote command s, patchdata. Its up to you to ensur e that v alid MIDI messages are sent andthat any dev ice IDs or channel assignments get encoded int o the data(see the second examp le).

SendBulk SendBulk

This send s the contents of a bulk w indow to the MIDI device. Use theReceiveBulk command to get the data. Use this only w ith patch t yp esthat have t heir Patch Size set to Bulk.

Receive Receive MaximumSize { into | after } Destination

require ExactSizebytes--optional

timeout after Time {seconds |milliseconds } --optional

wait UserMessage --optional

This gets onesystem exclusive message over MIDI and p laces it into orafter the Destination. Any additional data beyond the nu mber stated,M axi mumSize, are lost.

The optional require clause specifies the exact n umb er of MIDI bytesrequ ired. If a different nu mber of by tes is received (too many or toofew), th en t he op eration fails and t he u ser will get a message. Use thiswh enever you kn ow exactly h ow many by tes the MIDI device shouldsend to you.

The optional t imeout clause specifies the amoun t of time to w ait for amessage. If this time is exceeded, the receive command will fail andthe u ser will get a time out message. Note that s an d se c are acceptableabbr eviations for seconds, as are m s an d msec for mil l i seconds . If notimeout is specified, a default timeout w ill be u sed.

Send $F7 send an end-of-system-exclu-

sive message

Send ($C : DeviceID) $7F send a patch change to patch

127. Note the use of adding the

Device ID variable to send the

program change on the right

channel.


14/37


The optional wait clause pu ts a text message up for the user and waitsindefinitely for t he first by te of any M IDI message. This is used w hena MIDI device requires the u ser to press a but ton on th e device itselfto initiate the transfer of patch d ata to Galaxy.

ReceivePackets ReceivePackets HeaderSize TrailerSize MaximumSize

{ into | after } Destination

require ExactSizebytes--optional



This is very similar t o Receive only it provides some very convenientfeatures. This message will receive as much data as the MIDI devicesends to Galaxy, across several system exclusive messages if neces-sary. Furth ermore, the command w ill strip offH eaderSizebytes fromthe front and TrailerSizeby tes from the end of each system exclusivemessage received . Note t hat M aximumSizerefers the maximu m size of

each in divid ual system exclusive message, not th e wh ole set ofmessages.

The other p arameters are just like those in t he Receive command.

ReceiveBulk ReceiveBulk MaximumSize --optional



Receive 68 into TheData get up to 68 bytes into the

variable theData

Receive 8+PatchSize into

TheData timeout after 500

msec

get a sys-ex message that is

8 bytes larger than the

patch size, but wait up to

500 milliseconds for the

data

Receive 8+PatchSize into

TheData wait Now Push the

Send Key

get data, but put up a mes-

sage for the user and wait

indefinitely for the data

ReceivePackets 6 2

BankSize+6+2 into theData

get up to BankSize bytes

into the variable theData

from multiple system exclu-

sive messages, throwing

away the first 6 and last 2

bytes of each message

ReceivePackets 6 2

BankSize+6+2 into theData

timeout after 250 msec

as above, but only wait up

to 1/4 second for the data

to arrive


15/37


Like ReceivePackets, th is command gathers all data the MIDI devicehas to send. How ever, it takes th e data exactly as received and p lacesit into th e bulk w indow. Use this only w ith patch typ es that havetheir Patch Size set to Bulk . Setting M aximum Sizeto 0 w ill tellGalaxy to allocate half of the available memory for bu lk op erations.ReceiveBulk , unlike ReceivePackets, w ill accept n on-system exclu-

sive data.

The other opt ions are just like th e Receive command.

Delay Delay Time {seconds |milliseconds }

This causes Galaxy to w ait the specified time before doing any thin gelse. Some devices require sh ort p auses before send ing or receivingMIDI data. Consult th e MIDI devices manu al for its r equ irements.

Abort Abort ErrorMessage

This stops Galaxy from runn ing the script any further, and displaysan opt ional error message for the u ser. You might use th is commandwh en you detect the MIDI device is sending b ad MIDI information.

Put Put ListOfValues { into | after } Destination

This command put s the result of the ListOfValuesinto the Destination.Th e ListOfValuesmay b e eith er a num ber, a string, or a list of arith-metic exp ressions and str ings separated b y sp aces. The Destinationcanbe an existing or a new v ariable.

Delay 50 msec wait 1/20 of a second

Delay 2*60*60 seconds wait 2 hours while you go eat

dinner

Abort cancel operation of the

script

Abort The MIDI data was

bad! Check the device.

tell the user of a problem

with the device

Abort Bad data received

make sure AppleTalk is OFF

tell the user to turn off

AppleTalk

Put 9 into x x now has 9 in it

Put x*3 into y y now has 27 in it

Put Hello into x x now has Hello in it

Put World after x x now has Hello World in it

Put temp[23,10] into

Patch[0,10]

replace 10 bytes of Patch

starting at offset 0 with 10

bytes of temp at offset 23

Put $C:DeviceNumber y

into z

z has a program change 27

message in it


16/37


N OTE: A ft er can only be used w it h an arr ay that al ready exi sts. Seethe secti on Putt ing Empty int o a Var iabl e for more inf orm ati on.

NibblizeDeNibblizeChecksum

Checksum0

Nibblize ListOfValues { into | after } Destination

DeNibblize ListOfValues { into | after } Destination

ChecksumListOfValues { into | after } Destination

Checksum0 ListOfValues { into | after } Destination

These command s all perform th e same fun ction as the Pu t command.Howev er, each of them does something to t he d ata before it is placedinto or after th e Destination.

Nibbl i ze expands the data to twice its size by placing the upper andlower 4 bits (a nibb le) of each by te into separate by tes. The up pernibb le pr ecedes the lower nib ble in memory . Many MIDI dev ices usethis simple encoding of patch data for transmission. W e encourage

you to store patches in d enibb lized format for efficient use of diskspace and memory.

N OTE: One good clue as to whether the data is nibbli zed i s whether thesize of the data that the device sends you is twice as large than what isspecif ied in i ts M I D I specif ication.

DeNibbl i ze contracts the d ata to half its size by combining each p airof byt es int o a single by te. It is the reverse ofNibbl i ze .

Checksum sums every b yte and app ends the low-byte of the total tothe en d of the d ata. Some MIDI devices require th is value to be p laced

near th e end of the d ata portion of all system exclusive messages. Seethe MIDI devices manual for details.

Checksum0 is like Checksum only th e reverse of the low-b yte of thetotal is appen ded to th e data. Some MIDI devices, such as some byRoland , u se this form of checksum.

View View Variables

This pauses a script and opens a dialog box d isplaying t he content s ofall curr ently d efined v ariables. It is useful for debu gging you r script.Temporarily add it at various points if you want to check w hat y our

script is doing. Strategic points to v iew variables are just b efore aSend command and just after a Receive command .

View Variables stop and look at the

variables


17/37


PatchTalk Control Structures

Contr ol Stru ctures are PatchTalk command s that d irect Galaxy how tointerp ret other PatchTalk statements. They allow y ou to chooseamong tw o or more group s of statements and/or r epeatedly execute agroup of statements. Since they contain other command s, these state-ments may tak e up several lines in a script .

If If Condition Then

Commands

Else--optional

Commands

EndIf

If the test indicated b y Conditionis true, th en th e first set ofCom-

mandsis ru n b y Galaxy . Otherwise the second set ofCommandsis run .Note that th e second set of commands is optional and , if not p rovided ,no command s will be run if the condition is false.

Note that the word then is optional.

If PatchNumber < 64 check if the number is less

than 64

Put A into BankLetter if so, then were in bank A

Else else the number is greater

than or equal to 64

Put B into BankLetter and then were in bank B

EndIf finish the If If x=16; put 0 into x;

EndIf

one line version of if x

is 16 then set it to zero


18/37


Repeat Repeat

Commands

Until Condition

The group ofCommandsis executed repeatedly u ntil the t est specified

in Conditionis no longer tru e. The Commandsare executed at leastonce.

Put 0 into PatchNum

Repeat

Send SysExHeader PatchNum Patch F7

Put PatchNum+1 into PatchNum

Until PatchNum is PatchesInBank

Put "" into Alphabet

Put 0 into HowMany

Repeat

Put 'A' + HowMany after Alphabet

Put 1 + HowMany into HowMany

Until howMany = 26

PatchTalk Variables

A v ariable is a named place where a v alue can b e stored. It is like amailbox with an add ress wh ere the add ress is the v ariables name.W hile Galaxy is runn ing a script , a variable may h old different valuesat different times. You can ch ange th e value stored in a variable withthe Pu t statement. You can u se the value stored in a variable in anyexpr ession by t yp ing th e variables name. See the Pu t statement (inthe p revious section) for an examp le of wh at happ ens to a fewvariables.

Many variables already exist in Patch Talk. These are special placesthat Galaxy w ill put impor tant information and expect informationwh en ru nn ing y our scripts. Below is a list of all these variables and

what information you will find in them. Many of the descriptionsrefer to the p atch t yp e or th e device or the b ank. Rememberthat each script is wr itten for a sp ecific patch ty pe for a sp ecific MIDIdevice. When Galaxy runs the script, it is because youre workingwith a bank of information for that M IDI device.


19/37


All values are zero b ased. This means th at, for examp le, th e sixteenchann els of MIDI are nu mbered 0 th rough 15 in PatchTalk scripts.Another example is that the one hun dred and twenty eight p atchesare num bered 0 to 127. Please note th at this is true in a script nomatter what options have been checked in the Define Patch Typedialog.

Different variables are available in different scripts. Be sure to useonly th e variables available in a given script or you will get an err ormessage. Following th e description of each v ariable is its data (nu mberor string) and if it can not be chan ged (fixed).

Variables for AllScripts

DeviceID The d evice ID of th e MIDI dev ice being talked to, w hich is displayedin the bank and bun dle windows (nu mber, fixed).

PatchSize The size, in by tes, of a single patch. Th is does not includ e any add i-tional information th at Galaxy needs for each p atch (iftotal patch size differs from patch size in th e Custom Patch Typ e dialog box ).That information is maintained separately and you don t ever see it(nu mber, fixed).

BankSize The size in b ytes of a bank of patches (nu mber, fixed ).

PatchesInBank The nu mber of patches in a bank of the patch typ e (nu mber, fixed).

BankTitle The name of the bank as it appears in a bu nd le wind ow. If you havethe same patch ty pe add ed to a dev ice several times with differentnames (for example, you might hav e card vo ices an d internalvoices), then this is the n ame of the bank youre working w ith. If thebank is not part of a bun dle, then th is variable is the empty string.

Get Bank and SendBank Scripts

Bank The collection of all the p atches being edited. Contains the p atch d atafor all the patches in the ban k. Cann ot be changed in t he Sen d Bank script (string). Wh en w riting a Get Bank script, you will load data intoBank. Similarly, w hen w riting a Send Bank script , you will send datathat is contained in Bank .

Patch This is the p atch data in Bank for th e patch wh ose nu mber is Patch-N u m . Chang es to this variable change th e appr opriate data in Bank also (string).


20/37


PatchNum The nu mber of the patch w hose data is in the variable Patch (num-ber). Chang ing th e value stored in PatchNu m will also change th e datathat Patch contains.

Get Patch and SendPatch Scripts

Patch The patch data to be sent t o or received from the MIDI device. W henwr iting a Get Patch script, you will load d ata into Patch. Similarly,wh en w riting a Send Patch script, y ou w ill send d ata that is containedin Patch. Note that th e variable Patch does not work w ith the variablePatchNum as it d oes in th e Get Bank an d Sen d Bank scripts (string).

DevicePatchNum The nu mber of the p atch in th e MIDI device to get from or send t o. Besure to check t he UseEditBuffer variable first, because if its set totrue DevicePatchNum does not ex ist (nu mber, fixed ). IfUseEdit-Buffer is set to false, and DevicePatchNum is examined in t he Ge tPatch script, DevicePatchNum will cont ain the location of the cu r-rently selected p atch in Galaxy s bank wind ow. In the Sen d Patch script, DevicePatchNum will cont ain th e last p atch location ifUse-EditBuffer is set to false.

UseEditBuffer Is set to tru e if the script should get from or send to the edit b uffer onthe M IDI device. If your dev ice doesnt hav e an edit bu ffer, th is vari-able should always b e set to false. W hen this is false, you should getfrom or send to location DevicePatchNum (condition, fixed).

To Device Nameand To Display

Name

The following apply wh en Nam e Conv ersion in the Define CustomPatch Typ e dialog is set to Script:

DeviceNameLength The nu mber of by tes used for the name in th e patch (number, fixed).

DisplayNameLength The number of bytes used for displaying the name (number, fixed).

DevicePatchName The n ame of a patch in th e MIDI devices format. The To DisplayN a m e script converts from this to the variable DisplayPatchName (string).

DisplayPatchName The name of a patch as displayed by Galaxy. Th e To Device Nam e script converts from this to the variable DevicePatchName (string).


21/37


The following occurs w hen Nam e Conv ersion in the Define CustomPatch Typ e dialog is set to Table :

NameChar Set to a value ranging from 0-127. The script shou ld conv ert th is value(to display or d evice format) and store it back int o NameChar(number).

Patch Label Script

PatchLabel Set this variable to the label to be displayed for the patch nu mber inPatchNum (string).

PatchNum The number to be converted to a custom patch label (number, fixed)

User-definedVariables

Your ow n v ariables may h ave names that are up to th irty-one charac-ters in length. Th ey mu st begin w ith a letter. To create a variable,

simply u se the Pu t command to store some value in it. Such as:

Put 67 into MyHeightInInches

Put Frederick into MouseName

PatchTalk Notes

Commands Commands are w ritten on e to a line. If youd like to w rite one com-mand across several lines (for clarity), then y ou can h old dow n th e

Option k ey w hen y ou pr ess return. This will insert a characterthat t ells Galaxy that t he command cont inues on th e next line. Youcan also put more than one command on a single line by separatingthem w ith a semicolon. Here are some examples:

Receive 1024 into midiBytes

timeout after 2 seconds this command takes two

lines

Put 5 into x; Put x*x into y two commands on a line

If x = 0 then; Put 1 into x;

EndIf

a one line If command

If x > 0; Put x into

AbsoluteX

Else Put 0-x into AbsoluteX;

EndIf

a two line If command


22/37


Numbers Anywhere a numeric value is needed you can enter any of the follow-ing: a decimal numb er, a hexadecimal nu mber, a v ariable, or anu meric expr ession. Numeric expressions can use any of the standardmath operations. Some examples are:

The operators and functions understood in PatchTalk are:

123 a decimal number

$F0 a hexadecimal number .C0 another hexadecimal number

Size+10 the contents of the vari-

able Size plus 10

2*(X+5) a mathematical expression

A the ASCII numeric value for

the character A (65)

0-5 negative 5 (you cant type

in negative numbers

directly).

+ Addition 15+4 is 19

- Subtraction 15-4 is 11

* Multiplication 15*4 is 60

/ Integer Division 15/4 is 3

mod Modulo 15 mod 4 is 3

>4 is $0000

: Nibble

concatenation

15:4 is $F4

Byte (value) Forces value to

fit in a byte

Byte ($f0f1f2f3) is

$F3

Word (value) Forces value tofit in a word (two

bytes)

Word ($f0f1f2f3) is$f2f3

Byte3 (value) Forces value to

fit in three bytes

Byte3 ($f0f1f2f3)

is $f1f2f3

Long (value) Forces value to

fit in a long

(four bytes)

Long ($f0f1f2f3) is

$f0f1f2f3

Sizeof (value) The size of value

in bytes

Sizeof (abc) is

3.

To7BitHex

(value)

Converts from 8-

bit-per-byte

format to 7-bit-

per-byte

To7BitHex ($f123)

is $36223

To8BitHex

(value)

Converts from 7-

bit-per-byte

format to 8-bit-

per-byte

To8BitHex ($f123)

is $38a3

characters The numeric value

of the characters

(up to four)

A is 65


23/37


Strings/Arrays You can r efer to a p ortion of a variables contents b y t yp ing a ran ge.The range is specified b y tw o nu mbers in squ are brackets separatedby a comma ([offset, length]) after the variables name. The firstvalue is the offset in by tes into the v ariable. The second is the nu mberof bytes to use. You can omit lengt h and it will default to one b yt e.You can also replace length with to end or en d and t he rest of the

variable will be used.

Some examples of Strings an d Array s include:

Strings are characters enclosed in d oub le qu otes, such as J ohn sonabove. Th e following ch aracters h ave special meaning in an ASCIIstring:

Put Johnson into FullName put a string into a new

variable

Put FullName[0,4] into

ShortName

put John into another

new variable

Put FullName[0] into Initial just the first character:

J

Put FullName[4,3] into AWord put son into another new

variable

Put FullName[4,to end] into

AWord

same thing

Put woo into AWord[1] change middle character

to woo

Put ed after AWord add ed

Put ny into FullName[4,to

end]

change ending; now is

Johnny

Put FullName AWord into

Text

Johnny Swooned

Put empty into AnEmptyArray now you can put...after

with this array

(Option-L) Continues the string on the next line(all characters to the end of the line

including the next Return are ignored).

Note that typing Option-Return will

enter this character.

\ (backslash) The escape character. It removes specialmeaning from some characters and adds

meaning to others. The following charac-

ters are given special meaning when

following the escape character. Any

characters not listed here are insertedliterally (are given no special meaning)

when following the backslash.

ror n Inserts a Return character into the text

(Return) Same as r or n, but also inserts a new

line in the script

t (Tab) Inserts a Tab character into the string(the Tab key may also be pressed)

(double quote) Terminates the string


24/37


Lists of Values Some commands, n otably Put , allow you t o work with a list of valuesat once. These lists can b e made by simply ty ping on e or morenu meric exp ressions and strings separated b y sp aces. Some examplesare:

Conditions A condition is used in th e cond itional command s, If and Repeat, todecide wh ich command s to run . Cond itions are just a form of expr es-sion using special test operators. Some examples are:

The full list of conditional operators is:

42 list of only one number

20 + 2 * 16 >> 1 another list of a single number (36)Hello list of the bytes $48, $65, $6C,

$6C, $6F

$C0 $34 a list of two bytes

14-4 4*5 the list of two bytes, 10 and 20

.F0 Moo 4*5 a list of the several bytes $F0,

$4D, $6F, $6F, 20

X Y a list of whatever is in X followed

by whatever is in Y

DeviceId > 16 list of only one number

PatchNum = Data are the two things equal

(X > 5) And (X < 15) are the two things equal

= or is equality 3 = 3 is true 3 = 4 is false

< less than 3 < 3 is

false

3 < 4 is true

greater than 3 > 3 is

false

3 > 4 is false

>= or greater than or

equal

3 3 is true 3 4 is false

or not equal 3 3 is

false

3 4 is true

condA

And

condB

true if both

conditions are

true

condA

Or

condB

true if either

condition is

true

Not

cond

true if the con-

dition is false

and vice versa


25/37


OperatorPrecedence

In th e absence of paren theses, the following order of p recedence isused for nu meric exp ressions. The operators with in the same rowhave equ al preceden ce. Those w ith h ighest precedence are listed onthe first row . Sub -expressions are evaluated from righ t to left.

Messages A few command s use messages. These are pieces of text th at are dis-played for you un der v arious circumstances. Messages are simply textbetween doub le qu otes:

Abort The device sent bad MIDI

Receive .100 wait Hit send on the MIDI Device

Custom Menu

Figure 7: Custom Menu

N OTE: T o access theCustommenu, you need to haveProgramming Mod e checked in the Define Device dialog box, and have a bank or abundle window active.

Not

:* /

+ -

>

< = >

And

Or


26/37


Define CustomPatch Type

Opens the Define Custom Patch Ty pe d ialog for th e patch ty pe con-tained in th e active bank or library w indow.

Edit Help Message Opens a dialog where you can enter a short message, wh ich th e userwill see if she chooses Help w hen a bank of this typ e of patches is

active.

Scripts:Get Patch, SendPatch, Get Bank,

Send Bank, ToDisplay Name,

To Device Name,Patch Label

Opens a text editing w indow for the specified script. ChooseFile>Save to save the edited script. If you have unsaved changeswhen you close a script editing window, youll be asked if you wantto save them. The Custom menu remains available while the scriptwindow is active.

About Patch Type Heres wh ere you, th e author of the custom libr arian module, get totell us about y ourself and y our end eavor. Put wh atever y ou like here.

Open Other TypesScript

Opens a dialog box w here y ou can select a script from a d ifferentpatch typ e (even on e that isnt curr ently in stalled into Galaxy !) toread.

Figure 8: View Script Dialog Box


27/37


Click Installed in Galaxy to choose among patch types currentlyinstalled in Galaxy . Click In o ther mod ule to choose a modu le docu-ment from which you w ant to select a patch ty pe. The patch typ esinstalled in Galaxy , or in th e selected modu le document, app ear in t hescrolling list. Select a p atch ty pe in the list, and select a script from th epop-up menu at the bottom of the window , then click OK to open a

script editing w indow . You w ont be able to make changes to scriptsopened in th is way, bu t it can be very useful for basing a n ew scripton an existing one.

Execute CurrentScript

Run s the script in th e active script editing w indow, op erating on thetopmost bank w indow of the proper patch typ e.

Patchtalk Troubleshooting

As with any task, if something goes wr ong youd like to know wh at itis so you can fix it. PatchTalk is a tool for p erforming tasks forGalaxywhen a task doesnt perform its function properly, youllwan t to find out w hats wr ong and correct the prob lem. This is calleddebugging.

Viewing theContents of

Variables

The Patch Talk View Variable s command can be u sed for debu gging,as well as learning about PatchTalk and you r M IDI device. Use it toview all the currently-defined variables and their values within a run-ning script . Refer to the description of the View Variable s commandearlier in th is section for a description of its syn tax.

You can use View Variable s to:

Look at the sys-ex header youre sending to the device.

By viewing the data in the sys-ex header right before you send it,you can verify that y ou bu ilt it correctly. Sometimes you may findthat you left out a byte, or inserted a by te when you meant toinsert a long w ord (4 by tes).

Look a t the da ta the device is sending back.

If you v erify t hat th e data you are receiving is correct, you cankn ow th at the pr oblem is not a bug in t he dev ice or a result of anincorrect sys-ex h eader. You can then concentrate on determinin g

wh y its not making it into the bank properly.


28/37


Examine the contents of bank or patch as they are changed.

By viewing variables immediately b efore and after a command th atchanges the contents of bank, patch, or any other important vari-able, you can determine w heth er the change is taking effectproperly.

If not, many times you may find that th e wrong part of the vari-able is being chan ged, or t hat t he p atch size or n ame offset d efinedfor this patch ty pe is incorrect.

If so, you can concent rate on th e command s after th is one in th escript since you h ave determined t hat its correct up to this point.

View the patch data dumped from the device using its front panel .

This is useful both to check th e sys-ex h eader of the data it sends(to make sure y ou foun d it correctly in th e devices manual) and tomake sure you re getting th e same thing w hen y ou ask for it overMIDI (as opp osed to u sing th e dev ices front pan el).

Decipher the encoding scheme of a patch when the devices User

Manu al is un clear. See Decipherin g Patch Data, w hich follow sshortly.

Common Problems

The device does notrespond to my MIDI

messages

The MIDI cables are not connected from t he int erface to the d eviceproperly.

The comput er is not conn ected to the MIDI interface pr operly.

Is OMS M IDI Setup in the Setups menu notified of the proper

port (pr inter or modem)? If youre using the MIDI Manager: Is the port youre using turned

on and is Galaxy connected t o the OMS MIDI Manager d river inPatchBay?

The in t er face does not have power.

You are not sending aproper system

exclusive message

Ask y ourself the following:

Does the message begin wi th F0?

Does the message end wi th F7?

Does the sys-ex data match the specification in the devices Users

Manual? Is the deviceID variable (if used), set to the correct value?

Is the size of the sys-ex message correct?

I f a checksum is inc luded, is it correc t?

Have you checksummed the p roper dat a?

Do any of the values in the da ta exceed $7F?


29/37


You are sending to thedevice too soon after it

has sent data

Some devices require a time d elay after it has sent or received databefore another message can be sent to it. Check the devices UsersManual to see if this applies. Use the command Delay to introducedelays betw een system exclusive messages.

The device has a bug in

its MIDI implementation.

Be careful about assuming this. Make sure your current setup workswith other d evices by plugg ing th e same MIDI cables into otherdevices. Then check the M IDI specification an d all data you sent andreceived . If you still believe it is a bug in you r d evice, call the manu -factur er. Be aware that some devices may n ot be chan ged just b ecauseyou h ave reported a bu g. Try to work aroun d th e bug if at allpossible.

The patch name is setincorrectly (or becomes

garbage) whenreceiving

The received d ata is incorrect.

View the data immediately b efore placing i t in Patch or Bank anddetermine its validity .

The p atch size, n ame offset, or name length is specified incorrectly.

Check th e Define Custom Patch Type dialog. Make sure that if thedevice does not supp ort a name for this patch typ e that you addName Length to th e size of the r aw p atch (as stored in th e device).

The data is somehow encoded.

You may find this information in th e devices User 's manualandth en again, y ou may n ot. If the information isnt there, try alteringthe patch in th e device and then send ing back wh at it sent you. Ifth is work s (th e old patch is received correctly) see Decipherin gPatch Data, wh ich follows. One good clue as to wh ether th e datais nibblized is wh ether th e size of the data th at the d evice sendsyou is bigger th an w hat is specified in its MIDI specification.

Deciphering PatchData

You may not b e able to tell by looking at the d evices User Man ualwh ether th e patch data is being encoded as its sent or not. If yourehavin g trou ble displaying th e patchs name, or if the size of th e datathe device sends is larger or smaller t han the size specified in th e MIDIspecification, all or part of the data may be encoded .

A common w ay of encoding MIDI data in sys-ex messages is nibb liz-ing. This is th e process of conv erting one by te into two b ytes. The

first by te contains the up per four b its of the original byte and thesecond b yte contains the lower four b its. There are tw o consequ encesof this that you can look for wh en try ing to determine if data isnibblized:

The data is twice as large as it would be if it were not nibblized.

No bytes have their h igh bit se t (have va lues $80).


30/37


Also bew are of strange th ings like only p art of the patch b eing nib-blized. This is the case for MKS-70 Patches and the User Manual saysnothing about the data being nibb lized.

Error Messages There are many t yp es of errors th at can occur wh ile a script is being

pr ocessed. These include: memory sh ortages, constr aint v iolations,semantic errors, and syntax errors. W hen an error is encountered, th escript is aborted. Sometimes a patch or b ank has already been altered,in w hich case the changes remain in effect. If the bank is not correct, itis set to th e correct size, and any part ial or missing p atches are set tothe empty patch. You define the empty p atch by selecting a patch y ouwant considered as empty, t hen choosing Edi t> Set Em pty Patch .Although the data is probably meaningless when a script terminatesafter reading only part of the b ank, th is should n ot be a pr oblem sinceit is expected th at the script w ill be fixed and re-executed to over-write any invalid d ata in th e bank.

W hen a fatal error occurs (one w hich immediately terminates execu-tion of the script) th e script is opened and th e insertion p oint is placedas close as possible to the end of the offend ing command . You maythen fix the p roblem and click on a bank wind ow to gain access to theLoad/Send menu and run the script again.

Constraint Violations Constraint violation err ors occur as a result of violating some ran ge orlength constr aint. For instance, if you specify a b yt e range for a vari-able that extend s past the data, or if you u se too many ch aracters in avariable name. The length violations are merely an inconven ience toyou, b ut let you kn ow w hen y ou exceed th e limitations of PatchTalk.The range violations, how ever, are extremely helpful. They save youhou rs of frustr ation because they point ou t flaw s in y our logic imme-diately, since you shou ld n ever access data th at is meaningless.Therefore, examine your script w ith care after one of these messagesun til you u nderstand w hat you are doing wrong and can decide on acorrect way to accomplish your purpose.

Semantic Errors Semantic errors occur w hen t he command is und erstood (parsed cor-rectly) bu t does not make sense und er the ru les imposed by PatchTalksemantics. Examples of semantic errors in PatchTalk are:

Specifying a range for a numeric var iable .

For ex ample, nu mber[1], is meaningless in PatchTalk an d is there-fore not allowed. Note that n either a lengt h n or a position isallowed.

Specifying a range for a variable with no value.

This is a special kind of constr aint violation, since any range sp ec-ified falls outside th e range of data b ytes.


31/37


Put t ing data a fter a numeric var iable.

You can only ad d d ata to the end of a string v ariable. Numericvariables can only h ave their content s replaced completely.

Putt ing data after a range of data in a variable (e .g., Put F7 afterPacket[1, 50]).

There is nothing conceptually wr ong w ith thisit is just n ot sup-ported b y PatchTalk in th is way. To do th is in PatchTalk, p ut th edata into t he n ext p osition. That is, Pu t F7 into Packet[51].

At tempt ing to use the bulk commands on a non-bulk bank.

ReceiveBulk and SendBulk may only be used on bank windowsdefined as Bulk in th e Define Custom Patch Typ e dialog box .

Usin g u nk now n un it s.

PatchTalk currently supports seconds (must begin with s) andmilliseconds (must begin with ms).

Accessing a variable that does not exist (has not been defined by

putting data into it). Using a str ing variable as a number without specifying a range.

Up to 4 by tes of a string variable may be u sed as a nu mber (in anu meric exp ression). Both a starting p osition and a lengt h mu st bespecified (e.g., Pu t SysExHeader[8, 4]


32/37


PatchTalk Tips

Putting Empty into aVariable

If you h ave a succession of statements that p ut a value after a variable,the empty command may h elp y ou. Putting empty into a variable cre-ates the variable bu t d oes not pu t a value into it. Because PatchTalk

does not let you p ut a value after a variable unless the variable alreadycontains a value, empty is a convenient way around this.

put empty into Abank

put 0 into i

repeat

send .f0 .43 .00 .07 .f7

receivePackets 4 2 100 after Abank

put i + 1 into i

until i = 10

In the above example, empty was u sed to create a variable Abank . A si is incremented , receivePackets puts the data after Abank . By p ut-ting empty into Abank , an initial receivePackets 4 2 100 intoAbankline is not needed .

Using PatchNum inGet and Send Bank

Scripts

Some PatchTalk script s may req uire add itional pr ocessing of bankdata received on a patch b y p atch basis. Take for example a script th atexamines a parameter in each patch an d alters the d ata in th e patchaccordin gly. The following script examines parameter 32 and based on

the result, p refixes an asterisk to th e beginning of the p atch namewh ich starts at offset 33.

repeat

put 0 into PatchNum

put Patch[32] into mode

if ( ((mode = 2) or ( mode = 7 ) or ( mode = 9 ) or

( mode = 10 )) and Patch[33] '*') ) then

put Patch[33,9] into Patch[34,9]

put '*' into Patch[33]

endif

put PatchNum + 1 into PatchNum

until PatchNum = 64


33/37


PatchNum is set to zero, then incremented by one through each passof the repeat loop. As PatchNum is incremented, Patch p oints to thenext patch of data. The script examines the number stored inPatch[32] and stores the v alue into mode. If mode is equ al to 2,7,9 or10 and the first ch aracter of the n ame is not already an asterisk (*), th escript moves the first 9 characters of the name to the righ t by one,

thus making the first character location free, then places a * charac-ter into t he first character location for the p atch n ame.

Creating CustomPatch Labels

Some MIDI devices label their p atches in d ifferent formats. A pop ularmethod is to numb er 128 patches as a11 - b88. The following scriptcreates a custom patch label displaying patch labels as a11-b88.

if (patchNum


34/37


Sending OtherMIDI Messages

Remember th at PatchTalk does not limit y ou to send ing system exclu-sive messages only. The Send command can transmit any ty pe of MIDImessage. Feel free to u tilize program changes w hen a parameterchange is u navailable, as w ell.

Extending PatchTalk

Extend ing the PatchTalk command s will give you add itional power tomanipu late data w ithin PatchTalk. Th e PCmd is the simplest ext ernalfunction b oth to create and t o use. It is used ex actly th e same way asthe Pu t command and is, in fact, how th e Checksu m and Checksum0command s are implemented.

The *Cmd is much more general. It accepts any nu mber of parameters

consisting of numb ers and h and les to data. In the event that some-thin g goes wrong , it is also allowed to retu rn a custom error messageto PatchTalk.

External Put Commands (PCmds)

CommandName ListOfValues { into | after } Destination

This command has th e same form as Put and may th erefore create newvar iables and mod ify existing on es (if the same variable is specified forListOfValuesan d Destination). It is provided to allow new tran sforma-

tions to be w ritten similar to Nibb lize and Denibb lize. Put merelytransfers th e data w ithout modification. Your PCmd can th erefore sim-ulate Put by simply d oing nothing. Nibblize and Denibblize happen toexpan d or collapse the d ata, but this is not necessary. Checksu mmerely appends a single bytew hich turn s out to be a very h elpfultransformation. You may w rite your ow n PCmd if you have a develop-ment system th at can generate code resources. This is how you wou lddefine the p rocedur e in THINK C.

pascal void myProc (dataHandle)

Handle dataHandle;

{

....

}


35/37


It is defined as a Pascal procedur e to allow Pascal programmers t owr ite PCmds. Th e hand le dataHandle consists of the d ata specified b yListOfValues. It is modified directly b y th e procedu re to return theresult. W hen it retu rns, th e data in the h andle is placed in th e variablespecified by Destination. Note that d ataHandle is not locked.

The C code for Checksu m and Checksu m0 is supp lied in th e filesChecksum .c and Checksu m0.c respectively. Feel free to u se thesefunctions as starting p oints for you r own PCmds. If you don 't have adevelopment system and you really need a custom function, get afriend to do it for you in exchange for the module you're writing(assuming she owns Galaxy).

The code resource must h ave ty pe PCmd and t he same name as spec-ified b y CommandName.

General External Commands (*Cmds)W hen a PCmd is not pow erful enough to accomplish the task at hand ,consider writing a more general external command, a *Cmd. *Cmdsallow an arbitrary number of numeric and variable parameters to bepassed to them. They p erform a task by altering memory , just like aPCmd, b ut t hey are more pow erful, since they accept more inpu t. Inaddition, they allow a m ore specific error message to b e given in casethey dont succeed.

Their PatchTalk syntax is:

CommandName arg1, arg2, arg3, , argN

As with PCmds, *Cmds are code resources that are called according toPascal calling conv entions. Th ey also take a single argu ment. But th isis where they differ. The argument is a parameter blocka structurecontaining all the p arameters. The following is a list of constant valuesfollowed by th e basic structu re of th e parameter block.

The args (th e argument s) are nu meric exp ressions and string v ariablesseparated by commas.

/** Error Types (for resultCode)*/

enum { NoError, BadParamCount, NeedMemoryError, Gener-alFailure, CustomErrorMsg };

/** Parameter Types (for paramType) */

enum { NumericType = 1, StringType = 2 };


36/37


/** Dat a field s ar e of th is type: */

typedef union {

long longNumber;

Handle handle;

} LongOrHandle;

/** The following structure occurs once for eachparameter: */

typedef struct {

LongOrHandle param;

int paramType;

} CommandParameter;

/* The parameter block */

typedef struct {

int resultCode;

/* result of *Cmd (initially NoError) */

Str255 errMsg;

/* string to be displayed when CustomErrorMsg' isreturned */

Byte reserved[6];

int numParams;

/* the number of parameters actually sent to us */

CommandParameter par[10];

/* numParams defines the number of array elementswhich actually occur */

} GeneralCmdParamBlock;

Defining this structure in your development environment makes iteasier to refer to th e parameters from w ithin y our *Cmd.

*Cmd Errors The first tw o fields are u sed for report ing errors t o the u ser. The fieldresultCode may h ave one of the listed error v alues where NoError is 0,BadParamCount is 1, etc. The resultCode field is set to NoError upon

entry , so you do n ot need t o set it if all goes well. If an error occurs,how ever, resultCode may b e set to ind icate the ty pe of error. If it isanyth ing bu t NoError, th e current script will be aborted.

The first three error codes tell th e user that an incorrect nu mber ofparameters was passed, the command ran out of memory, and thecommand failed, respectively.


37/37

The v alue CustomErrorM sg, how ever, allows t he *Cmd to d isplay anyerror message it w ants. To retu rn a custom error message, create ahand le containing t he message (using Pt rToHand , for instance). Thenset errMsg to th is handle and resultCode to CustomErrorMsg. W henyou r etur n, PatchTalk displays th e message and d isposes of th ishand le for you. Note th at the maximum custom error message lengt h

is 255 characters and must be a Pascal string.

The nu mParams field contains the nu mber of parameters passed to th e*Cmd. It shou ld be checked to make sure it is the nu mber ex pectedand, if not, BadParamCoun t should b e return ed in resultCodeimmediately.

The Parameters The fields following nu mParams are pairs of p arameters (4 b ytes) andtheir ty pes (2 by tes). Each parameters ty pe shou ld be checked an d anerror retu rn ed if it is not th e typ e expected. It could be disastrous ifyou use a long in teger as a han dle.

Examples The C source code is supplied for the PatchTalk *Cmds Separate andCollate in t he files Separ ate.c an d Collate.c respectiv ely. You m ayuse these routines as a starting p oint w hen d efining y our ow n *Cmds.

Passing String Data to External Commands

Both ty pes of extern al commands p ass string d ata only as the contentsof a variable. Note that th is results in a hand le being p assed. Th eexternal command may do w hatever it wishes to the data in th is han-

dle, bu t it may not d ispose the h andle (although it may empty it sothat it contains 0 by tes of data).

Also be aware that all hand les are not locked.

External Command Code Resources

These external commands are implemented as code resources of th etype PCmd and *Cmd as their names imply. You may put them inthe resource fork of Galaxy w hile youre testing them, b ut t heyshould b e placed in th e modules resource fork t hat u ses them b eforeyou d istribute th e module.

Note that wh en you export a module, any external commands that ituses are not automatically ex port ed. You mu st manu ally copy themfrom Galaxys resource fork into th e modu les resource fork u singResEdit.

opcode pathctalk guide 1997

Documents