ELabelPrinter

The ElabelPrinter control allows for finding out which printers are installed, reading printer properties (name, model, etc.) and for performing certain operations on the printers.

The ELabelPrinter control supports the following properties:

AsyncMethods

The AsyncMethods property is a read-write property that applies to each printer (that is, the AsyncMethods property is not an ElabelPrinter property, but a property of each individual printer). If the value is True then any method calls are executed asynchronously (not waiting for printer to process the method). If the value is False, then the methods will wait until the printer driver has processed the requested function. For example, when using the RefreshStatus method it may be useful to return immediately, knowing that the RefreshStatus method may take some time (if printer driver is downloading a graphic for example). To determine when the requested function has been completed, examine the StatusBits property and test if the elStat_RequestPending bit is set. If this bit is set, then the printer driver has not yet processed the requested function.

Count

The Count property is a read-only property that returns the number of configured EASYLABEL printers. This includes any Windows printers that have been added to the EASYLABEL printer list.

Description

The Description property is a read-only property that returns a string containing the printer description. The printer description is defined when the printer is configured in EASYLABEL. This value may be blank. The installation of this newest version changed the Description fields of all printers to blanks. If Printer Descriptions are desired they will need to be re-entered.

PrinterIndex

The PrinterIndex is a read/write property that identifies a specific printer by its index in the printer table. The printer index is a value ranging from 1 to the value returned by the Count property. Setting this value sets the current printer to the printer identified by the index number. Since the printer index can change when printers are added or deleted from the configuration, this is not a reliable way to identify a particular printer. To identify a specific printer, use the PrinterName property, which is unique to each printer.

Model

The Model property is a read-only property that returns a string containing the printer model name. The model name indicates the type of printer, but does not uniquely identify any particular printer.

PrinterName

The PrinterName property is a read/write property that uniquely identifies a specific printer. Reading this property returns the printer name. Setting this property selects a specific printer. The installation of this newest version changed the PrinterName fields of the printer properties to blanks. If you are using PrinterNames, you will have to re-enter the PrinterName for each printer.

Status

The Status property is a read-only property that returns the last status string retrieved from the printer using the RefreshStatus method. Not all printers support a status string.

StatusAge

The StatusAge property is a read-only property that returns the number of milliseconds since the Status was last updated via the RefreshStatus method.

StatusBits

The StatusBits property is a read-only property that contains bit flags indicating the status of the printer driver or of the printer itself. The following list shows the bit flags that have been implemented.

elStat_RequestPending

Method calls are being executed asynchronously (AsyncMethods = True) and the printer driver has not yet completed the requested function.

The ELabelPrinter control supports the following methods. Note that not all of these methods are supported for every printer. Unless otherwise noted in the method descriptions, these methods are put in a queue to be processed by the printer driver. If the driver is busy (downloading a graphic for example), then the method will be processed as soon as the current operation is complete. If the driver is idle (not currently processing any jobs) then the method will be executed immediately. The methods will not return until the operation has been completed by the printer driver, so there may be a delay before the method returns control to the application. To enable asynchronous method execution, set the AsyncMethods property to True.

Clear

The Clear method cancels a print job that is resident in the printer’s buffer.

This method is only supported by the Datamax driver (Datamax 2+ printers) and the Fargo driver (Datamax Standard printers). In the Fargo driver, there is a pause of 500ms after the command is sent to the printer, before returning control to the application. Also, the Fargo driver will not send any new batches (if any) after this command, where the Datamax driver will. If using the Datamax driver, it may be necessary to cancel the job before calling the Clear method.

Cancel

The Cancel method cancels all print jobs associated with the printer. This includes the current job being processed by the printer (if any). This will also clear any job resident in the printer’s buffer.

Pause

The Pause method causes the printer to stop printing. Use the UnPause method to resume printing. If the printer is idle when this method is called, any subsequent jobs sent to the printer will not start printing until the UnPause method is called.

UnPause

The UnPause method reverses the action of the Pause method. If the printer was paused, it will resume printing. Note that with some printers, Pause and UnPause are implemented with the same command, which simply toggles between the two states.

Reset

The Reset method causes the printer to be reset. This clears the printer memory of any label formats, graphics, or downloaded fonts. Usually, this is the same as powering the printer off and then back on.

