Creating a Custom JOS Report Format File

Supported Applications: All
Time Required: 1.5 - 2 hours

This tutorial will explain the process for creating a custom JOS Report. The generated report will not be complex, but will cover the fundamentals of report format file creation and customization. In order that this report format file work for all applications, it will only output information that is common between all the SmartCAM NC applications.

Concepts Explored

General Information About JOS Report

JOS Report is a tool for extracting information from your current process model and formatting the extracted data into an ASCII text file or sending the generated ASCII data to your selected printer. Depending upon the format file selected, JOS Report can either generate formatted data that can be sent directly to your printer or can be used to create higher-level source files; such as the HTML and CSV format files.

SmartCAM can send the information to a selected printer or to a text file. The information is exactly the same, the only option is where you want the ASCII text data sent.

If using JOS Report to create a higher-level source file; such as HTML or CSV, you should output the report to a file. Then enable the "Open JOS Report" option. When you generate the report, SmartCAM will write the file to the path and filename you provided, then open the file in the appropriate application for viewing and printing the information. SmartCAM itself has no information about what the appropriate application is, it relies on the Windows File Association feature to open the correct application. See your Windows Help for information on how to work with Windows File Association.

Helpful Information

Several areas to review, for assist in understanding how Report format files work and to get the information you will need to write the format files include: Using SmartCAM - Data Tags and Section Numbers and this table of contents item's sub-items. Review Using SmartCAM - Reports and it's child documents. And, as a general overview, see the Using SmartCAM - Customizing Format Files topic and child documents.

How JOS Report Works

JOS Report sends formatted ASCII text strings to a selected output device or file. When JOS Report is run, the selected Report Format file is read. If there are any included files, they are read in to memory as they are encountered. Once the entire format file and any include files are imported the reporting function starts to run.

JOS Report then calls a number of procedures (like subroutines) in a specific sequence. Some procedures exist to assist in the correct formatting of your report file. Other procedures are based on the JOS Operations Setup Section Numbers, which ones are called depends upon the JOS data in your current process model. Finally there are procedures, that you can create for your own custom purposes, which are not automatically called by JOS Reports, but rather called by direct reference by commands in your format file.

All procedures in the format file are optional. Use them if you require them to assist in the formatting of your final report.

The following documents the calling order and normal purpose of the various procedures.

INIT Procedure

If the format file, or any of the include files, has a init procedure defined. It is the first procedure run. The init procedure is only run once and can only be defined once. It is normally used to define the page size and pagination parameters and to invoke built-in text conversion (text substitution) functions. The following is the init procedure for the report format file that outputs HTML web reports.

procedure init
{
    page_width(256);
    disable_pagination();
    disable_form_feed();
    html_encode();
}

The first three called functions set the line length for the output lines, turn off pagination, and turn off the outputting of form feed characters. These functions may override the default page formatting settings from your application INI file.

Since HTML source code is a single, uninterrupted data file, this init procedure disables pagination. It sets the maximum line length for each line to 256 characters. And it turns on a special purpose function that modifies JOS data so that it outputs correctly for the HTML file format.

Documentation about the above referenced functions, as well as many other built-in functions, can be found in the Using SmartCAM - Reports - JOS Report Format Commands topic.

HEADER Procedure

The next procedure to be called is header. If it exists, the header procedure is called at the start of each report output. If pagination is enabled, it is also called at the start of each new page. The header procedure is normally used to add a header to the start of each report and/or to the top of each new report page.

Report Content

The Report Content input on the JOS Report dialog has three options. These control the type of information output by the JOS Report function. The three options are: Job Info, Tooling, and Steps. After calling the header procedure (above), JOS Report now calls the procedures to generate the content for each of the selected content types.

The related procedures are called in the order that they are displayed on the JOS Report dialog. First the Job Info data is collected and output, then the Tooling, and finally the Step data.

If the related JOS Report - Report Content check box is not selected, the procedures related to that selection are not called.

JOB_HEADER Procedure

