Primera PTBurn 3 SDK User manual



PTBurn 3 SDK

Network‐capable,Text‐based,SharedFolderBurning&Printing























Compatiblewith:

PrimeraTechnologyInc.
September20,2011/Revision3.24

  

JobFileCommandStructure
ProgrammingExamples
RobotStatusInformation
ClientCommands
Introduction

PTBurnSDK   Page2of68
©2011PrimeraTechnology,Inc.PrimeraisaregisteredtrademarkandBravoisatrademarkofPrimeraTechnology,Inc.Allothertrademarks
arethepropertyoftheirrespectivecompanies.
1Introduction ............................................................................................................................ 5
2JRQFileCommandStructure .................................................................................................. 6
2.1CommandKeys/Values .................................................................................................... 6
2.1.1JobID.......................................................................................................................... 6
2.1.2ClientID...................................................................................................................... 6
2.1.3Importance................................................................................................................ 6
2.1.4Data........................................................................................................................... 6
2.1.5AudioFile ................................................................................................................... 7
2.1.6ImageFile................................................................................................................... 8
2.1.7DeleteFiles................................................................................................................. 9
2.1.8ImageType................................................................................................................. 9
2.1.9DataImageType ....................................................................................................... 10
2.1.10CloseDisc ................................................................................................................. 10
2.1.11Copies...................................................................................................................... 11
2.1.12PrintLabel ................................................................................................................ 11
2.1.13VolumeName .......................................................................................................... 11
2.1.14BurnSpeed............................................................................................................... 11
2.1.15VerifyDisc ................................................................................................................ 11
2.1.16RejectIfNotBlank ..................................................................................................... 11
2.1.17NotifyClient ............................................................................................................. 11
2.1.18PreserveISOVariations ............................................................................................ 12
2.1.19ReadDataTo............................................................................................................. 12
2.1.20ReadDataFormat..................................................................................................... 12
2.1.21CreateSubFolders.................................................................................................... 12
2.1.22CheckFileOnDisc...................................................................................................... 13
2.1.23CheckSystemIDOnDisc ............................................................................................ 13
2.1.24CheckVolumeIDOnDisc ........................................................................................... 13
2.1.25CheckPubIDOnDisc.................................................................................................. 13
2.1.26CheckPreparerIDOnDisc.......................................................................................... 13
2.1.27CheckAppIDOnDisc ................................................................................................. 13
2.1.28PVDSystemID........................................................................................................... 14
2.1.29PVDPublisherID ....................................................................................................... 14
2.1.30PVDPreparerID ........................................................................................................ 14
2.1.31PVDApplicationID.................................................................................................... 14
2.1.32LoadUnloadOverride............................................................................................... 14
2.1.33PreMasterData........................................................................................................ 14
2.1.34DriveID .................................................................................................................... 14
2.1.35BinID........................................................................................................................ 15
2.1.36TestRecord .............................................................................................................. 15
2.1.37PrintQuality ............................................................................................................. 15
2.1.38PrintInnerDiam........................................................................................................ 16
2.1.39PrintOuterMargin.................................................................................................... 16
2.1.40MergeField .............................................................................................................. 16
2.1.41RobotName ............................................................................................................. 17
2.1.42PrintReject............................................................................................................... 17

PTBurnSDK   Page3of68
©2011PrimeraTechnology,Inc.PrimeraisaregisteredtrademarkandBravoisatrademarkofPrimeraTechnology,Inc.Allothertrademarks
arethepropertyoftheirrespectivecompanies.
2.1.43CDTextDiscTitle ....................................................................................................... 17
2.1.44CDTextDiscPerformer.............................................................................................. 17
2.1.45CDTextDiscComposer.............................................................................................. 18
2.1.46CDTextTrackTitle ..................................................................................................... 18
2.1.47CDTextTrackPerformer ........................................................................................... 18
2.1.48CDTextTrackComposer............................................................................................ 18
2.2ProgrammingExamples.................................................................................................. 18
2.2.1SimpleDataJob....................................................................................................... 18
2.2.2SimpleAudioJob..................................................................................................... 19
2.2.3BurnandPrintjobof5discswithmanyoptionsspecified .................................... 19
2.2.4PrintOnlyJobof25Discs........................................................................................ 20
2.2.5ReadDataJobof3Discs ......................................................................................... 20
2.2.6ReadGlobalImageJobof3Discs ........................................................................... 20
3StatusInformation ................................................................................................................ 21
3.1SystemStatus.txtFile ...................................................................................................... 21
3.1.1ExampleofSystemStatus.txt .................................................................................. 21
3.1.2RobotList ................................................................................................................ 22
3.1.3RobotSection.......................................................................................................... 22
3.1.4SystemSection........................................................................................................ 24
3.2RobotName.txtStatusFiles............................................................................................ 26
3.2.1ExampleofRobotName.txt(e.g.DiscPublisherXRP.txt) ....................................... 26
3.2.2JobListSection......................................................................................................... 28
3.2.3CompletedJobsSection........................................................................................... 28
3.2.4JobDetailsSection .................................................................................................. 29
3.2.5SystemSection........................................................................................................ 32
3.2.6DriveStatisticsSection............................................................................................ 36
4ClientCommands.................................................................................................................. 38
4.1AbortCommand............................................................................................................. 38
4.2ShutdownAfterJobCommand ...................................................................................... 38
4.3ShutdownImmediateCommand ................................................................................... 38
4.4AlignPrinterCommand.................................................................................................. 39
4.5IgnoreInkLowCommand .............................................................................................. 39
4.6ProcessDiscCommand .................................................................................................. 39
4.7RejectDiscCommand..................................................................................................... 40
4.8UnloadCommand .......................................................................................................... 40
4.9CheckBinsCommand..................................................................................................... 40
4.10CreateReportCommand............................................................................................ 40
4.11GeneratePreview ....................................................................................................... 41
4.12RunUtilityCommand ................................................................................................. 41
4.13USBConnect ............................................................................................................... 41
4.14USBDisconnect........................................................................................................... 41
4.15Set/ClearKioskMode ................................................................................................. 41
4.16CleanCartridges.......................................................................................................... 42
5CodingBestPractices............................................................................................................ 42
5.1Programming Tips.......................................................................................................... 42
5.1.1ReadingtheStatusFile............................................................................................ 42

