Primera PTBurn 3 SDK, User Manual

Page 1: ...apable 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...

Page 2: ...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...

Page 3: ...le 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 tx...

Page 4: ...er 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...

Page 5: ...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 bur...

Page 6: ...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 valu...

Page 7: ...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 De...

Page 8: ...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...

Page 9: ...s 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...

Page 10: ...01 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 f...

Page 11: ...le 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 requ...

Page 12: ...hould 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 ReadD...

Page 13: ...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...

Page 14: ...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 PreMaster...

Page 15: ...ed 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...

Page 16: ...s 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...

Page 17: ...opulated 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 o...

Page 18: ...t 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 m...

Page 19: ...s 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 Y...

Page 20: ...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...

Page 21: ...ted MyJob ERR The job has finished with errors or has been aborted Additional status can be retrieved from text files containing additional detailed status information 3 1 SystemStatus txt File PTBurn...

Page 22: ...er 4 2 62 500 PxengSWVer 4 2 62 500 PxDrvSWVer 1 02 16a PxMasSWVer 4 2 62 500 PxWaveSWVer 4 2 62 500 PxHelp20SWVer 3 00 67a ServerTime 06 05 2008 17 44 27 ServerTickCount 1749 DriveSpace 123849 Below...

Page 23: ...particular robot This Robot Status file is located in the same folder as this file 3 1 3 6 DiscsInRightBin Number that contains the number of discs in the Right Bin If this value is 1 then the number...

Page 24: ...Type4 5 Magenta 3 1 3 9 CartridgeFillX Number that contains the percent fill of the cartridge The X will be replaced with a value CartridgeFill0 represents the leftmost cartridge If the robot contains...

Page 25: ...if the PTBurn Service is still running and updating status 1 tick count 1 second 3 1 4 4 ServerTime Current time obtained by the PTBurn application on the server computer on which PTBurn is running F...

Page 26: ...s Besides the SystemStatus txt file PTBurn will also create a more detailed status file for each robot the name of the file s will be RobotName txt e g Disc Publisher SE txt The structure of this stat...

Page 27: ...iscsInLeftBin 6 DiscsInRightBin 4 CartridgeType0 2 CartridgeFill0 96 CartridgeType1 1 CartridgeFill1 95 Top Recorder BadDiscs 3 GoodDiscs 4 ReadingErrors 0 ReadingErrorsMedia 0 RecordingErrors 0 Recor...

Page 28: ...section are keys that can provide the list of the current jobs being processed by PTBurn The Key value of the current job is always Job0 the next job is Job1 etc So an example might be JobList Job0 My...

Page 29: ...s MyJob1 The keys under each job s details section are 3 2 4 1 JobID String that the describes this job 3 2 4 2 ClientID String that describes the client of this job 3 2 4 3 JobsAhead Integer value th...

Page 30: ...arted yet the value is blank space 3 2 4 11 TimeCompleted String that gives the time and date of when the job was completed Format is MM DD YYYY hh mm ss XX where XX is either AM or PM If not complete...

Page 31: ...two times before successfully burning on its third attempt In this example the entries for this job will be DiscErrorIndex0 3 DiscErrorIndex1 3 3 2 4 16 DiscErrorNumberX Integer value that details wha...

Page 32: ...cDriveX If the LoadUnloadOverride key is set in the jrq file then PTBurn will report the drive letter that is processing the disc X is a value from 0 to the number of drives in the robot ie 0 for the...

Page 33: ...r value that tells how many drives are managed by the robotics for the Disc Publisher this will be 1 3 2 5 4 GoodDiscsLife Integer value that tells how many discs have been successfully completed in t...

Page 34: ...the drive letter key DriveLetter0 F DriveLetter1 G 3 2 5 13 DriveLocationX String that contains the location of robotically controlled drives on the system The X represents an index if multiple robot...

Page 35: ...update of this value 3 2 5 19 DiscsInLeftBin Number that contains the number of discs in the Left Bin If this value is 1 then the number is unknown This value is updated each time a disc is picked fro...

Page 36: ...est value of Yellow Magenta Cyan CartridgeFill2 59 Yellow CartridgeFill3 37 Cyan CartridgeFill4 100 Magenta 3 2 5 22 SerialNum Serial number of the unit This key is only valid on Disc Publisher se Dis...

Page 37: ...ingErrors The number of bad discs produced by this drive that were a result of recording errors that were not media related ie not Sense 03 3 2 6 6 RecordingErrorsMedia The number of bad discs produce...

Page 38: ...nd then the client decides that this job should be aborted the client must create a new file called MyJob1 PTM Note that the ClientID must be specified and it MUST match the ClientID in the correspond...

Page 39: ...RINTER ClientID Administrator RobotName zzzz The ClientID should ALWAYS be fixed to Administrator RobotName zzzz specifies which printer robot to align e g Disc Publisher SE If RobotName is not specif...

Page 40: ...was set to YES in the jobs jrq file Message PROCESS_DISC DiscID X The DiscID should contain the id of the disc that is being processed ie the X value from LoadDiscStateX in the Status file See Append...

Page 41: ...Connect This command is used to simulate a new USB Disc publisher being connected This is mainly used for testing and demonstration The PTBurn service will automatically detect this when running Messa...