TestPage

The TestPage method causes the printer to print a test pattern label and/or a printer configuration label.

SetClock

The SetClock method displays a dialog box allowing the user to enter the date and time to set the printer clock. The method will not return until the user closes the dialog box. If you want to set the printer’s clock programmatically, use the SendData method to send the appropriate commands to the printer.

Recalibrate

The Recalibrate method causes the printer to feed one or more labels past the label sensor, for the purpose of determining label length and sensor settings.

MemoryCard

The MemoryCard method displays a dialog box allowing the user to view a listing of the files stored on a memory card. The user can view information about each file, with the option of deleting files from the memory card. The method will not return until the user closes the dialog box.

HardwareReset

The HardwareReset method causes the printer to be restored to the factory default settings. Note that using this method may cause the printer to lose its communication settings or other critical settings. Use with caution.

FormFeed

The FormFeed method causes the printer to feed a label, so that the print position is at the top of the next label.

EnterDump

The EnterDump method causes the printer to enter “dump” mode. Usually, this means the printer will no longer respond to commands, it simply prints any data received in hex and/or ASCII. This may be useful for diagnosing communication problems. To exit dump mode, use the ExitDump method.

ExitDump

The ExitDump method causes the printer to revert to normal operation after being put into “dump” mode using the EnterDump method.

RefreshStatus

The RefreshStatus method updates the printer status information. The printer is queried as to its current state. Note that if the printer driver is busy when this method is called, the method may not return for up to several seconds. To retrieve the printer status, read the Status property.

SendData

The SendData method sends a data string to the printer. The data string may contain any command or data item recognized by the printer. Each type of printer has its own command language, so the data string must be formatted in the language used by the particular printer.

FreezeAll

The FreezeAll method “freezes” all print jobs associated with the printer. A frozen job will not be processed until it is “unfrozen”. See the UnFreezeAll method.

UnFreezeAll

The UnFreezeAll method “unfreezes” all of the print jobs associated with the printer. Any frozen jobs are restored to their unfrozen state and will be processed according to their print queue priority.

ELabelBatch

The ELabelBatch control allows for composing a print job and submitting it to the print queue. In order to do that user has to prepare the job properties (like FormatName, Batches, BatchSize, TestPrint etc.) and then call CreateJob method. Note that there is absolutely no connection between different instances of an ELabelBatch control: Client1 can set the FormatName property to “nut” and Client2 can simultaneously set the FormatName of his ELabelBatch instance to “screw”. If 2 clients will call CreateJob method simultaneously, then 2 jobs will be added to printer queue in an unpredictable order.

Event reporting can be enabled on a job by job basis (when the CreateJob method is called). Events for a job are always fired to the control instance that created the job. If multiple instances of the control are active, each instance receives events only for the jobs that it created.

The ELabelBatch control supports the following properties:

FormatName

The FormatName property is a read/write property that defines the filename or pathname of the label to be printed. The name should not include any filename extension. The extension “.FMT” is always assumed.

Batches

The Batches property is a read/write property that defines the number of label batches to be printed. If the format contains no incremented/decremented fields, then Batches contains the number of formats to be printed and the BatchSize is ignored. If the format does contain incremented/decremented fields, then Batches contains the number of batches (number of times to increment/decrement) and BatchSize contains the number of labels in each batch.

BatchSize

The BatchSize property is a read/write property that defines the size of each label batch. If the format contains incremented/decremented fields, then BatchSize contains the number of labels in each batch. If the format does not contain incremented/decremented fields, then BatchSize is ignored.

PrinterIndex

The PrinterIndex is a read/write property that identifies a specific printer by its index in the printer table. Setting this value sets the job’s printer to the printer identified by the index number. Since the printer index can change when printers are added or deleted from the configuration, this is not a reliable way to identify a particular printer. To identify a specific printer, use the PrinterName property, which is unique to each printer.

To direct printed output to a disk file, set the PrinterIndex property to zero, then set the OutputFile property to the pathname of the desired output file.

JobDescription

The JobDescription is a read/write property that specifies the job description text that will be shown in the print queue and associated with the created print job.

DisplayMessage

The DisplayMessage property is a read/write property that defines the message that will be displayed by EASYLABEL before the printing of the format. The default is an empty string, which means, “don’t display a message”. Note that setting this property to a non-empty string will suspend the application until the user responds to the displayed message box.