PTBurnSDK   Page4of68
©2011PrimeraTechnology,Inc.PrimeraisaregisteredtrademarkandBravoisatrademarkofPrimeraTechnology,Inc.Allothertrademarks
arethepropertyoftheirrespectivecompanies.
5.1.2DeterminingiftheserviceisRunning..................................................................... 42
5.1.3Startingtheservice ................................................................................................. 42
5.2Merge Printing................................................................................................................ 43
6AppendixA:PTSetup.ini....................................................................................................... 45
7AppendixB:DeploymentDetails ......................................................................................... 50
8AppendixC:Job,SystemandBurnEngineErrorCodes....................................................... 51
9AppendixD:Loading/UnloadingOverride........................................................................... 65
10RevisionHistory .................................................................................................................... 67

PTBurnSDK   Page5of68
©2011PrimeraTechnology,Inc.PrimeraisaregisteredtrademarkandBravoisatrademarkofPrimeraTechnology,Inc.Allothertrademarks
arethepropertyoftheirrespectivecompanies.

1Introduction
Primera’sPTBurnSDKserviceallowsanyclientapplicationtoeasilycreatediscswith
customizedburndataandprintedlabelinformation.Itisidealforusewithcustomer‐supplied
“front‐end”applicationsinnetworkedorcustomenvironmentsinmarketssuchasmedical
imaging,digitalphotoprocessing,music/video/softwareon‐demandandmuchmore.The
supporteddevicesforthisapplicationarePrimera’sDiscPublisherSE,DiscPublisherII,Disc
PublisherPRO,DiscPublisherXR,DiscPublisherXRP,DiscPublisherProXi‐Series,andDisc
Publisher4100Series(includingXRP).

TheclientapplicationcreatesanASCIItextfile(JobRequestFile)intheJobRequestFolder
(shared“hot‐folder”).TheJobRequestFilespecifiestheimagedatatoburn,thelabeltoprint,
andthenumberofcopiestocreate.ThePTBurnservicescansthisJobRequestFolderfornew
jobssubmittedbyanyclientapplicationandcreatesthediscsautomaticallyontheDisc
Publisher.ThereisabothaUnicodeversionandaMultibyte(MBCS/ANSI)versionofPTBurn
SDK;usetheUnicodeversionforburningandprinting2‐bytecharacters.

ThePTBurnWindowsServiceworksonWindowsXP,WindowsVistaorWindows7.Client
machinescanrunanyoperatingsystemthatisabletoreadandwriteintoaWindowsshared
folder.Itcanburneitherdataoraudiodiscs,aswellascreatediscsfromadiscimage.

ChangescanbemadetothePTSETUP.INIfiletocustomizecertainsettings.SeeAppendixAfor
moredetailsonthePTSETUP.INIfile


PTBurnSDK   Page6of68
©2011PrimeraTechnology,Inc.PrimeraisaregisteredtrademarkandBravoisatrademarkofPrimeraTechnology,Inc.Allothertrademarks
arethepropertyoftheirrespectivecompanies.
2JRQFileCommandStructure
Tocreatediscs,theclientapplicationmustcreateaJobRequestFile.Thistextfilecanbe
namedanythingtheclientchoosesbutitMUSTresidewithintheJobRequestFolderANDmust
haveanextensionof.JRQ(thiscanbechangedinPTSETUP.INI).This.JRQfilecreatedbythe
clientcontainsinformationthatspecifiesthedatatoburn,numberofcopies,etc.

TheJobRequestFilemustbeatextdocumentwithcertainKeyvaluesdefined(manyofwhich
areoptional).Theformatis:
2.1 CommandKeys/Values
2.1.1 JobID
AnyASCIIstringmessageupto32charactersdescribingthejob.Whenthejobisbeing
executedthisJobIDstringwillbeshowninthePTBurnwindow.Ifthiskeyisnotprovidedthen
thejobrequestfilenamewillbeused.
2.1.2 ClientID
ThisASCIIstringmessageupto32charactersisadescriptionfortheClientwhoissubmitting
thejob.Theclientcandecidewhatstringhewantstouse.Ifthiskeyisnotprovidedthenthe
ClientIDwilldefaultto“Unknown.”
2.1.3 Importance
ThistellsPTBurnhowimportantthejobis.Possiblevaluesare0to400where0ismost
importantand400isleastimportant.Ifthiskeyisnotprovidedthenadefaultvalueof4willbe
used.Jobswithlowervalueswillbeprocessedfirstunlessthejobhasbeenwaitingtoolong
(thisvaluecanbechangedinPTSETUP.INI).NOTE:Whensubmittingjobsofdifferentpriorities
itisimportanttosubmitjobswithhigherprioritybeforejobswithlowerpriority;jobsthatare
discoveredbyPTBurnwillnotbeinterruptedoncetheyactuallybegin,evenifajobwitha
higherpriorityisdiscoveredlater.

2.1.4 Data
Thisisastringthatspecifiestheeitherthefilenametoburnorthefolderthatcontainsallthe
datatobeburned.Allfilesandsubfolderswithinaspecifiedfolderwillbeburned(theroot
folderitselfwillnotbecopied–onlyitscontents).Alternatively,individualfilescanbe
specifiedhere(thefullpathforthesourcefilemustbegiven,butthefilewillbecopiedtothe
rootlocationonthedisc).Theformatisasfollows:

Data=Filename,SessionX