If the Job Info report type is selected, the job_header procedure is called. This function is generally used to add a header to the report that is specific to the Job Info data. For example, for the HTML report format files, the job_header procedure is used to establish an HTML table with the correct number of columns for the resulting report and create a report section banner.

Job Info Section Procedure

The section procedure for the Job Info report is called. Section procedures, based on the Job Operations Setup Section Numbers, are where the actual details of the report are generated. Section procedures will be examined in greater detail later in this tutorial.

JOB_FOOTER Procedure

The job_footer procedure is called when the Job Info report is complete, after the last of the Job Info related section procedures are called. This function is normally used to add a footer to the Job Info content in the report. For example, for the HTML report format files, the job_footer procedure is used to finish up and close the HTML table created in the job_header procedure.

TOOL_HEADER Procedure

This procedure is called just prior to calling the section procedures to output data for the process model's tooling information.

Tooling Section Procedures

The section procedures related to the tooling information, in your current process model, are called. Section procedures will be examined in greater detail later in this tutorial.

TOOL_FOOTER Procedure

This procedure is called just after the last of the Tooling related section procedures are called.

STEP_HEADER Procedure

This procedure is called just prior to calling the section procedures to output data for the process model's step information.

Step Section Procedures

The section procedures related to the step information, in your current process model, are called. Section procedures will be examined in greater detail later in this tutorial.

STEP_FOOTER Procedure

This procedure is called just after the last of the Step related section procedures are called.

FOOTER Procedure

The footer procedure is called at the end of the entire report. If pagination is enabled, it is also called at the end of each page, just before the form feed. It is normally used to add footer text at the end of the report and end of each page.

Section Procedures

Section procedures are used to format the report data. They are based on the Job Operations Setup Section Numbers, which are used to organize and classify JOS data. See the Customizing format files - Job Operations Setup section numbers topic for a full list of the section numbers and their organization.

Section procedures are where most of the report content is generated. This is where the actual data from the JOS data tags is commonly output. A table of the current JOS Data Tags is available under the Using SmartCAM - Data Tags and Section Numbers - Job Operations Setup Data Tags topic.

The format for the section procedure is:

procedure section_section number
{
    format statements that output the required data tags
}

When JOS Report is run, SmartCAM finds the Job Operation Setup Section Number for the given piece of data and then searches for a matching section procedure. SmartCAM starts with the most specific section number and works up the tree hierarchy until it finds a matching procedure. If no matching procedure is located, then nothing is output.

The following stripped down example of section procedures for Milling may help explain this process:

procedure section_1030000
{
    format statements for the Operations section number
}

procedure section_1030200
{
    format statements for Hole Operations
}

procedure section_1030203
{
    format statements for Peck Drilling Operations
}

The above three section procedures are for milling Operations. These would be called when the JOS Report options include the Step report type.

For purposes of this example, JOS Report is run. The first Step encountered is a Rough Milling operation; which has the section number 1030101. SmartCAM first looks for a section procedure with the section number 1030101. One does not exist in this format file, so it backs up the hierarchy tree by one node. It now looks for procedures using section number 1030100 - Milling Operations. Again, it is not found. So, it backs up the tree one more node, looking for 1030000 - Operations. It does find this procedure and then calls it to output the data for this step.

The next Step is a peck drilling hole operation, which has the section number 1030203. In this case, there is a section procedure for this operation, so it uses it. The format file still includes the section procedures for number 1030200, which is for Hole Operations, and the generic 1030000 which is for all operations. But, since there was a section procedure specifically for the Peck Drilling operation, it was used.

The next Step is a Spot Drilling operation. So, JOS Report checks for a section procedure for Spot Drilling - 1030201. One does not exist. So, it backs up the tree one node, looking for Hole Operations - 1030200. This is found, and is used to output data for the Spot Drilling operation.

As you can see, SmartCAM attempts to find the most specific section procedure, based on section numbers. And then walks up the tree, backwards, until it find a procedure that matches the section number hierarchy.

Note: When designing your reports, try to use the highest level section number that you can. Using Milling as an example, when you design your report you find that for Milling Operations, you want the same data output for all the Operation types, except Face Milling. Rather than creating a different section procedure for each of the Milling Operations, you would only design two. One specifically for the Surface Milling operation, which is section number 1030104. And a second, more generic procedure, for all Milling Operations, which is section number 1030100. This reduces the work needed to create and maintain the report.