LastJobNumber

The LastJobNumber property is a read-only property that returns the number of the job created by the last call to CreateJob method. A zero or negative value indicates that the last CreateJob method call returned an error code (see below). Note that each instance of an ELabelBatch object keeps its own LastJobNumber property. Therefore, this value will never be a job number created by a different instance of an ELabelBatch object (such as one instantiated by another client application).

OutputFile

The OutputFile property is a read/write property that specifies the name of the output file when printing to a file is requested (PrinterIndex property set to 0). This property is ignored if the PrinterIndex property is nonzero.

PrinterName

The PrinterName property is a read/write property that uniquely identifies a specific printer. Reading this property returns the printer name. Setting this property selects a specific printer as the destination printer for the job.

TestPrint

The TestPrint property is a read/write property that defines the test print mode for the next batch. The value 1 means test print, 0 means normal print, all other values are reserved. If TestPrint is set to 1, then only one label is printed (or in the case of multiple-up, one row of labels) regardless of the settings of Batches or BatchSize. This can be used to check label alignment or proper entry of any variable fields.

HoldJob

The HoldJob property is a read/write property that defines whether the job will be placed in the queue “on hold” (or “frozen”). A job that is on hold will not be processed until it is released (“unfrozen”). The value for this property can be True or False. Use the ELabelJob control to modify the status of jobs in the print queue.

Field(FieldName)

The Field property is a read/write property defines the value of the label field named FieldName that will be used during printing. NOTE: the correctness of the fieldname and the specified value will not be checked until CreateJob method is called.

ShowPreview

The ShowPreview property is a read/write property that is a True/False value indicating whether the control should display the label preview bitmap. If this value is False, no label preview is shown. If True, then the label preview bitmap is displayed in the space allocated for the control.

DisableUI

The DisableUI property is a read/write property that is a True/False value. If this value is set to True, then the EASYLABEL user interface cannot be started. In other words when DisableUI is set to True trying to start EASYLABEL will do nothing.

IgnoreFieldError

The IgnoreFieldError property is a read/write property that is a True/False value. When a client application supplies data for a field that does not exist on the label an error is generated (-4). Setting this property to True will ignore this error and continue with the print job. Setting it to False will cause the CreateJob method to fail with the error code –4. Currently, IgnoreFieldError must be set in the VB application using an “ElabelBatch.IgnoreFieldError = True” statement in order for it to work.

The ELabelBatch control supports the following methods:

CreateJob(Events)

The CreateJob method creates and queues the job defined by the current properties. At a minimum, the FormatName property must be specified. To determine the success of the job creation, examine the LastJobNumber property. A positive non-zero value indicates success and the value is the job number. A negative value is an error code, and zero indicates a non-specific error condition (see below).

If the Events parameter is True, then all events related to the job are sent through the controls’ JobEvent and JobRemainCount procedures. The JobEvent procedure is notified of job start, job end, job errors, etc. The JobRemainCount is notified of the decreasing label counts of the job. Note that JobRemainCount may not be called for jobs that contain very small label counts, and that remaining label count reported will most likely jump down in increments greater than 1. For example, for a job that has 20 labels, JobRemainCount may get called with counts of 15, 10, 5, then 0.

ProcessCommand(Commands)

The ProcessCommand method executes the given Commands string. The string Commands must have the same format as a command file. See the online help for information about command files and their structure.

ProcessCommandFile(FileName)

The ProcessCommandFile method processes the command file named by the FileName parameter. The FileName must be the name of an existing command file. See the online help for more information about command files and their structure. Note that this method only works if EASYLABEL is in command file monitor mode.

UpdatePreview

After completing the required field data for a label (when printed/database fields) the UpdatePreview method will display an updated label preview bitmap in the control. The control now contains a Print Preview showing the label format as completed and ready for printing.

CreateJob Error Codes

If a call to the CreateJob method fails for any reason, an error code is set in the LastJobNumber property. This can be tested by the client application to determine the success/failure of the job creation. A positive value indicates success and is the job number of the created job. A value of zero indicates a non-specific error condition. A negative value will be one of the specific error conditions listed below.