WhereSessionXisoptionalandisusedonlyifrequestingamulti‐sessiondisc(amaximumof2
sessionsisallowedatthistime).ThevalueXisanintegervalue(1or2)thattellsPTBurnfor
whichsessiontoburnthisdata.
IfSessionXisnotgiventhenitwillbeburnedintothefirst(andonly)session.

PTBurnSDK   Page7of68
©2011PrimeraTechnology,Inc.PrimeraisaregisteredtrademarkandBravoisatrademarkofPrimeraTechnology,Inc.Allothertrademarks
arethepropertyoftheirrespectivecompanies.

e.g.
Data=C:\MyFolder1,Session2

(ThistellsPTBurntoburnthecontentsofC:\MyFolder1tosession2onthedisc.Inthis
example,theremustalsobeanAudioFile=orImageFile=entryforSession1).

SeetheDataImageTypekeybelowtospecifyburningoptionsincludingfilesystem.

TheonlywaytheDatakeycanbeusedwiththeAudioFilekeysortheImageFilekeyis
iftheSessionXvalueisused.TheDatakeymustnotbeusedwithAudioFileor
ImageFilewiththesamesessionvalue.

Foraddedflexibilityyoucanalsoburndatafromasourcelocationandchangethedestination
nameand/orlocationofthedatatobeburnedontothedisc.Forexample,youcancopyfiles
fromthesourceharddriveandrenamethem.Youcanalsoplacethemintoanewfolderonthe
disc.Also,youcancopyanentiresourcefolderandplacethemintoanyspecifieddestination
folderonthedisc.
Theformatforthisisasfollows:

Data=SourceFilename>\DestinationFilename
Or
Data=SourceFolder>\DestinationFolder

Notethedestinationfilenameandfoldershouldbeproceededbya“\”todenotetherootof
thedisc.

Examples:
Data=C:\MyFolder1\MyFile.txt>\YourFile.txt
ThiswillburnC:\MyFolder1\MyFile.txttotherootofthediscandchangethenameto
YourFile.txt

Data=C:\MyFolder1\MyFile.txt>\YourFolder1\YourFile.txt
ThiswillburnC:\MyFolder1\MyFile.txtasYourFile.txtintoafolderonthedisccalled
YourFolder1(noteYourFolder1willautomaticallybecreatedonthedisc).

Data=C:\MyFolder1>\YourFolder1\YourFolder2
ThiswillburntheentirecontentsofC:\MyFolder1intoanewfolderonthedisccalled
YourFolder2(whichiscreatedasasubfolderwithinYourFolder1)

2.1.5 AudioFile
Thisisastringthatspecifiesthenameofanaudiofiletoburn.
YoucanoptionallyspecifyaPregapvalue(insectors)ofthetrack,theSession,ortheISRCcode
forthedisc.So,theformatisasfollows:


PTBurnSDK   Page8of68
©2011PrimeraTechnology,Inc.PrimeraisaregisteredtrademarkandBravoisatrademarkofPrimeraTechnology,Inc.Allothertrademarks
arethepropertyoftheirrespectivecompanies.

AudioFile=Filename,PregapX,SessionX,ISRCxxxxxxxxxxxx

Upto99AudioFile=statementsareallowed(99totalifDataandImageFilestatementsused
also).

Acceptableaudiofilenametypesinclude.WAV,.MP3,and.WMA.
PregapX(audiosilence)valuesareinsectorsso75sectors=1second,150sectors=2seconds,
andsoon.Thefirstaudiotrack
willalwayshaveaPregapof150evenifanothervalueisspecified.IfPregapisnotspecified
thenavalueof150willbeusedasthedefault.

SessionXisoptionalandisusedonlyifrequestingamulti‐sessiondisc(amaximumof2sessions
areallowedatthistime).ThevalueXisanintegervalue(1or2)andtellsPTBurnforwhich
sessiontoburnthisaudiofile.IfSessionXisnotgiventhenitwillbeburnedintothefirst(and
only)session

e.g.
AudioFile=MySong.mp3,Session1

(ThistellsPTBurntoburntheaudiofileMySong.mp3tosession1onthediscascdaudio.In
thisexampletheremaybeaData=orImageFile=entryforSession2).

TheonlywaythiskeycanbeusedwiththeDatakeysortheImageFilekeyisiftheSessionX
valueisused.AudioFilemustnotbeusedwithDataorImageFilewiththesamesession
value.

ISRCisanotheroptionforeachaudiotrack.TheISRCvaluexxxxxxxxxxxxisa12character
sequencethatdescribeseachaudiotrack.Seehttp://en.wikipedia.org/wiki/Isrcfordetailsof
validvaluesforthe12characters.
e.g.
AudioFile=MySong1.wav,ISRCUSPR37300012
AudioFile=MySong2.wav,ISRCUSPR37300013

2.1.6 ImageFile
Thisspecifiesthename(includingpath)ofanalready‐mastereddiscimagetobeburned.The
acceptablediscimagetypesinclude.GIor.ISO.

Theformatisasfollows:

ImageFile=Filename,SessionX


PTBurnSDK   Page9of68
©2011PrimeraTechnology,Inc.PrimeraisaregisteredtrademarkandBravoisatrademarkofPrimeraTechnology,Inc.Allothertrademarks
arethepropertyoftheirrespectivecompanies.
WhereSessionXisoptionalandisusedonlyifrequestingamulti‐sessiondisc(amaximumof2
sessionsareallowedatthistime).ThevalueXisanintegervalue(1or2)thattellsPTBurnfor
whichsessiontoburnthisimage.
IfSessionXisnotgiventhenitwillbeburnedintothefirst(andonly)session.

e.g.
ImageFile=c:\MyImage.ISO,Session1

(ThistellsPTBurntoburnthediscimageMyImage.ISOtosession1onthedisc.Inthisexample,
theremaybeData=orAudioFile=entriesforSession2).