Defined Procedures

A defined procedure is a special purpose procedure that you create. It is not called automatically by SmartCAM, rather it is manually called using the call(procedure name) function.

Defined procedures are used to automate repetitive tasks, for example in the HTML report format files defined procedures are used extensively to handle the tasks of building and maintaining the HTML code for complex nested tables. Another common use is to convert some numeric index JOS data tags into their string equivalents. Example:

procedure feed_mode
{
    format ("%s",
        map(unfdmode, [ 1 = "IPR", 2 = "IPM", 11 = "mm/r", 12 = "mm/min"]));
}

// Top level STEP section procedure
procedure section_1030000
{
    format("Feed mode is: ");
    call(feed_mode);
    format("\n");
}

In the above example, a defined procedure is created called feed_mode. It converts the unfdmode JOS data tag from its index value into the string equivalent - using the map() function. Then outputs the string value using the format() function.

The feed_mode procedure is called in the section procedure "section_1030000". The call(feed_mode); function is used to call this defined procedure. When a called procedure is complete, SmartCAM returns to the next line after the "call()" statement and continues running.

Structure of a JOS Report Format File

The JOS Report format (.FMT) and include (.INC) files are ASCII text files. They can be created in any text editor, such as Windows Notepad.

Include Files

By convention, the main report format file has a .FMT extension. This is the file that you select in the JOS Report's Format file: input. The main report format file usually does not contain any of the actual report formatting functions; instead it embeds a number of "Include" files that contain the actual report formatting code. The files included into the main report format file have .INC as their extension. SmartCAMcnc recommends not using .FMT as the file extension for include files, as it can make it confusing to know which format file is the main format file and which are included files.

The main report format file generally incorporates at least three different include files. One for each type of report: Job Info, Step, and Tool. This organization is not required, you could create all the reporting functions in a single .FMT file. The convention of using include files for each of the report types was adopted to make editing and management of the report format files easier.

For example: when you are looking at the include file for the Job Information report type, you know that the declared variables and functions are just for the Job Information report. This reduces the number of procedures to review and simplifies debugging and later enhancements. This tutorial will use the included files convention.

Comments

The JOS Report format comment string is two forward slashes: //. When the comment marker is encountered, SmartCAM stops reading the current line. So, anything after the comment marker is ignored.

// Report Variables
extern integer tl_num; // Tool number

In the above example, the entire line "Report Variables" is considered a comment and ignored. In the second line, the external integer declaration is accepted, because it comes before the comment marker. However, the comment "Tool number" is ignored.

Statement Terminator

All format language statements end with a semicolon. Language statements are the "Commands" used in the format language. This includes the format(), map(), page_length(), and other language commands.

There are only two types of statements that do not end with semicolons. The first is a comment statement. The second is a procedure declaration. However, all the statements inside of a procedure declaration must end with semicolons. Example:

procedure header
{
    format("------------ Header ------------");
}

Notice the "procedure header" and procedure brackets ({}) do not end with semicolons. However, the "format()" statement does.

Variables

The formatting language does not have general purpose variables, the only variables in the format file are place holders for JOS data tag contents. Before a JOS Data tag can be output, it must be declared - so that the system knows what type of data is being output.

A table of the current JOS Data Tags is available under the Using SmartCAM - Data Tags and Section Numbers - Job Operations Setup Data Tags topic.

To output the contents of a JOS Data Tag, it must be first declared as a variable. This is done using the following syntax:

extern string jof_file;
extern integer tl_num;
extern float standoff, corner_amps;

In the above example, the string JOS data tag jof_file is declared and can be used in the report. The integer tag tl_num, and the floating point (decimal) data tags; standoff and corner_amps, are declared. Each variable declaration must end with a semi-colon. You can define more than one variable, of a given type, by separating the tag names with commas.

Tags must be declared before they are first used and they can only be declared once.