-1 Format file not found. The format file name specified by the FormatName property could not found. Make sure that the full path is specified, or that the format file is in the current “default” directory.

-2 Format created for another printer controller. The printer type specified in the format file does not match any of the configured printers.

-3 No valid format name found. This is an internal error. This could also mean that the file path specified by the FormatName property does not refer to a valid format file. See the description of error code –1.

-4 Undefined name. A name defined by the Field() property does not match any of the variable field names in the format file.

-5 Database error. An error occurred while doing database lookups.

-6 Can’t find printer. This is an internal error indicating a missing printer control block.

-7 Can’t select printer. This is an internal error indicating an error during loading of the printer DLL.

-8 ODBC SELECT error. An error occurred during processing of an ODBC SQL SELECT statement.

-9 Can’t create job data. An error occurred during the creation of the job data. This could indicate a low memory condition.

-10 Format saved with demo version. Attempting to print a format that was created with the demo version, and a print-only sentinel device was detected.

-11 Destination file not allowed in demo. No sentinel device was detected, and the job was attempting to do a “print to file”.

-12 Invalid format count. This is an internal error.

-13 Database is empty. Attempting to print from a database and no records were selected to be printed.

-14 Out of memory. An internal error occurred while allocating memory to process the ActiveX request.

-15 No formats selected for printing. The count of formats selected to be printed is equal to zero.

-16 Can’t find report file. The selected format has an associated report file, but the report file could not be opened and/or updated.

-17 Can’t find external file. A field on the format referenced an external file which could not be found in the path specified.

If events are enabled when CreateJob is called, the following two functions will be called as each event is triggered by the printer driver.

JobEvent(JobNumber, EventID, EventDesc)

JobRemainCount(JobNumber, Remain)

The following constants are available to be used to check for various EventID’s. Note that each printer driver will only create events for a subset of these. This is a list of all events that can be generated by ALL of the printer drivers. For example, elEvent_CutterError can only be generated by printers that allow for cutters and that are able to detect a cutter error.

elEvent_Waiting 0
elEvent_Printing 1
elEvent_Error 2
elEvent_InvalidDevice 3
elEvent_Unavailable 4
elEvent_OutOfSpace 5
elEvent_InsufficientMemory 6
elEvent_PictureError 7
elEvent_GraphicLoad 8
elEvent_FontLoad 9
elEvent_Busy 10
elEvent_PaperOut 11
elEvent_RibbonOut 12
elEvent_PrinterPaused 13
elEvent_Offline 14
elEvent_CommError 15
elEvent_Frozen 16
elEvent_FontError 17
elEvent_BufferFull 18
elEvent_LabelPresented 19
elEvent_Ready 20
elEvent_CorruptRam 21
elEvent_DatabaseError 22
elEvent_CutterError 23
elEvent_HeadUp 24
elEvent_TempOutOfRange 25
elEvent_ExcessFonts 26
elEvent_ErrorReadingFile 27
elEvent_Started 28
elEvent_Ended 29
elEvent_UnableToOpen 30
elEvent_Canceled 31
elEvent_Deleted 32

ELabelJob

The ELabelJob control allows for examining and modifying jobs that are in the print queue. Jobs that are currently being printed can be queried for current print status, or the job can be cancelled. Jobs yet to be printed can be modified to change label counts or the destination printer for example.

The ELabelJob control supports the following properties:

JobCount

The JobCount property is a read-only property that indicates the number of print jobs currently in the print queue. This value changes as jobs are added to the queue, or as jobs are removed when they are completed.

JobID

The JobID property is a read/write property that contains the job identifier, a number that uniquely identifies a specific job in the print queue. A job ID is returned by the CreateJob method of the ELabelBatch control. Setting this value loads the other properties with the data related to the specified job.

Description

The Description property is a read/write property that contains a text string describing the print job. This value may be a null string (“”). This value can be changed at any time as long as the job is not currently being processed.

Status

The Status property is a read-only property that contains the status text (as displayed in the print queue).

StatusBits

The StatusBits property is a read-only property that contains a numeric value indicating the current job status. This is the same as the EventID passed to the JobEvent function of the ELabelBatch control.

OutputFile

The OutputFile property is a read/write property that specifies the name of the output file when printing to a file is requested (PrimaryPrinter property set to 0). This property is ignored if the PrimaryPrinter property is nonzero.