Page 42: ...rogramming Tips 5 1 1 Reading the Status File The status file should NOT be opened in a locked state To ensure this you should either open the file with FileShare set to FileShare ReadWrite or use Get...

Page 43: ...Pic2 jpg and Pic3 jpg Save this file Note that you can modify the Merge file just before print time to allow you to replace the text photos with anything you want or you can use the MergeField key in...

Page 44: ...tos with alternate names PicX jpg PicY jpg and PicZ jpg for example then you need to modify the Merge file to call out these new filenames Again you can have PTBurn do the work for you by specifying M...

Page 45: ...re launching PTBurn exe To find the directory where the PTBurn executable is located you can query the Registry key called AppPath which is located in the same location in the Registry PTSETUP INI Set...

Page 46: ...teAllCopies TRUE Specifies what to do with in process inp jobs on startup This key has no effect on jobs that were completed aborted or errored out DON or ABT or ERR Kill will automatically kill the I...

Page 47: ...problem a 10sec delay will usually fix the problem DriveDelay 2 This string will set the temp path that the recording engine uses to store temporary data necessary to burn the disc The folder must ex...

Page 48: ...e robot goes into an error condition and there are multiple robots attached AutoSwitchRobot FALSE SHARED FOLDER This is the local path of where the Shared Folder PTBurnJobs will be created The shared...

Page 49: ...on all 2 bin robots 0 kiosk mode set by ptm message Default mode 1 Kiosk mode always on 2 Kiosk mode always off If you specify 1 or 2 for this key then the Kiosk mode ptm is ignored KioskMode 0 LightS...

Page 50: ...folders one for Unicode 2 byte fonts and one MBCS 1 byte fonts choose the one appropriate for your application Each vendor can perform some customization by editing the loose file PTSETUP INI before d...

Page 51: ...ystem and Burn Engine Error Codes System Errors System errors are defined in the table below These are errors that occur that require administrator attention PTBurn provides these error numbers and me...

Page 52: ...d while moving into the Printer 20 Administrator attention Disc was dropped while moving into the Left Bin 21 Administrator attention Disc was dropped while moving to Reject Front Slide 22 Administrat...

Page 53: ...the lid System Error 3 The input bin is empty Add more discs and push the Cartridge button left button on the unit System Error 4 There was an internal printer communications error Press the Cartridge...

Page 54: ...es from the Disc Publisher including power Then plug all cables back into the Disc Publisher re boot the computer and then re start the software Note This error will occur only at the start of the sof...

Page 55: ...Click Yes to align the printer or No to quit the application System Error 23 Not used in Disc Publisher II The color cartridge is invalid To change the cartridge open the cover press the Cartridge but...

Page 56: ...XRP This printer is not compatible with a pigment based cartridge To change the cartridges open the cover press the Cartridge button change the cartridge close the cover and press Ok to continue Syste...

Page 57: ...e new cartridge and close the cover To ignore the warning press the left button System Error 38 The system timed out waiting for the printer to finish The disc may not have been printed System Error 3...

Page 58: ...valid Job 10 The media CD DVD is invalid Disc 11 The media CD DVD has insufficient space Disc 12 The media CD DVD is not blank Disc 13 The drive failed to open close Job 14 The drive failed to become...

Page 59: ...e maximum files folders that can be burned is 99 However files that are contained within a folder that is specified do not count towards the maximum This error will cause the job to fail Job Disc Erro...

Page 60: ...he drive that is being used for a job is not the drive in the Disc Publisher This error can occur when the Disc Publisher drive is not seen by the server and there is another external recorder on the...

Page 61: ...ur if the CD Text is in an invalid format or exceeds the maximum CD Text length 6000 bytes This error will cause the job to fail Job Disc Error 28 This error will occur if the CD printing application...

Page 62: ...will cause the job to fail Job Disc Error 35 This error will occur if the disc image cannot be created This error will cause the job to fail Job Disc Error 36 This error will occur if status cannot b...

Page 63: ...ALIDMEDIUM 9 The function was passed a pointer to a target unit containing media that is not blank PRIMOSDK_RUNNING 10 The operation whose status is being queried is currently running PRIMOSDK_BUR 11...

Page 64: ...VERFLOW 32 A temporary file went into overflow PRIMOSDK_DVDSTRUCTERROR 33 A data structure includes a VIDEO_TS or AUDIO_TS folder that is not compliant with DVD Video or DVD Audio rules PRIMOSDK_FILET...

Page 65: ...unloading the disc to the printer and want to be able to control whether the disc passes or fails based on their verification User submits a Recording Printing job with LoadUnloadOverride YES Once th...

Page 66: ...he user s special verification procedure fails the client can send the Reject Disc message as detailed below This will cause the hold state to end and the disc will fail and be rejected appropriately...

Page 67: ...lity for Audio discs Sections 2 1 43 to 2 1 48 Added missing documentation for CurrentStatusState in section 3 2 4 20 Updated information for ReadDataFormat 2 1 20 and CreateSubFolders 2 1 21 Moved Se...

Page 68: ...tate Added Section 3 2 4 21 DriveLetter to get the drive letter for the recorder Updated several of the Status file sections to clarify Added UDF250 UDF260 options to DataImageType 1 28 08 document ve...