JOS Report Format Commands

JOS Report format files use the basic format language syntax, Procedures, and format() statement. However, there are additional format commands that designed for reports; to help format your printed or displayed output.

Learning SmartCAM includes a tutorial topic that covers all the steps required to create a custom format file. See the Creating a Custom JOS Report Format File topic.

JOS Report Procedures

Procedures are groups of formatting language statements that are associated with a single task; for example, the init{} procedure is called once, at the start of a report, and is used to initialize specific settings for the report.

JOS Report Procedures are covered in the Procedure Types topic.

Setting Print Options

Print options, for SmartCAM JOS reports, are tracked in the [JosReport] section of the application.ini file. Defaults can be established using Utility - Options - JOS Report Options and editing the properties. Additionally, the print options can be set within the init procedure of your report format file.

Example:

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

This procedure sets the output to use a page width of 256 characters, turns off pagination (form feeds between pages) and the final form feed at the end of the report. It also enabled HTML encoding (used for HTML-based pages).

The following properties can be set in your format file:

Property	What it does
`OutputFile`	Specifies the filename for the report file, when you print to a file. This setting is controlled by an input field in the JOS Report dialog box and does not need to be set manually.
`OutputDevice`	`0` sets the report output to your printer, `1` outputs the report to a file. this setting is controlled by a selection on the JOS Report window. It does not need to be set manually.
`PageWidth`	Sets the maximum width, in characters, of a printed line.
`PageLength`	Sets the maximum length of a page, by the number of lines that can be printed.
`UseFormFeed`	Force a form feed at the end of each page of the report. If the printer uses a form feed, set the value to `1`. If no form feed is needed, set the value to `0`. In most cases, set this to 1.
`UseFinalFF`	Forces a form feed after printing the last page of a report. If the printer requires a final form feed, set the value to `1`. If no form feed is required, set the value to `0`. In most cases, set this to 1.

Miscellaneous Commands for Report Formats

In addition to the general constructs, procedures, and format statements already identified, the following commands can also be used in report procedures.