The formatting language variables exist only to output the current content of the selected JOS data tags; it is not possible to modify the content of a variable. Nor can you define a variable that does not already exist in the JOS data tags.

INI Settings for Reports

You can establish some default settings for your report in the [JosReport] section of your application.ini file. These settings include the default output filename for the report, whether to send the report to a file or to the current default printer, the page width in characters, page length in lines, whether to use form feed characters (pagination), and finally whether to send a form feed at the end of the printed report (needed by some older printers).

See the Using SmartCAM - Reports topic and subtopics, as well as the Automation/Customization - Customizing SmartCAM - SmartCAM INI Overview topic and subtopics for more information.

Creating a Simple Custom Report

This section of this tutorial topic includes instructions on how to create a new format file, using the information provided above. You will also need to review the SmartCAM Customization Guide - Customizing format files topics.

The completed format and include files are in the Data Files archive, that you can download from the main Learning SmartCAM page. You can use these files to compare your work against the working final product. You can use these format files to generate Job Info, Step, and Tool reports simply by using the Report_Tutorial.fmt file as your input for the Format File: field on JOS Reports. You do not need to move the files, simply use the File Select button and browse to the format file in the directly where you extracted the Learning SmartCAM sample data archive.

Format Files: Report_Tutorial.fmt, Report_Tutorial_JobInfo.inc, Report_Tutorial_Step.inc, Report_Tutorial_Tool.inc

Step One: Decide on the Data to Output

Decide which JOS Data Tags to output for the Job Info, Step, and Tool reports. Review the Using SmartCAM - Data Tags and Section Numbers - Job Operations Setup Data Tags to find what data tags are available and whether they are string, integer, or decimal (float) data types.

For this tutorial, only a few fields will be output, to both simplify the tutorial and to try to make sure the report works for all SmartCAM NC applications. Normally, a different set of report format files would be required for each of the four machining types: milling, turning, fabrication, and wire; since much of the data that one would like to output is application specific.

The JOS Data Tags used in this tutorial report are:

Step Two: Decide on Format File Structure

Everything can be written into a single Format file. However, for longer, more complex format files, this can be confusing. This tutorial will use four files. A main format file, called Report_Tutorial.fmt, which is the file selected in the Format File: input on the JOS Report dialog. And three include files, one for each of the three report types.

Step Three: Create the main Format File

Using a text editor, such as Notepad, create a new text file. Name the file "Report_Tutorial.FMT".

Add File Comments

It is always a good idea to add some comments at the top of the file that explains what the file is and what it is for. Add the following comments to your format file.

// Report_Tutorial.fmt
// Simple JOS Report format file used as an example in Learning SmartCAM
// Outputs limited data to a simple ASCII text file.

Add Report Header and Footer Procedures

This report will have a header and footer block at the start of each report and each page in the report. Use the header and footer procedures for this activity.

// Main Report Header section
procedure header
{
    format("*********************************************************\n");
    format("        Learning SmartCAM Report Format Tutorial\n");
    format("*********************************************************\n");
    format("\n");
}

// Main Report Footer section
procedure footer
{
    format("                              -- %d --\n", page());
}

These header and footer procedures are using two built-in report format functions: format() and page().

The format() function is used to output formatted strings to the final report. The format() function has the ability to format and embed string, integer, and decimal data into the output string. Special characters, such as %s for strings and %d for integers, mark where the data should be inserted. The data to be embedded is passed to the format() function in the parameter list.

A special character string to remember is "\n". When the format function is run, this string is replaced with a newline character; causing a new line to be added to the output string.

In the footer procedure, the format() string includes a "%d" character. When the format() function is run, the %d is replaced with an integer. The integer is passed to the format() function as the second parameter. In this example, it uses the built-in function page(). The page() function returns the current page number of the output report as an integer.

See the Format Statement topic for more detailed information on the format() function.

Include Report Specific Format Files

The section procedures for this report are broken up into three files; one for each report type. The format files, or include files, for these report types needed to be added to the main report format file.

// Include Report Type format files

// Job Info
#include "Report_Tutorial_JobInfo.inc"

// Step
#include "Report_Tutorial_Step.inc"