LastError

The LastError property is a read-only property that contains a numeric value indicating the last error that occurred for job. These are the same values as the EventID passed to the JobEvent function of the ELabelBatch control.

FormatName

The FormatName property is a read-only property that is the simple filename (no path or extension) of the label format to be printed.

TotalFormats

The TotalFormats property is a read-only property that indicates the total number of formats to be printed for the job.

FormatsLeft

The FormatsLeft property is a read-only property that indicates the number of formats remaining to be printed. This value will be less than or equal to the TotalFormats property.

Batches

The Batches property is a read/write property that defines the number of label batches to be printed. If the format contains no incremented/decremented fields, then Batches contains the number of formats to be printed and the BatchSize is ignored. If the format does contain incremented/decremented fields, then Batches contains the number of batches (number of times to increment/decrement) and BatchSize contains the number of labels in each batch. This value can be changed as long as the job is not currently being processed.

BatchSize

The BatchSize property is a read/write property that defines the size of each label batch. If the format contains incremented/decremented fields, then BatchSize contains the number of labels in each batch. If the format does not contain incremented/decremented fields, then BatchSize is ignored. This value can be changed as long as the job is not currently being processed.

PrimaryPrinter

The PrimaryPrinter is a read/write property that identifies a specific printer by its index in the printer table. Setting this value sets the job’s printer to the printer identified by the index number. Since the printer index can change when printers are added or deleted from the configuration, this is not a reliable way to identify a particular printer. To identify a specific printer, use an instance of an ELabelPrinter control to map a PrinterName to a PrinterIndex, then set the PrimaryPrinter property of the job to the PrinterIndex property of the ELabelPrinter control.

To direct printed output to a disk file, set the PrimaryPrinter property to zero, then set the OutputFile property to the pathname of the desired output file.

AlternatePrinter1

The AlternatePrinter1 property is a read/write property that identifies the first alternate printer for a print job. An alternate printer should be the same type and model as the primary printer. If an alternate printer is specified, and the primary printer is currently busy, the job will be printed on an alternate printer.

AlternatePrinter2

The AlternatePrinter2 property is a read/write property that identifies the second alternate printer for a print job. An alternate printer should be the same type and model as the primary printer. If an alternate printer is specified, and the primary printer is currently busy, the job will be printed on an alternate printer.

The ELabelJob control supports the following methods:

Cancel

The Cancel method cancels the job identified by the JobID property. If the job is currently printing, printing is stopped and the printer cleared. If the job was waiting in the queue, it is immediately removed from the queue.

RefreshStatus

The RefreshStatus method updates the status properties (Status, StatusBits, FormatsLeft, etc.) for the job identified by the JobID property. Note that the queue is “locked” while the status is being updated. Therefore it is not a good idea to call RefreshStatus in a tight loop. For more accurate status updating, it is best to use the JobEvent function of the ELabelBatch control to receive the events as they happen.

Freeze

The Freeze method causes the job identified by the JobID property to be put “on hold” (or “frozen”). A frozen job will not be processed until it is “unfrozen” (see the UnFreeze method). This method can be applied to any job that is not currently printing.

UnFreeze

The UnFreeze method releases the job identified by the JobID property. The job is said to be “unfrozen” and will be processed according to its queue priority. This method can be applied to any job that is not currently printing.

MoveUp

The MoveUp method moves the job up in the queue priority. This is accomplished by exchanging the job with the previous one in the queue. The job to be moved is identified by the JobID property. Jobs are processed from the top of the queue (the first one shown in the print queue display).

MoveDown

The MoveDown method moves the job down in the queue priority. This is accomplished by exchanging the job with the next one in the queue. The job to be moved is identified by the JobID property. Jobs are processed from the top of the queue (the first one shown in the print queue display).

ApplyChanges — This Method has NOT been implemented.

The ApplyChanges method updates the print job with any changed property values. The property values that can be changed for a job are: Batches, BatchSize, Description, OutputFile, PrimaryPrinter, AlternatePrinter1, and AlternatePrinter2.

GetJobIDFromQueue(JobIndex)

The GetJobIDFromQueue method returns a job identifier based on a job’s index in the print queue. The job ID and the job index are totally unrelated. To enumerate the jobs in the queue, loop from 1 to the JobCount value and the use GetJobIDFromQueue to get a job ID for the job. Once the job ID is obtained, then set the JobID property to retrieve the properties and/or status of a specific job.