TheonlywaythiskeycanbeusedwiththeDatakeysortheAudioFilekeysisifthemulti‐
sessionSessionXvalueisused.ImageFilemustnotbeusedwithDataorAudioFilekeyswiththe
samesessionvalue.

2.1.7 DeleteFiles
Thisspecifiesifthefiles/folders/imageforthisparticularjob,shouldbedeletedafterthejobis
completed.Possiblevalues:
YES
NO
ThedefaultvalueifthiskeyisnotgivenisNO.Inorderforthefiles/folderstobedeletedthey
mustresidewithinasubfolderoftheSharedJobFolder.Everythingwithinthefirstsubfolder
undertheSharedJobFolder(includingthesubfolder)willbedeleted.

IfDeleteFilesissettoYES,thejobdataandprintfileswillbedeleteduponthejobcompleting
(Pass,Fail,orAbort).Thejobrequestfile(nowwitha.donor.errextension)willnotbedeleted
immediately.ThedeletionofthisfilewilloccurwhenthetimesetinPTSETUP.ini(Status_Time)
hasexpiredafterjobcompletion.

2.1.8 ImageType
Thisspecifiesthemode(blocklength)tousewhenburningtheImageFilediscimage.The
possiblevaluesareasfollows:

MODE_1_2048
MODE_2_2336
MODE_2_2352

Thiskeyonlyappliesto.ISOdiscimages.
Notethatusingthewrongvalueherecancausetheimagetonotfitandleadtoanunusable
disc.


PTBurnSDK  Page10of68
©2011PrimeraTechnology,Inc.PrimeraisaregisteredtrademarkandBravoisatrademarkofPrimeraTechnology,Inc.Allothertrademarks
arethepropertyoftheirrespectivecompanies.
2.1.9 DataImageType
Thisspecifieswhatkindofimageshouldbecreatedforadataburn(whenDataFileskeyis
given).Multipleitemsarepossiblesotheformatis:

DataImageType=FileSystem,Option1,Option2,…

PossiblevaluesofFileSystemarethefollowing:
ISOLEVEL1–foranISO9660Level1compliantCDwithfolderandfilenamesinthe8+3format
usingonlytheA‐:‐Z,0‐:‐9and“_”characterset.
ISOLEVEL2–forandISO9660Level2compliantCD(DOSOEMcharacters).Filenamesare8+3
format(useISOLEVEL3forlongfilenamesupport).
ISOLEVEL3–foranISO9660Level3compliantCD(DOSOEMcharacters,longfilenames)
JOLIET–foraMicrosoftJolietcompliantCDwithfilenamesupto106characters.
ISOLEVEL1+JOLIET–foranISO9660Level1withJolietCD.
ISOLEVEL2+JOLIET–foranISO9660Level2withJolietCD.
ISOLEVEL3+JOLIET–foranISO9660Level3withJolietCD.
UDF–foraUDF1.02bridgefilesystem
UDF201–foraUDF2.01bridgefilesystem
UDF250–foraUDF2.50bridgefilesystem
UDF260–foraUDF2.60bridgefilesystem

PossiblevaluesofOption1,Option2,…arethefollowing:SETNOW–thiswillcauseallfilesto
besettothetime/dateatwhichthedisciscreated.Ifthisoptionisnotgiventhenthefile’s
time/datewillkeeptheiroriginalvalues.
MODE2–thiswillmakeaCD‐ROMMode2XAdisc.Ifthisoptionisnotgiventhenthedisc
createdwillbeMode1.
ThisoptionisvalidonlyforaCD‐R,andisignoredforaDVD‐R.
SAO‐‐ifthediscmustbewrittenSessionAtOnce.WhenSAOisnotspecifiedtherecordingis
doneTrackAtOnce(TAO).TAOisrequiredforDVDmulti‐border(DVD‐R,DVD‐RW)butis
optionalforCD‐R,CD‐RW.
(Ifthiskeyisnotprovided,thedefaultwillbeaJoliet,Mode1,TrackatOnceDisc).

Note:IfchoosingISOLevel1thefilenamesmustadheretotheISOLevel1namingconvention
(8+3usingA‐Z,0‐9,and_only).Ifanyfiles/foldersinthejobdonotadheretothisconvention
thejobwillfail.

Note:IfburningDVDVideo(VIDEO_TS),werecommendthatyouselectUDFtoallowfor
betterplaybackcompatibilitywithdvdplayers.
2.1.10 CloseDisc
Thisspecifiesifthediscmustbeclosedsothatnoothersessioncanbeadded.Possiblevalues:
YES
NO
ThedefaultvalueisNOifthiskeyisnotgiven.

PTBurnSDK  Page11of68
©2011PrimeraTechnology,Inc.PrimeraisaregisteredtrademarkandBravoisatrademarkofPrimeraTechnology,Inc.Allothertrademarks
arethepropertyoftheirrespectivecompanies.
2.1.11 Copies
Thisspecifieshowmanycopiesyouwantcreated.Therangeofvaluesisfrom1to10,000.The
defaultis1ifthiskeyisnotgiven.

2.1.12 PrintLabel
Thisspecifiespathandfilenameofthelabeltoprintondisc.
Thepossiblefiletypesare.STD(SureThing™),.jpg(JPEG),.bmp(WindowsBitmap),or.PRN
(printedtofilethroughanyapplication).Ifthiskeyisnotgiventhennoprintingwillbe
performed.Forprintingmergetextandpictures(uniquetextand/orpicturesoneachdisc)see
thesupportingSureThingdocumentationfromMicrovision(sometipsarealsogivenbelow).

2.1.13 VolumeName
Thisstringspecifiesthevolumelabelname.Thestringcanbeupto32characters,butusually
onlythefirst11charactersarevisibleonasystem.Ifthiskeyisnotgiventhenthedefaultwill
betheJobIDstring(iftheJobIDstringisnotgiventhenthedefaultwillbe“NewDisc”)