// Tool
#include "Report_Tutorial_Tool.inc"

The three report specific format files will be included in the main Report_Tutorial.fmt format file when it is read. These three files need to reside in the same directory folder as the main report format file.

Step Four: Create the Job Info Format Include File

Using a text editor, such as Notepad, create a new text file. Name the file "Report_Tutorial_JobInfo.inc".

The variables and procedures defined in this file will be specific to the Job Info report type.

Declare Variables

The Job Info report type will output several JOS Data Tags. These data tags need to be declared before they can be used.

// Report_Tutorial_JobInfo.inc
// JOS Report included format file for Learning SmartCAM tutorial

// Variables for the Job Info report
extern string created, creator, job_note, jof_file;
extern string nc_date, nc_file, nc_runtime;
extern integer nc_size;

This code fragment declares seven string variables and one integer variable. The variable names must match the name of the JOS Data Tags and the variable's data type (string, integer, float) must match the actual JOS tag data type.

Add Job Info Report Header and Footer

The main Report_Tutorial.fmt format file included procedure declarations for the report header and footer. The following header and footer declarations are for the Job Info report information only. The job_header procedure is called just prior to calling the Job Info section procedure. The job_footer procedure is called just after the Job Info report information is output.

// Job Info Report Type Header
procedure job_header
{
    format(" **** Job Info Section:\n\n");
}

// Job Info Report Type Footer
procedure job_footer
{
    format(" **** End of Job Info Section");
    newpage();
}

The newpage() function, in the job_footer procedure is used to output a formfeed character. This function, in the report type footer, causes each report type to be printed starting at the top of a new page.

If pagination is disabled, either in the application INI settings or in an init() procedure, then the newpage() function does nothing.

Add Section Procedure

The section procedure is used to output the actual Job Info report data. The Job Operations Setup Section Number used for this section procedure is 5010000. Refer to the JOS Section Numbers topic for more information about section numbers.

// section procedure for Job Info report type
procedure section_5010000
{
    format("Created on: %s\n", created);
    format("Created by: %s\n", creator);
    format("JOF File:   %s\n", jof_file);
    format("Job Notes:\n%s\n\n", job_note);
    format("NC File:    %s\n", nc_file);
    format("Date Coded: %s\n", nc_date);
    format("Runtime:    %s\n", nc_runtime);
    format("NC Size:    %d (bytes)\n", nc_size);
}

Step Five: Create the Step Format Include File

Using a text editor, create a new text file. Name the file "Report_Tutorial_Step.inc".

The variables and procedures defined in this file will be specific to the Step report type.

Declare Variables

The Step report type will output several JOS Data Tags. These data tags need to be declared before they can be used.

// Report_Tutorial_Step.inc
// JOS Report included format file for Learning SmartCAM tutorial

// Variables for the Step report
extern string op_desc, st_notes;
extern integer step_num;

This code fragment declares two string variables and one integer variable. The variable names must match the name of the JOS Data Tag and the variable data type (string, integer, float) must match the actual JOS tag data type.

Add Step Report Header and Footer

The main Report_Tutorial.fmt format file included procedure declarations for the report header and footer. The following header and footer declarations are for the Step report information only.

// Step Report Type Header
procedure step_header
{
    format(" **** Step Section:\n\n");
}

// Step Report Type Footer
procedure step_footer
{
    format(" **** End of Step Section");
    newpage();
}

Add Section Procedure

The section procedure is used to output the actual Step report data. The Job Operations Setup Section Number used for this section procedure is 1030000; this is the top-level Section Number for all Operations. Refer to the JOS Section Numbers topic for more information about section numbers.

// section procedure for Step report type
procedure section_1030000
{
    format("Step Num.:  %d\n", step_num);
    format("Op. Desc.:  %s\n", op_desc);
    format("Step Notes:\n%s\n\n", st_notes);
}

Step Six: Create the Tool Format Include File

Using a text editor, create a new text file. Name the file "Report_Tutorial_Tool.inc".

The variables and procedures defined in this file will be specific to the Tool report type.

Declare Variables

