Product Logo

CNS Barcode

Scan and Generate Barcodes


Coding Considerations

##Getting Results

When calling the plug-in through functions or some script steps, you can get information back from the plug-in about what it is doing. How you get results depends if you are using functions or script steps to call the plug-in.

###Functions Every time you use a CNS Barcode function, status text is returned back from the plug-in. This information can be very useful for letting you know if an error occurred. Consider the following:

CNSBC_AddProfile ( “Scan Widget” )

The above code will add a profile named “Scan Widget”. If it was successful, the plug-in will return:

Profile ‘Scan Widget’ Added.

However, if there was an error with the Profile Name (for example, it was blank), the plug-in will return something like:

ERROR: AddProfile: You must specify the Name for the new Profile (‘ProfileName’ parameter).

###Script Steps

Not all of the plug-in’s script steps return results. Whether the script step will return something is determined if it has the “Target” parameter. This script step parameter allows you to specify a Field or Variable to hold the result data. For example, consider the Send script step:

CNSBC Generate [ Select; Target: Generate::Barcode ; Type:QR Code ]

When you select the CNSBC Generate script step and view the parameters of the step, the Target parameter specifies where the barcode image will go. In the example above, after the script step is run, the “Generate::Barcode” field will contain the barcode image.

##Error Checking

Including error checking in your scripting is vital to writing robust email scripts that will not break when something does not work correctly. How error checking is implemented depends if you are using the functions or script steps.

###Functions

When using the plug-in’s functions, consider the following:

Set Field [ Generate::Barcode ; CNSBC_Generate( “QRCode”; Generate::Data )]

The above code will generate a barcode. If it was successful, the plug-in will return the barcode image to the “Generate::Barcode” container field. However, if an error occurred for any reason, the plug-in will return an error to the field. For example:

ERROR: Generate: Error creating barcode: error: Invalid characters in data

Notice the error begins with “ERROR:”. Since all errors begin with this, you can write your scripts to look for this string. For example:

Set Field [ Generate::Barcode ; CNSBC_Generate( “QRCode”; Generate::Data )]
If[ PatternCount( Generate::Barcode ; “ERROR:” ) > 0]
Take action here like:
Show Custom Dialog[Generate::Barcode]
Halt Script
End If

What your script does when an ERROR is encountered really just depends on what you want the script to do. In the above code, the script displays the error to the user via a Show Custom Dialog script step and then Halts the script.

Writing errors to the database via Set Field is very important when using Set Variable script steps to call the plug-in. If an error occurs when using Set Variable, and you do not write the error to the database, the error message will be lost as soon as the script finishes.

###Script Steps

Consider the following script step: CNSBC Generate [ Select; Target: Generate::Barcode ; Type:QR Code ]

The above script step will generate a barcode. Since the Target parameter was used, if it was successful, the plug-in will return the barcode image to the “Generate::Barcode” container field. However, if an error occurs, you can determine this by calling FileMaker’s Get ( LastError ) function, and then get the actual error by calling FileMaker’s Get ( LastExternalErrorDetail ) function. With this in mind, error checking for the plug-in’s script steps could look like:

CNSBC Generate [ Select; Target: Generate::Barcode ; Type:QR Code ]
If[ Get ( LastError ) ]
Take action here like:
Set Field [ Generate::Barcode ; Get ( LastExternalErrorDetail ) ]
Show Custom Dialog [ Generate::Barcode ]
Halt Script
End If

##Curly Brackets

When working with the plug-in’s functions, you are working in FileMaker’s calculation engine, so you must format the functions correctly for that environment. In FileMaker’s calculation engine, curly brackets indicate that a parameter or parameters are optional. Take the CNSBC_ConfigureProfile function for example:

CNSBC_ConfigureProfile{( ProfileName )}

This function can be called without any parameters because the parameter section is surrounded by curly brackets indicating that is it optional. Using the function in this manner looks like:

CNSBC_ConfigureProfile

The above code would open the Profile Configuration Dialog and allow you to select any Profile for editing from a list. However, if you would like to only allow editing of a specific Profile, you can specify the name of that Profile in the optional “ProfileName” parameter:

CNSBC_ConfigureProfile( “Scan Widget” )

As shown above, make sure you remove the curly brackets or FileMaker will give you an error.

In more complex functions, there may be multiple optional parameters. Note that if there are optional parameters before one that you need to use, you must include any parameters before it. Consider the CNSBC_ScanWindow function:

CNSBC_ScanWindow( Action {; ProfileName {; Left {; Top {; WindowTitle }}}} )

If you want to specify the “WindowTitle” parameter, you must also specify the three optional parameters before it. Following is an incorrect example and a correct example:

INCORRECT:

CNSBC_ScanWindow( “Show”; “Please scan a barcode” )

CORRECT:

CNSBC_ScanWindow( “Show”; “Scan Widget”; “-1”; “-1”; “Please scan a barcode” )

FileMaker Version Considerations

When plug-ins were first introduced, the only place you really wanted to use a plug-in function was the Set Field script step. However, since FileMaker 4, many new advancements have taken place. Though the Set Field script step is still a very common place to use plug-in functions, there are now many places that can logically be used. For a list of a few of these places, see the next section titled “Places to use CNS Barcode Functions”.

It is important to keep in mind what versions of FileMaker will be in use when using CNS Barcode and other plug-ins. For example, creating a variable using the Set Variable script step can be very convenient, however, that functionality only exists in FileMaker 8 and greater. If you or your users use FileMaker 7, then your script calls would fall on deaf ears if you used Set Variable script step. In addition, when using functions in a variable you will be less likely to see the results returned from the plug-in (such as error messages), because a variable cannot but put on a layout like a field.

Places to use CNS Barcode Functions

You can use CNS Barcode functions in any calculation engine dialog in FileMaker. Keep in mind that just because you can do something does not mean it is actually useful.

There are several places that fit very well depending on the situation:

  • Calculation field
  • Auto-Enter Calculated value
  • Validation by calculation
  • Set Field Script/Button step
  • Insert Calculated Result Script/Button step
  • Show Custom Dialog
  • Set Variable Script/Button Step
  • Custom Functions
  • and more…