2.1.14 BurnSpeed
Thisintegervaluespecifiesarequestedrecorderburnspeed.Therangeisfrom1to100.This
correspondsto1xto100x(eventhough100xrecordersarecurrentlynotavailable).Ifthiskey
isnotgiventhentherecorderwillburnatMAXspeed(oryoucansetBurnSpeed=0forMAX
speed).Iftherecorderisnotcapableoftherequestedburnspeed,thenthenearestavailable
speedwillbeused.

2.1.15 VerifyDisc
Thisspecifiesifthediscmustbeverifiedornot.Possiblevalues:
YES
NO
ThedefaultvalueisNOifthiskeyisnotgiven.

2.1.16 RejectIfNotBlank
Thisspecifiesifadiscshouldberejectedifisnotblank.Possiblevalues:
YES
NO
ThedefaultvalueisNOifthiskeyisnotgiven.WhenavalueifYESisgiventhenthediscwillbe
rejectedunlessblankmediaisinserted.NOmeansthatitwillattempttoaddasessionifone
alreadyexists.

2.1.17 NotifyClient
Thiskeyspecifiesiftheclientwantstobenotifiedwhentheirjobiscomplete(pass,fail,or
abort).

PTBurnSDK  Page12of68
©2011PrimeraTechnology,Inc.PrimeraisaregisteredtrademarkandBravoisatrademarkofPrimeraTechnology,Inc.Allothertrademarks
arethepropertyoftheirrespectivecompanies.
Possiblevalues:
Message
Disabled
ThedefaultvalueisDisabledifthiskeyisnotgiven.WhenavalueofMessageisgiventhenthe
clientwillbenotifiedviaanetmessage.Ifthisfeatureisused,theClientIDkeymustbesetto
theclient’scomputername.ThisfunctionworksforWindowsXPbutnotWindowsVistaor
Windows7.

2.1.18 PreserveISOVariations
Thiskeyforcestherecordingenginetopreservethefilenameasisevenifitisoutof
specification.Possiblevalues:
YES
NO
ThedefaultvalueisNOifthiskeyisnotgiven.
2.1.19 ReadDataTo
Thiskeyspecifiesthelocationtowhichdatafromthedisc(s)shouldbestored(thisisusefulfor
savingthecontentsofadiscforlateruse).IftheReadDataFormatkeyissettoReadData,then
thiskeycontainsthepathofwherethedatafromthediscshouldbewrittentotheharddisk
drive(ex.C:\MyDisc1).IfReadDataFormatisReadGI,thenReadDataTospecifiesthepathand
GIfilenamethatshouldbecreated(ex.\\Computer\PTBurnJobs\ReadFilewouldcreatethe
globalimagefile\\Computer\PTBurnJobs\ReadFile.gi).WhenusingReadGIastheformatyou
shouldNOTspecifythe.giextensionintheReadDataTokeybecausePTBurnwillappendthe.gi
extensiontothename.
2.1.20 ReadDataFormat
Thiskeyspecifiestheformatinwhichthedisc(s)willbestoredontotheharddiskdrive(intothe
locationspecifiedbyReadDataTo).Thepossiblevaluesareasfollows:
ReadGI
ReadData
ThedefaultvalueisReadData,whichwillreadthedatafromthediscandstorethesamedata
ontotheharddiskdrive.ReadGIwillcreateaGlobalImagefileoftheDisc.Iftheformatis
ReadGIandthenumberofcopiesisgreaterthan1,thena_0,_1…willbeappendedtotheGI
filename.
NOTE:anyfiles,including.GIfileswillbeoverwritteniftheyalreadyexist.
2.1.21 CreateSubFolders
ThiskeywillcausePTBurntocreateasubfolderbelowtheReadDataTopathforeachdiscread.
ThesubfolderswillbenamedDisc_0,Disc_1…Thepossiblevaluesare:
YES
NO
ThedefaultvalueisNOifthiskeyisnotgiven.ThiskeyisonlyvalidifReadDataToisspecified,
ReadDataFormat=ReadData,andthenumberofcopiesisgreaterthan1.
NOTE:Beforestartingthejob,thesubfoldersDisc_0,Disc_1,…,shouldbedeleted,renamed,or
movediftheyalreadyexistinthelocationspecifiedbyReadDataTo.

PTBurnSDK  Page13of68
©2011PrimeraTechnology,Inc.PrimeraisaregisteredtrademarkandBravoisatrademarkofPrimeraTechnology,Inc.Allothertrademarks
arethepropertyoftheirrespectivecompanies.
2.1.22 CheckFileOnDisc
ThiskeywillcausePTBurntocheckthediscpriortorecordingtoseeifthespecifiedfileexists.
Thevalueofthiskeyshouldbethecompletepath(onthedisc)ofthefile.Forexample:

CheckFileOnDisc=Server\myFile.txt

willcausePTBurntochecktoseeifthefile“myFile.txt”isonthediscinthe“Server”folder.If
thefileisnotfoundthenanInvalidMediaError(Job/DiscError10)willbeset.
2.1.23 CheckSystemIDOnDisc
ThiskeywillcausePTBurntocheckthediscpriortorecordingtoseeiftheSystemIDvaluein
thePVDmatchesthevalueofthiskey.

CheckSystemIDOnDisc=PTBurn

willcausePTBurntochecktoseeifthesystemIDinthePVDonthediscissetto“PTBurn”.If
thevalueisnotfoundthenanInvalidMediaError(Job/DiscError10)willbeset.
2.1.24 CheckVolumeIDOnDisc
ThiskeywillcausePTBurntocheckthediscpriortorecordingtoseeiftheVolumeIDvaluein
thePVDmatchesthevalueofthiskey.