The Tool report type will output several JOS Data Tags. These data tags need to be declared before they can be used.

// Report_Tutorial_Tool.inc
// JOS Report included format file for Learning SmartCAM tutorial

// Variables for the Tool report
extern string tl_desc, tm_notes;
extern integer tl_num;
extern float tl_dia;

This code fragment declares two string, one integer, and one decimal variables. The variable names must match the name of the JOS Data Tag and the variable data type (string, integer, float) must match the actual JOS tag data type.

Add Step Report Header and Footer

The main Report_Tutorial.fmt format file included procedure declarations for the report header and footer. The following header and footer declarations are for the Tool report information only.

// Tool Report Type Header
procedure tool_header
{
    format(" **** Tool Section:\n\n");
}

// Tool Report Type Footer
procedure tool_footer
{
    format(" **** End of Tool Section");
    newpage();
}

Add Section Procedure

The section procedure is used to output the actual Tool report data. The Job Operations Setup Section Number used for this section procedure is 2000000; this is the top-level Section Number for all Tooling. Refer to the JOS Section Numbers topic for more information about section numbers.

// section procedure for Tool report type
procedure section_2000000
{
    format("Tool Num.:  %d\n", tl_num);
    format("Tool Dia:   %f\n", tl_dia);
    format("Tool Desc.: %s\n", tl_desc);
    format("Tool Notes:\n%s\n\n", tm_notes);
}

Step Seven: Running the Report

Now that the format files are complete, the next step is to test them by running them.

Start your SmartCAM application and load a process model file. The model should have defined steps and tools; so that those report types can be verified.

Use File - Print - JOS Report to open the JOS Report dialog. Click on the File Select button and then browse to and open the Report_Tutorial.fmt format file.

Make sure all three report types are enabled.

Set the Printer/File option to File and then type in a destination path and filename for the generated report file. You could set the option to Printer, but it is often easier to debug text files if you can open the file in a text editor, rather than looking at it printed on a page.

Click on the Accept button to generate the report.

Storing Custom Reports

The default report format files are stored in the REPORTS\ folder of the common unversioned SmartCAM file tree. Example:

X:\ProgramData\SmartCAM\Common\Reports\

When a new version of SmartCAM is installed, the report files shipped with SmartCAM may be overwritten. So, it is recommended that you do not modify the SmartCAM installed report files. Instead, you should make a copy of the files, with a new filename, and modify the copied version. Or, create and maintain your own company customized folders; similar to the \ProgramData\SmartCAM\Common folder.

Example: X:\ProgramData\SmartCAM\CustomReports\

Debugging Format Files

The following describes a couple of methods of resolving problems with JOS Reports.

2696: Report Generation failed to open specified file or printer

This error is triggered by a number of factors.

Errors in Format Files
If there are errors in the format files, the report would not be able to be generated and would trigger this error. Use Utility - Diagnostics to display the Diagnostics Window. Review the text in the window looking for report format errors.

"12016: Attempt to redeclare the variable <name>
A common format file error is attempting to declare a variable more than once. If this happens, the Diagnostics Windows will include the above referenced error message. Check your format files for the declaration of name and make sure it is only declared once. It must be declared before the first time it is used. If using include files and the variable needs to be output from multiple files, then declare the variable in the main format file - not the included files.

12024: Type mismatch in format() statement for argument <format string>
There is a data type mismatch. Either the data was declared as the wrong data type or the format string includes the wrong data type place holder (e.g., %s for string, %d for integer, %f for decimal (float).

Path Error or Permissions
If the output is going to a file, perhaps the provided path is incorrect. If the path is invalid, the report file could not get written and would trigger this error. Or, if the path is correct, however the current Windows login does not have sufficient permissions to read/write/modify files in this path this error would get triggered.

Extra Page Output at End of Report

When sending the JOS Report to a printer, if there is an extra page being output at the end of the print job, the likely cause is the INI setting: UseFinalFF. The UseFinalFF INI setting exists for older printers that required a closing form feed in order to print the last page of the report.

See the [JobReport] section of the The Application.INI File topic for further information.

Done

This exercise is complete.