Ptburn sdk

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, Disc Publisher 4100 Series (including XRP), Disc Publisher SE-3, and Disc Publisher 4200 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, Windows 7, Windows 8 and Windows 10. 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

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.1Command Keys/Values

2.1.1JobID

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.2ClientID

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.3Importance

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.4Data

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.

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.5AudioFile

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:

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.6ImageFile

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
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.7DeleteFiles

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.8ImageType

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.

2.1.9DataImageType

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.10CloseDisc

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.

2.1.11Copies

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.12PrintLabel

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.13VolumeName

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.14BurnSpeed

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.15VerifyDisc

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.16RejectIfNotBlank

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.17NotifyClient

This key specifies if the client wants to be notified when their job is complete (pass, fail, or abort).

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.18PreserveISOVariations

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.19ReadDataTo

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.20ReadDataFormat

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.21CreateSubFolders

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.

2.1.22CheckFileOnDisc

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.23CheckSystemIDOnDisc

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.24CheckVolumeIDOnDisc

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.25CheckPubIDOnDisc

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.26CheckPreparerIDOnDisc

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.27CheckAppIDOnDisc

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.

2.1.28PVDSystemID

This key will set the SystemID value of the PVD. This max number of characters for this key is 32.

2.1.29PVDPublisherID

This key will set the PublisherID value of the PVD. This max number of characters for this key is 128.

2.1.30PVDPreparerID

This key will set the PreparerID value of the PVD. This max number of characters for this key is 128.

2.1.31PVDApplicationID

This key will set the ApplicationID value of the PVD. This max number of characters for this key is 128.

2.1.32LoadUnloadOverride

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.33PreMasterData

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.34DriveID

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:
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.35BinID

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.37PrintQuality

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
The default driver value can be change in the Printer Preferences dialog when viewing the printers on Windows.

2.1.38PrintInnerDiam

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.39PrintOuterMargin

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.40MergeField

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 --
   
   1. 
      Merge Text: Tools/Insert Field, Merge Fields tab, Field One, Two…
      
   2. 
      Merge Photo: Tools/Object Tools/Picture Tool, enable the ‘Merge’ checkbox, Field One, Two….
      
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.41RobotName

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.42PrintReject

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.43CDTextDiscTitle

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.44CDTextDiscPerformer

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 characters is 100. The total number of characters for CDTextDiscPerformer and all CDTextTrackPerformer entries cannot exceed 2000 characters.

2.1.45CDTextDiscComposer

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.46CDTextTrackTitle

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.47CDTextTrackPerformer

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.48CDTextTrackComposer

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.