IfthevalueisnotfoundthenanInvalidMediaError(Job/DiscError10)willbeset
2.1.25 CheckPubIDOnDisc
ThiskeywillcausePTBurntocheckthediscpriortorecordingtoseeifthePublisherIDvaluein
thePVDmatchesthevalueofthiskey.

IfthevalueisnotfoundthenanInvalidMediaError(Job/DiscError10)willbeset.

2.1.26 CheckPreparerIDOnDisc
ThiskeywillcausePTBurntocheckthediscpriortorecordingtoseeiftheDataPreparerID
valueinthePVDmatchesthevalueofthiskey.

IfthevalueisnotfoundthenanInvalidMediaError(Job/DiscError10)willbeset.
2.1.27 CheckAppIDOnDisc
ThiskeywillcausePTBurntocheckthediscpriortorecordingtoseeiftheApplicationIDvalue
inthePVDmatchesthevalueofthiskey.

IfthevalueisnotfoundthenanInvalidMediaError(Job/DiscError10)willbeset.


PTBurnSDK  Page14of68
©2011PrimeraTechnology,Inc.PrimeraisaregisteredtrademarkandBravoisatrademarkofPrimeraTechnology,Inc.Allothertrademarks
arethepropertyoftheirrespectivecompanies.
2.1.28 PVDSystemID
ThiskeywillsettheSystemIDvalueofthePVD.Thismaxnumberofcharactersforthiskeyis
32.
2.1.29 PVDPublisherID
ThiskeywillsetthePublisherIDvalueofthePVD.Thismaxnumberofcharactersforthiskeyis
128.
2.1.30 PVDPreparerID
ThiskeywillsetthePreparerIDvalueofthePVD.Thismaxnumberofcharactersforthiskeyis
128.
2.1.31 PVDApplicationID
ThiskeywillsettheApplicationIDvalueofthePVD.Thismaxnumberofcharactersforthiskey
is128.
2.1.32 LoadUnloadOverride
Thiskeywillenablethemanualloadandunloadfunctionality.
YES
 NO
ThedefaultvalueisNOifthiskeyisnotgiven.ThiskeyallowsyoutoPauseafterthedriveis
loaded(beforeburning)andalsoallowsyoutoPauseafterburning(beforethedriveis
unloaded).ItalsoallowsyoutoLoad/Unloadthedrivewithoutburning(e.g.readdisccontents
only).
PleaseseeAppendixDfordetailsregardingmanualloadandunload.
2.1.33 PreMasterData
Thiskeywillenablepre‐masteringofdatajobs.Thismeansthatwhenthejobisstarteda
temporaryimagewillbecreatedandtheneachdiscinthejobwillbeburnedfromthatimage.
Otherwiseeachdiscwillbeburnedasaseparatedatadisc.WerecommendsettingthistoYES
ifyouareburningalargenumberoffiles,orthereisthepossibilitythatafilecouldchange
duringtheburnprocess.
YES
 NO
ThedefaultvalueisNOifthiskeyisnotgiven.

IMPORTANTNOTE:IfyouareburningtoDVD,thenyoumustspecifythiswithanotherkey:
DiscType=DVDR
Ifnotspecified,thenitwillbeassumedthatyouwanttopre‐masteraCD.
2.1.34 DriveID
ThisKeyisusedtospecifyadrivetobeusedinajob.TherecanbemorethanoneDriveIDkey
inajrqfile.TheDriveIDshouldbesettothedriveindex,whichcanbefoundintheStatusfile
(SeeDriveDescXinSection3.4.22).IfnoDriveIDisspecifiedthenalldrivesintherobotwillbe
used.ForExample:


PTBurnSDK  Page15of68
©2011PrimeraTechnology,Inc.PrimeraisaregisteredtrademarkandBravoisatrademarkofPrimeraTechnology,Inc.Allothertrademarks
arethepropertyoftheirrespectivecompanies.
IftheJRQSpecifies
DriveID=0

AndtheStatusfilehasthefollowingentry
DriveDesc0=HL‐DT‐STCD‐RWGCE‐8526B1.02
DriveLocation0=RoboticRecorder

Then,inthisexample,onlythetopdrivewillbeusedinthejob.
2.1.35 BinID
Thiskeyisusedtospecifyfromwhichbintopickadiscandwheretooutputthedisc.The
behaviorofBinIDdependsonwhetherKioskmodeissetornot.(SeeSection3.1.2.11to
determineifKioskModeisenabledornot.SeeSection4.15toenable/disableKioskMode).
ValidvaluesforBinIDare0,1,or2

KioskModeEnabled:
BinIDDiscPickedfromDiscOutputto
0BothBinsFrontKioskarea
1LeftBinFrontKioskarea
2RightBinFrontKioskarea

KioskModeDisabled:
BinIDDiscPickedfromDiscOutputto
0RightBinLeftBin
1LeftBinFrontKioskarea
2RightBinFrontKioskarea

2.1.36 TestRecord
Thiskeyisusedtospecifyifyouwantthedisctobetestedinsteadorrecorded.Thisisuseful
whenrunningtestswhereyoudonotwanttowastemediabyburningit.Thepossiblevalues
are

YES
 NO
ThedefaultvalueisNOifthiskeyisnotgiven.

2.1.37 PrintQuality
Thiskeyspecifiestheprintquality.Ifthiskeyisnotspecifiedthenthedefaultdrivervaluewill
beused.Thepossiblevaluesarelistedbelow.
Low=0
Medium=1
Better=2
High=3
Best=4

PTBurnSDK  Page16of68
©2011PrimeraTechnology,Inc.PrimeraisaregisteredtrademarkandBravoisatrademarkofPrimeraTechnology,Inc.Allothertrademarks
arethepropertyoftheirrespectivecompanies.

ThedefaultdrivervaluecanbechangeinthePrinterPreferencesdialogwhenviewingthe
printersonWindows.