ELabelInfo

The ELabelInfo control allows for read-only access to some of the properties of a label format. In addition, some of the field properties can be accessed. None of the properties of the label or its fields can be modified by this control. Also, not all of the properties of the label or fields are exposed.

The ELabelInfo control supports the following properties:

FormatName

The FormatName property is a read/write property that defines the filename or pathname of the label to be printed. The name MUST include the filename extension (unlike the ELabelBatch control).

FieldCount

The FieldCount property is a read-only property that gives the number of fields contained in the label.

Description

The Description property is a read-only property that is a text string containing the description of the label (if any). This value may be an empty string.

PrinterModel

The PrinterModel property is a read-only property that contains the text of the printer model name. This value is never blank.

LabelWidth

The LabelWidth property is a read-only property that is the width of the label in tenths of millimeters.

LabelHeight

The LabelHeight property is a read-only property that is the height of the label in tenths of millimeters.

PreviewBitmapAvailable

The PreviewBitmapAvailable property is a read-only property that is a True/False value. It indicates whether or not the format has a label preview bitmap. True indicates that there is a label preview available while False reveals a lack of one.

ShowPreview

The ShowPreview property is a read/write property that is a True/False value indicating whether the control should display the label preview bitmap. If this value is False, no label preview is shown. If True, then the label preview bitmap is displayed in the space allocated for the control.

Field(Index)

Field(Name)

The Field property is a read-only property that returns an object reference for the field identified by the Index (from 1 to FieldCount) or the Name string. The Field object has the following properties:

Index The index number of the field. This will be a value from 1 to the FieldCount property. Setting this value selects a field by its index, reading this value retrieves the field’s index value.

Name The name of the field. This value may be blank (fields are not required to have a name). Setting this value selects a field by its name, reading this value retrieves the field’s name.

Type The type of the field (text, barcode, etc.). This is a read-only property that returns a one-character string indicating the type of the field. H=human readable (text), B=barcode, L=line, X=box, C=circle or ellipse, P=picture (graphic image).

Source The source of the field (where the field data comes from). This is a read-only property that returns a one-character string indicating the data source. F=fixed data, W=when printed, M=database, C=copied, L=linked, S=serial file, P=date, T=time, A=arithmetic, X=external file, N=name when printed (user enters name of file containing the data), I=database indirect (database field contains name of data file).

PromptOrder The order in which fields will be prompted. This is a read-only property. This is used when there are multiple when-printed fields. This indicates the numerical sequence in which the fields will be prompted. This is a value from 1 to n, where n is the number of when printed fields.

Comment This is a read-only property that contains any comments entered for the field when the field was created/edited.

ExternalFile This is a read-only property that contains the filename or pathname of the data file that contains the field data.

MaxFieldLength This is a read-only property that contains the maximum length for a when printed or database field.

PromptLine1 This is a read-only property containing the text that will be displayed to prompt the user for the value of a when printed field.

The following Field properties are only offered if the field’s Source property is a database (M). They are empty when the source is not a database.

DBSystemName The name of the database system or data source that the field gets it’s data from. This is a read-only property.

DBTableName The name of the table or .dbf pathname that the field gets it’s data from. This is a read-only property.

NumberOfSearchFields This is a read-only property that contains the number of fields used to search the database from 1 to 3.

SearchFieldName1 This is a read-only property that contains the column name in the table for search key 1 (first column to search).

SearchFieldName2 This is a read-only property that contains the column name in the table for search key 2 (second column to search).

SearchFieldName3 This is a read-only property that contains the column name in the table for search key 3 (third column to search).

PromptLine1 This is a read-only property containing the text that will be displayed to prompt the user for the value of search field 1.

PromptLine2 This is a read-only property containing the text that will be displayed to prompt the user for the value of search field 2.

PromptLine3 This is a read-only property containing the text that will be displayed to prompt the user for the value of search field 3.

DBDataFieldName This is a read-only property that contains the name of the column used for the field data.

To access any of the field properties, use something like ELabelInfo.Field(“TEXT1”).Type to get the type of the field named “TEXT1”. Use similar statements to get the other properties.