Command	What it does
`OutputFile`	Specifies the filename for the report file, when you print to a file. This setting is controlled by an input field in the JOS Report dialog box and does not need to be set manually.
`map()`	Maps an integer value to a string value. By default, the corresponding string values are paired with the scalar values.
`disable_pagination()`	Disables report pagination. When pagination is disabled, the page-based `HEADER` and `FOOTER` procedures are only called once each; header at the start of the report and footer at the end.
`enable_pagination()`	Enables report pagination. When the report outputs the user defined page length (number of lines per page), a new "page" is output. When pagination is enabled, the page-based `HEADER` and `FOOTER` procedures are called at the start and end of each page.
`page_length(#)`	Set the number of lines to output per page.
`page_width(#)`	Set the number of characters to output per line. If the output line exceeds the number of characters defined for the page width, the line is truncated at the point it exceeds the page width and the remainder of the line is output as the next line.
`disable_form_feed()`	Disables output of page-based form feed character (`^L`).
`enable_form_feed()`	Enabled output of form feed character (`^L`). When pagination is enabled and the number of lines per page is reached a new pages is generated. When form feed is enabled, a printer form feed character is output (to force a printer form feed).
`disable_final_form_feed()`	Disables the output of a form feed character (`^L`) at the end of the report.
`enable_final_form_feed()`	Enables output of final form feed character (`^L`) at the end of the report.
`day()`	Inserts the current day of the month as an integer.
`month()`	Inserts the current month as an integer value.
`year()`	Inserts the current year as an integer value.
`hour()`	Inserts the number of hours since midnight (24-hour time).
`minute()`	Insert the number of minutes past the hour.
`second()`	Insert the number of seconds past the minute.
`newpage()`	Forces a form feed.
`page()`	Inserts the current page number.
`shpfile()`	Returns the path/filename to the current process model file.
`jobfile()`	Returns the path/filename to the current JOF file.
`mclfile()`	If the report is being called from a SmartCAM macro, returns the path/filename of the currently running macro.
`smffile()`	Returns the path/filename to the current machine file.
`cgtfile()`	Returns the path/filename to the current code generator template file.
`codfile()`	Returns the path/filename to the current code output file.
`rptfile()`	Returns the path/filename to the report file being generated.
`get_name()`	Returns the filename.ext from a path/filename string. Example: `format("Process Model file: %s\n", get_name(shpfile()));`
`call(procedure)`	Calls a procedure from within another procedure. The called procedure must be defined before the call statement. When the procedure is finished, returns to the next line in the format file.
`call_if_report_image(procedure)`	Used to embed screen captures in the output report file. The report format generator knows which JOS context is active (Job Info, Steps, or Tooling) and if the JOS Reports dialog has a selected named view to be captured, this function will call the named procedure. The called procedure is where the bitmap is included in the report file.
`report_image_get(forceWhiteBackGrnd, Width, Height [, showTools, blackWireframe, lineThicknessMultiplier])`	Function that generates the screen capture bitmap and returns the path/filename of the created image file. The image file will be in .PNG format. This function knows what the current JOS Context is (Job Info, Steps, or Tooling) and uses the appropriate named view for the screen capture. The captured bitmap is saved in the same directory as the output report file. The bitmap is named the same as the generated output file with an additional `_n` added to the end of the filename. Where "`"`" is a number that is the index in to the list of named views. The `forceWhiteBackGrnd` is either `0` or `1`. When 0, the captured bitmap uses the current SmartCAM background color. When set to 1, the background is forced to White. A White background is usually preferred when printing the generated report. The `Width` and `Height` parameters are used to specify the size (in pixels) of the generated bitmap screen capture. Example: `report_image_get(1, 800, 600)` Captures a bitmap with background forced to White and bitmap size of 800x600 pixels. See the default HTML report files for an example of how the call_if_report_image() and report_image_get() functions are used in concert to add bitmaps to the generated reports. A simple example of this is: `procedure jobrpt_image { format("<img class=\"report\" src=\"%s\" height=\"600\" width=\"800\"/>\n", get_name(report_image_get(1, 800, 600))); } procedure section_5010000 { // add bitmap, if user opted for one call_if_report_image(jobrpt_image); }` The command has three optional parameters, based on equivalent functionality in the `File - Print - Graphics` function. If you do not want to use these features, you do not need to include their parameters as arguments when calling the function. However, if you want to use any of the three additional features, you must use all three arguments. The optional arguments are the three at the end, wrapped by [] brackets. Do not include the braces. The optional `showTools` argument includes the tool graphics in the captured bitmap. The values for this parameter are: 0 = OFF (the default) 1 = Nibble 2 = Flat tools 3 = 3D tools The optional `blackWireframe` argument will force colored wireframe to black. This is useful when you have light colored layer/steps and are sending the final report to a black and white printer. Values are `0` = Off (Default) and `1` = On. `lineThicknessMultiplier` adjusts the thickness of wireframe geometry. This field takes integer numbers. The default value is `1`, which means draw the same thickness as the graphics view. Setting the value to 2 doubles the thickness, setting it to 3 triples the thickness and so forth.
`image_get(viewName, forceWhiteBackGrnd, Width, Height [, showTools, blackWireframe, lineThicknessMultiplier])`	Function that generates a screen capture bitmap and returns the path/filename of the created image file. The image file will be in .PNG format. Similar in function to `report_image_get()`, this function allows the user to pass in the Named View to capture, regardless of the graphical user interface Image file setting. The captured bitmap is saved in the same directory as the output report file. The bitmap is named the same as the generated output file with an additional `_n` added to the end of the filename. Where "n" is a number that is the index in to the list of named views. The `viewName` is the name of the view to capture. The view name must be quoted. If the named view does not exist in the current process model, this function will return an error string instead of the path/filename of the saved bitmap. The error string is "error with view specified.png." The `forceWhiteBackGrnd` is either `0` or `1`. When 0, the captured bitmap uses the current SmartCAM background color. When set to 1, the background is forced to White. A White background is usually preferred when printing the generated report. The `Width` and `Height` parameters are used to specify the size (in pixels) of the generated bitmap screen capture. Example, using `image_get()` in an HTML image tag: `format("<img src=\"%s\" />\n", get_name(image_get("top", 1, 800, 600));` Captures a bitmap, of the `TOP` view, with background forced to White and bitmap size of 800x600 pixels. Output as the src parameter to HTML's image tag. The command has three optional parameters, based on equivalent functionality in the `File - Print - Graphics` function. If you do not want to use these features, you do not need to include their parameters as arguments when calling the function. However, if you want to use any of the three additional features, you must use all three arguments. The optional arguments are the three at the end, wrapped by [] brackets. Do not include the braces. The optional `showTools` argument includes the tool graphics in the captured bitmap. The values for this parameter are: 0 = OFF (the default) 1 = Nibble 2 = Flat tools 3 = 3D tools The optional `blackWireframe` argument will force colored wireframe to black. This is useful when you have light colored layer/steps and are sending the final report to a black and white printer. Values are `0` = Off (Default) and `1` = On. The optional `lineThicknessMultiplier` adjusts the thickness of wireframe geometry. This field takes integer numbers. The default value is 1, which means draw the same thickness as the graphics view. Setting the value to 2 doubles the thickness, setting it to 3 triples the thickness and so forth.
`tool_image_get(Width, Height, Zoom Level)`	Generates an image file for the current tool, in the active JOS Context. It resembles the tool graphic preview in the JOS Planner, however the tool profile will always be black and the background white. The function creates the bitmap file (in .PNG format) and saves it in the same folder as the generated report and returns the path/filename of the created image file. The captured bitmap is named the same as the generated report with an additional `_T[x_]n` appended to the end of the filename. Where `x` is the turret number (for turning) and `n` is the tool number. The `Width` and `Height` parameters are used to specify the size (in pixels) of the generated bitmaps screen capture. The `Zoom Level` primarily has an effect when a Custom Tool Graphics is used. It is set to either `0` or `1`. When no CTG is being used, with the current tool, this value does not have an effect. When a CTG file is assigned to the current tool, setting the value to 0 causes the image to zoom in on the tool. When set to 1 the image is scaled to fit both the tool and CTG holder in the image.
`html_encode()`	Usually called in the `init` procedure, when included this function causes all JOS strings to be run through a HTML encoder. Some text characters have special meaning in HTML and so need to be converted to HTML equivalents. This function does that. The characters converted are: Line Feed converted to <BR /> < converted to < > converted to > & converted to & " converted to " ' converted to '
`custom_encode(path/filename.ext)`	Allows custom character substitution from string data returned from JOS tags. This function is usually called in the `init` procedure. The parameter for this function is the path and filename of a custom encoding file. This is an ASCII text file which contains the string characters to search for and the character to replace with. The function parameter should include the path and filename. If it just includes the filename, SmartCAM will search for the file by first checking any paths associated with the environment variables: `SYSTEMROOT`, `SMARTCAM`, or `HOME`. It then checks the path where the current running SmartCAM application resides, then the User Configuration files directory (`SCUSER`), and the SmartCAM `SHARED` directory. If the file is not located in any of the above paths, it finally checks where the calling format file resides. The format file is a simple ASCII text file. Each search and replace combination reside on separate lines. Each line begins with the search string - the string to find. Followed by either a `[TAB]` or `\|` (bar) character, then the replace string. Single characters can be represented by the hexadecimal value of the ASCII character. Hexadecimal characters must start with `0x0`. For example the decimal value for the space character is 32. The Hexadecimal value is 20, so you would enter 0x020. Usually single characters would be represented by the character itself; however there are some non-display characters or extended ASCII characters where you would need to use the hexadecimal value. There is a special search string: `EOL`. If "EOL" (capital letters entered exactly as shown) is used this translates into "End of Line." When used SmartCAM will search for any normal combination of end of line characters; DOS, Windows, UNIX versions and match on them. If the first character of the line is '`#`', the line is ignored.