2.1.38 PrintInnerDiam
Thiskeyspecifiestheinnerdiameteroftheprint.Theunitsforthiskeyare.1mm.Therangeof
valuesisfrom150–500(.1mm).Ifthiskeyisnotspecifiedthenthedefaultdrivervaluewillbe
used.

ThedefaultdrivervaluecanbechangeinthePrinterPreferencesdialogwhenviewingthe
printersonWindows.
2.1.39 PrintOuterMargin
Thiskeyspecifiestheouterdiameteroftheprint.Theunitsforthiskeyare.1mm.Therangeof
valuesisfrom0–20(.1mm).Ifthiskeyisnotspecifiedthenthedefaultdrivervaluewillbe
used.

ThedefaultdrivervaluecanbechangeinthePrinterPreferencesdialogwhenviewingthe
printersonWindows.

2.1.40 MergeField
Thiskeyspecifiesa“Merge”fieldforSureThingprinting(eithermergetextormergepicture).
NotethattheprintfilespecifiedwithintheJRQmustbeaSureThingfile,anditmusthavebeen
designedwithaMergeFilespecified.
Thiskeyisnotneededifthemergefileexists.Thereasonforthiskeyisconvenience;byusing
thiskeythemergefiledoesnotneedtosaved.Insteadyoucanspecifythemergefieldswithin
theJRQusingthiskey.

Example:
MergeField=Kevin’sMergeJobDisc
MergeField=C:\images\logo.bmp
MergeField=C:\DocumentsandSettings\kevin\MyDocuments\MyPictures\sample.jpg

Thisexampleisforadiscthatwasdesignedwithonemergetextfieldandtwomergepictures.
NotethatthefieldsshouldbespecifiedinthecorrectordertomatchtheSureThingdesign.

TIP:WhendesigningtheoriginalSureThingimageyoumustbesuretofollowthesesteps:
1. OpenanewSureThingdesign.
2. InsertthenumberofdesiredmergefieldsintheSureThingdesign.Bothtextand
picturescanbemerged.Foreachtype,followthesestepsinSureThing‐‐
a. MergeText:Tools/InsertField,MergeFieldstab,FieldOne,Two…
b. MergePhoto:Tools/ObjectTools/PictureTool,enablethe‘Merge’checkbox,
FieldOne,Two….

PTBurnSDK  Page17of68
©2011PrimeraTechnology,Inc.PrimeraisaregisteredtrademarkandBravoisatrademarkofPrimeraTechnology,Inc.Allothertrademarks
arethepropertyoftheirrespectivecompanies.
3. Createa“dummy”mergetextfile.Intheexampleabovewewouldcreateafilecalled
MyMergeFile.txtwiththefollowingcontents:
“TextField1”,“MyImage1.jpg”,“MyImage2.jpg”
4. AssociatethemergetextfilewiththeSureThingdesign–todothis,clickTools/Set
MergeFileandbrowsetothenewlycreatedMyMergeFile.txt.
5. SavethenewSureThingdesignfile.
Now,thisnewlycreatedSureThingdesignfile(.STD)canbespecifiedinPTBurnandthevalues
specifiedwith“MergeField”willbeinsertedintotheimageatprinttime.

Additionalnotes:
Themergetextfileisonlyrequiredatdesigntime;duringrun‐timeitisnolongerrequired.If
theoriginalmergefileisnotfoundatprinttime,thenanewfilewillbecreatedinthesame
folderastheSureThingdesignfile.However,iftheoriginalmergetextfileisfound,thenthe
valuesinitarepopulatedwithvaluesfromtheJRQMergeFieldvalues(andanyunusedfieldsin
themergefilewillberemoved).

2.1.41 RobotName
Thiskeyspecifiesaparticularrobottouseforthejob.Thenamemustbeonelistedin
[RobotList]asdescribedinSection3.1.2.Thisisusefulinamultiplerobotscenariowhenyou
wanttospecifyaparticularrobotforthejob.

Example:
RobotName=DiscPublisherXRP(Copy1)

Note:
IfAutoSwitchRobot=TRUEinPTSETUP.INIandtherobotspecifiedusingRobotNamehasan
error,PTBurnwillautomaticallyswitchtoarobotwithoutanyerrors.

2.1.42 PrintReject
Thisspecifiesifthediscshouldbeprintedwith“Reject”iftheburnisrejected.
YES
NO
ThedefaultvalueisNOifthiskeyisnotgiven.

2.1.43 CDTextDiscTitle
ThiskeyspecifiestheCD‐Textfieldrepresentingthedisc’stitle.Thisentryisrequiredwhen
doinganaudiodiscwithCD‐Text(oneentryperdisc).Themaximumnumberofcharactersis
100.ThetotalnumberofcharactersforCDTextDiscTitleandallCDTextTrackTitleentriescannot
exceed2000characters
2.1.44 CDTextDiscPerformer
ThiskeyspecifiestheCD‐Textfieldrepresentingthedisc’sperformer.Thisentryisrequired
whendoinganaudiodiscwithCD‐Text(oneentryperdisc).Themaximumnumberof

PTBurnSDK  Page18of68
©2011PrimeraTechnology,Inc.PrimeraisaregisteredtrademarkandBravoisatrademarkofPrimeraTechnology,Inc.Allothertrademarks
arethepropertyoftheirrespectivecompanies.
charactersis100.ThetotalnumberofcharactersforCDTextDiscPerformerandall
CDTextTrackPerformerentriescannotexceed2000characters.

2.1.45 CDTextDiscComposer
ThiskeyspecifiestheCD‐Textfieldrepresentingthedisc’scomposer.Thisentryisrequired
whendoinganaudiodiscwithCD‐Text(oneentryperdisc).Themaximumnumberof
charactersis100.ThetotalnumberofcharactersforCDTextDiscComposerandall
CDTextTrackComposerentriescannotexceed2000characters.

2.1.46 CDTextTrackTitle
ThiskeyspecifiestheCD‐Textfieldrepresentingthetrack’stitle.Thisentryisrequiredforeach
trackwhendoinganaudiodiscwithCD‐‐Text.Themaximumnumberofcharactersforeach
entryis100.TheCD‐Textfieldswillbeassociatedwiththeirrespectivetrackbasedonthe
orderitappearsintheJobRequestFile.Forexample:

AudioFile=myfile1.mp3
AudioFile=myfile2.mp3

CDTextTrackTitle=Firsttrack
CDTextTrackTitle=Secondtrack

Track1willbemyfile1.mp3withtheCD‐TextTrackTitleforthetracksetto“Firsttrack”.Track
2willbemyfile2.mp3withtheCD‐TextTrackTitleforthetracksetto“Secondtrack”.
2.1.47 CDTextTrackPerformer
ThiskeyspecifiestheCD‐Textfieldrepresentingthetrack’sperformer.Thisentryisrequired
foreachtrackwhendoinganaudiodiscwithCD‐Text.Themaximumnumberofcharactersfor
eachentryis100.
2.1.48 CDTextTrackComposer
ThiskeyspecifiestheCD‐Textfieldrepresentingthetrack’scomposer.Thisentryisrequiredfor
eachtrackwhendoinganaudiodiscwithCD‐Text.Themaximumnumberofcharactersfor
eachentryis100.


2.2 ProgrammingExamples
2.2.1 SimpleDataJob
Test1.JRQintheJobRequestFolderhasthecontents:

Data=c:\MyBackup


PTBurnSDK  Page19of68
©2011PrimeraTechnology,Inc.PrimeraisaregisteredtrademarkandBravoisatrademarkofPrimeraTechnology,Inc.Allothertrademarks
arethepropertyoftheirrespectivecompanies.
ThiswillburnoneCD‐Rdiscwithallthefilesandsubfolderswithinthec:\MyBackupfolder.It
willbeaJolietfilesystem,Mode1,Track‐at‐once,not‐closeddisc(seeotherdefaultsabove).
2.2.2 SimpleAudioJob
Test2.JRQintheJobRequestFolderhasthecontents:

AudioFile=c:\MyMusic\MyTrack1.wav
AudioFile=c:\MyMusic\MyTrack2.mp3,Pregap75
AudioFile=c:\MyMusic\MyTrack3.wma,Pregap150
BurnSpeed=8
CloseDisc=YES
Copies=2

Thiswillburn2CD‐Raudiodiscswiththreetracks.The.wav,.mp3,and.wmawillbeconverted
andburnedasCD‐Audioautomatically.MyTrack2willhavea1secondpausebeforeitand
MyTrack3willhavea2secondpausebeforeit.Thediscswillbeburnedat8x(orascloseas
possible)andthediscwillbeclosed.
2.2.3 BurnandPrintjobof5discswithmanyoptionsspecified
Test3.JRQintheshared‐folderlocationhavethecontents:

JobID=Kevin’sPhotos
ClientID=COMPANYX‐KEVIN1
Data=\\SERVER\PTBurnJobs\KevinsJob\Photos\Data
Data=c:\MyBackup\File1.jpg
DeleteFiles=YES
DataImageType=ISOLEVEL1,SAO,SETNOW
CloseDisc=YES
Copies=5
PrintLabel=\\SERVER\PTBurnJobs\KevinsJob\Print\Photos.std
VolumeName=MyPhotos
VerifyDisc=YES
NotifyClient=Message

Thiswillburn5CD‐Rdiscswithallthefilesandsubfolderswithinthesubfolder
\\SERVER\PTBurnJobs\KevinsJob\Photos\Dataanditwillalsoburnthefile
C:\MyBackup\File1.jpg.Thediscwillbeverifiedafterburning.TheSureThinglabelfile
\\SERVER\PTBurnJobs\KevinsJob\Print\Photos.stdwillbeprintedoneachdisc.Thediscswillbe
closed‐sessionDisc‐at‐oncewithISO9660Level1filesystem,andthetime/dateofthefileswill
besettothetimeatwhicheachdiscisburned.Aftercompletingthejob,PTBurnwilldeleteall
thefilesandsubfolderswithinandincludingthesubfolder\\SERVER\PTBurnJobs\KevinsJob.
NotethatthefileC:\MyBackup\File1.jpgwillnotbedeleted.
BecausetheNotifyClientkeyissettoMessage,whenthejobiscompletedanetmessagewill
besenttothecomputerCOMPANYX‐KEVIN1.

PTBurnSDK  Page20of68
©2011PrimeraTechnology,Inc.PrimeraisaregisteredtrademarkandBravoisatrademarkofPrimeraTechnology,Inc.Allothertrademarks
arethepropertyoftheirrespectivecompanies.
2.2.4 PrintOnlyJobof25Discs
JobID=MyPrintJob
ClientID=MyWorkstation
PrintLabel=\\SERVER\PTBurnJobs\MyJob\MyImage.STD
Copies=25
2.2.5 ReadDataJobof3Discs
ClientID=MyComputer
JobID=Job0
Importance=2
Copies=3
NotifyClient=Message
ReadDataTo=\\MyComputer\PTBurnJobs\ReadData
ReadDataFormat=ReadData
CreateSubFolders=YES
2.2.6 ReadGlobalImageJobof3Discs
ClientID=MyComputer
JobID=Job0
Importance=2
Copies=3
NotifyClient=Message
ReadDataTo=\\MyComputer\PTBurnJobs\ReadData
ReadDataFormat=ReadGI

ThiswillcreateaGIglobalimagefileforeachofthe3discsatthefollowinglocations:

\\MyComputer\PTBurnJobs\ReadData_1.gi
\\MyComputer\PTBurnJobs\ReadData_2.gi
\\MyComputer\PTBurnJobs\ReadData_3.gi
