Script Command Syntax

A description of all the supported scripting commands follows.

An optional item is enclosed in []. An example would be [FROM], which means that the word FROM is optional.

Unless otherwise stated, extra text appearing on a line after details required by the command are ignored. Similarly, lines containing unknown commands are ignored.


ALIGN align_data

align_data is one of the following keywords: LEFT, RIGHT, CENTRE, CENTER. Note that both British and American spellings are acceptable.

Example:

ALIGN RIGHT


BANNER colour_data
NOBANNER

See COLO(U)R for details of what colour_data should be. See also the HIGHLIGHT command. The NOBANNER command (which does not require a parameter) is a shortcut for BANNER WHITE or its equivalents - it resets the banner colour back to white, which is the default (since paper is normally white!).

Examples:

BANNER LIGHT_RED
BANNER #FF0000
BANNER 100%, 0%, 0%


BLANK
BLANK [*]blank_data
BLANK
literal_number_or_expression

If the parameter is supplied, blank_data is treated as the number of blank lines to insert. If no parameter is supplied, one blank is assumed. Note that unlike TAB, if no sign is supplied then * is assumed since the = sign has no meaning here.

Example:

BLANK *2


COLOUR colour_data
COLOR
colour_data

colour_data is either a named colour, an HTML-style hexadecimal colour specification of the form #RRGGBB, or a colour component specification of the form r[%], g[%], b[%]. The named colour is one of BLACK, DARK_RED, DARK_GREEN, BROWN, DARK_BLUE, DARK_PURPLE, DARK_CYAN, DARK_GREY, DARK_GRAY, LIGHT_GREY, LIGHT_GRAY, LIGHT_RED, LIGHT_GREEN, YELLOW, LIGHT_BLUE, LIGHT_PURPLE, LIGHT_CYAN, WHITE, ORANGE. Note that both British and American spellings are acceptable for both the command AND the colour names. The HTML-style specification consists of three hexadecimal pairs of digits in the range 00 to FF (hex). There must be 6 digits as well as the hash symbol. The component specification must include exactly three components separated by commas. The % sign is optional. Each component must be in the range 0 - 100(%). See also the HIGHLIGHT and BANNER commands.

Examples:

COLOUR LIGHT_RED
COLOUR #FF0000
COLOUR 100%, 0%, 0%


ENDPAGE

This command has no parameters.  Forces the scripter to leave sufficient space after the current line to cause a new page to be started, indicated by a dashed line in the editor.

Example:

ENDPAGE


EOL

This command (short for End Of Line) has no parameters.  Causes all pieces of text issued since the last EOL (or the beginning of the script) to be output in the colours and fonts selected. Note that if multiple ALIGN commands have been issued since the last EOL (or script start), only the LATEST issued will be in effect. You MUST use EOL to output text, it will not show otherwise. Note that xxxFIELD and xxxDATE commands are also treated as pieces of text in this way.

Example:

EOL


FIELD field_data
SHORTDATE_FIELD field_data
LONGDATE_FIELD field_data
CUSTOMDATE_FIELD field_data  format_string
TIME_FIELD
field_data
VARIABLE_FIELD field_data variable_data[#format_string]

field_data is a piece of text interpreted in exactly the same way as for a TEXT command (see the TEXT command, and the section Literal Text, Variables & Quotes). The difference is that the resulting piece of text must represent a valid field in the current database row. If it does not, "<ERROR>" is shown. If there is no loop currently in effect, and thus no current database row, then it also shows as "<ERROR>".

SHORTDATE_FIELD and LONGDATE_FIELD work the same as FIELD, but in addition they interpret the text retrieved as a date in your PC's short or long date format. CUSTOMDATE_FIELD additionally requires a format_string. This determines how the date will be displayed in the report.  Please see the custom date format string help topic for details of this. If you just use FIELD to pull out a date field from the database, it will be shown in the database's natural format.

The field name supplied for CUSTOMDATE_FIELD -must- be in speech marks, as must the format string. This is in contrast to the field name as specified for the other FIELD commands, which does not need to be in speech marks. If you fail to put the speech marks, the parser will not understand and the output will be undefined.

TIME_FIELD works the same as FIELD, but in addition it interprets the text retrieved as a time using the format specified in the program preferences.  This will either be 12 hour (the default) or a custom format.  You should only use this script command for fields that hold the meeting time as a text string.

VARIABLE_FIELD assigns the value of the field to an existing variable. Thus the variable value will change with each iteration of the LOOP. However it does mean that you can now use any given field value elsewhere in your report. All variables must be already declared using the REQUIRES command. You can add a hash # after the variable name with a format string to get the parser to fill the variable in a certain way. Here are the possible alternatives:

$VariableName This will save the contents of the variable in it's raw state with no additional formatting.
$VariableName#TIME This will format the variable value as a "Time" field, taking into account program preferences.
$VariableName#TALK_THEME This will format the variable value as a "Talk Theme". You should use this with "Talk Number" fields.
$VariableName#SHORTDATE This will format the variable value as a short date.
$VariableValue#LONGDATE This will format the variable as a long date.
$VariableName#CUSTOMDATE[format_string] This will format the variable using your specified format string. Please see the custom date format string help topic for details of this.
$VariableName#COUNT This will format the variable with the count of characters in the field if it is of string type, or '-1'. Note that for integer field types, if used this will produce the count of characters in the *number*.
$VariableName#TTCOUNT This will format the variable with the count of characters in the field after interpreting it as a talk theme title. Note that since #TALK_THEME is normally used to format a talk number into a talk theme title, #TTCOUNT replaces #COUNT for talk numbers to correctly get the count of characters in the title.

(VARIABLE_FIELD ":reset:" depracated with version 13.0.1 See below)This command can also be used to reset variables to certain values. You have to use specify :reset: as the field name and there are three ways to reset:

VARIABLE_FIELD ":reset:" "$VariableName" This will reset the variable to the default value (or first option) specified in the REQUIRES .... VALUES property.
VARIABLE_FIELD ":reset:" "$VariableName#TEXT[text_data]" This will reset the variable to the specified text value. New line characters can be included by using \r\n within the text.
VARIABLE_FIELD ":reset:" "$VariableName#VARIABLE[$variable_data]" This will reset the variable to the value of another variable.

Examples:

FIELD "Chairman"
SHORTDATE_FIELD "Last Given"
LONGDATE_FIELD "Last Given"
CUSTOMDATE_FIELD "Last Given" "%B %y"
TIME_FIELD "Time"

VARIABLE_FIELD "$RowNumber" "$NumberOfHomeTalks"
VARIABLE_FIELD "Speaker" "$VisitingSpeaker"
VARIABLE_FIELD "Last Given" "$varLastGiven#LONGDATE"

VARIABLE_FIELD ":reset:" "$strTitle"
VARIABLE_FIELD ":reset:" "$strTitle#TEXT[New Title Text]"
VARIABLE_FIELD ":reset:" "$strTitle#VARIABLE[$strDefaultTitle]"

VARIABLE_FIELD ":reset:" depracated with version 13.0.1. The above 3 can now be done like this:

$strTitle = "New Title Text"
$strTitle = $strDefaultTitle
$strTitle = default_value($anotherVariable) See default_value for more details.

Note that $RowNumber here is being used as a field name, but has the dollar sign used for variables; remember that this is a special variable that is automatically filled with the currently-executing row number within the innermost loop. Speaker in the second example is a normal database field.


CONG_MEET_TIME field_data field_data
CONG_MEET_TIME $LocalCong field_data
CONG_MEET_TIME field_data $variable_data
CONG_MEET_TIME $LocalCong $variable_data

This command has two parts. The first part specifies the congregation. You can either specify a field for current row in the LOOP that holds this information, or you can use the predefined variable $LocalCong to use your own local congregation.

The second part specifies the date. Again, you can either specify a field for the current row in the LOOP that holds this information, or you can use a variable. That variable may be any one of the predefined date variables (for example, $Today, $NextYear, $NextTwoYears or $NextQuarter) or it may be a variable you have defined. If you use a variable you have defined, it must contain a valid date formatted thus ‘#yyyy mm dd#’ (the single quotes are not part of the format). You must use the Expression Editor and the format_date() function to format the date correctly.

Once you have specified these two fields (or variables), the program takes the actual values and then works out what the correct meeting time would be for that date at that congregation. If the date is in the past, it will just use the "current" meeting time for that congregation.

Examples:

CONG_MEET_TIME "Congregation" "Talk Date"
CONG_MEET_TIME "$LocalCong" "Talk Date"
CONG_MEET_TIME "$LocalCong" "$NextYear"


FONT font_data[, font data, ...]

font_data is either the name of a typeface that must exist on your PC (for example, "Comic Sans MS"), a style keyword, or a number indicating desired size. The size is quoted in points (1/72nd of an inch), as for programs such as Microsoft Word. Generally, 12 is about normal type size. You can combine as many of these pieces of font data in a FONT command as you like. Any that contradict previous ones will be used in left-to-right order, so those appearing last on the line will be in effect. You must use commas to separate the pieces of data, or they will not be understood. Note that any pieces of data that cannot be understood are ignored, and parsing continues after the next comma. A style keyword is one of the following: BOLD, NOBOLD, ITALIC, NOITALIC, ULINE, NOULINE. Note that in the same way that the font size and face remain in effect until you change them, so do styles - thus, underlining will continue until you explicitly use NOULINE to switch it off.

Example:

FONT Times New Roman, 10, BOLD


HIGHLIGHT colour_data
NOHIGHLIGHT

See COLO(U)R for details of what colour_data should be. See also the BANNER command. The NOHIGHLIGHT command (which does not require a parameter) is a shortcut for HIGHLIGHT WHITE or its equivalents - it resets the background colour back to white, which is the default (since paper is normally white!).

Examples:

HIGHLIGHT LIGHT_RED
HIGHLIGHT #FF0000
HIGHLIGHT 100%, 0%, 0%


IMAGE scale_factor% image_data
IMAGE field_data

scale_factor% specifies the size of the image. The default is 100% when this setting is missing.

image_data represents the full path spec to an image held on your computer. Images must be in BMP, GIF or JPG file format. The image will be aligned using the current font alignment setting.

field_data is a piece of text interpreted in exactly the same way as for a TEXT command (see the TEXT command, and the section Literal Text, Variables & Quotes). The difference is that the resulting piece of text must represent a valid field in the current database row. If it does not, a small is shown. The IMAGE command should only be used in this context inside a LOOP.

Examples:

IMAGE 100% "F:\My Documents\Public Talks\HallMap.jpg"
IMAGE 100% "CURRENT.Location Map"


INCLUDE script_name

script_name should only specify the name of the script without any path. It can be qualified with speech marks.


LINESPACING literal_number_or_expression

spacing_data must be any of the following values:

 1.0 (or SINGLE), 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 2.0 (or DOUBLE).

It means the number of lines to skip. 1.0 means normal line spacing; 2.0 means leave a single blank between lines, as if BLANK had been issued in between each EOL. 1.x is between the two, of course. Note that any banner colour will fill in the gaps left by such spacing, just as it does for BLANK.

Example:

LINESPACING 2


IF [NOT] where_clause[, where_clause]
END_IF

END_IF marks the end of the set of commands to be executed once if the current row meets the specified criteria. where_clause is of the form field_data IS text_data field_data CONTAINS text_data,  field_data ISLESSOREQUALTO text_data , etc. text_data is either a piece of literal text (* see below) to compare against (normal rules apply, see the TEXT command for details), or field_data. CURRENT and the dot are *not* required, as fields are always from the current loop row being examined (i.e., the one in progress before this IF command); once again normal rules for field names apply (see the FIELD command for details). NOT will examine the criteria for a match, and then do the opposite. Thus, a typical condition might be IF "Brother" ISNOT "J. Samuels" or IF NOT "Talk Number" ISLESS "1000". Note that you can combine multiple condition clauses by separating with commas. All such clauses are applied to the current row to determine if it is acceptable, and if not, the contents of the IF are ignored. Any condition clauses that cannot be understood are ignored and no attempt is made to apply them to the current row (but any other clauses on the line are still checked). Note also that you can embed inner loops and IFs within existing loops or Ifs, but for Ifs, the row being examined is *always* the current row from the innermost LOOP containing the IF. Each IF must be matched by an END_IF, and all commands between those two commands will be executed if the current row matches the criteria. field_data is exactly as for the FIELD command.

Unlike commands such as FONT, the keywords and parameters for the IF command, if supplied, must be supplied in the order shown. Condition clauses obviously can be in any order, though, within their section of the command.

Example:

IF "Chairman" IS "Chairman 1"
              (commands go inside IF)
END_IF

text_data* The text value can also be a variable name, such as $variable.  Also, it is important to use valid text if specifying literal text.  Depending on the field type, you must follow this set of rules (not that you don't need to worry if you are creating the script through the editor / control panel).

Advanced syntax:
 
IF [NOT] where_clause[ {AND|OR} where_clause[...] ]
END_IF
 
where_clause is exactly as before, except that if you include it in brackets, you can put NOT in front to negate just that clause. Note that if you include a NOT right at the beginning of all clauses without brackets, it will negate the whole expression, not just the first clause - this is for backwards compatibility. To negate any clause individually, always enclose it in brackets to be safe.
 
The original clause separator was the comma (,), which acted as an implicit AND. This is still perfectly valid, but you can now mix any combination of AND, OR and NOT, and by using brackets you can alter priorities. By default, OR will be evaluated before AND. It is strongly recommended to put brackets around combinations to show the intended priority clearly. If you mix the comma and AND / OR / NOT (not recommended), everything between each comma will be treated as if it were inside brackets.
 
Example:
 
IF ("Congregation" IS "$LocalCong" AND “Brother” ISNOT “$strThisBrother”) OR (NOT “Talk Number” ISLESSOREQUAL “160”)
 
    (this condition will now fire if the congregation is your local one and the brother is not the one named;
    it will also trigger if the talk number is 161 or higher (not less than or equal to 160) )
 
    (commands go inside IF)
END_IF

LOOKUP_FIELD "field_name" $variable_name FROM / SQL normal_loop_clause_syntax

LOOKUP_FIELD combines a normal LOOP with an embedded VARIABLE_FIELD command, to extract a single piece of data from a single row of the database.

If multiple rows are returned by the loop command portion, each successive row will overwrite the variable with the data from the relevant field. While this may seem odd, it does have its uses; by listing rows in date order, for example, you can find out data for the last talk heard (for a brother, a talk number, etc.).

normal_loop_clause_syntax refers to a normal WHERE clause (FROM) or a proper SQL statement (SQL); see the LOOP topic for more information.

Note that the front half is the same syntax as VARIABLE_FIELD.


LOOP [FROM] table_data [NODATERANGE] [WHERE where_clause[, where_clause]] [[REVERSE_]SORTBY field_data] ...
                                                                                                                                                 ... [ROW_COUNT $variable_name]

END_LOOP

table_data is one of the table names in the database (if you have added your own tables, you could choose one of them). END_LOOP marks the end of the set of commands to be repeated once for every row pulled from the table (but only those rows that meet the specified criteria).

where_clause is of the form field_data IS text_data,  field_data ISNOT text_data,  field_data CONTAINS text_data,  field_data STARTSWITH text_data or  field_data ENDWITH text_data. ** Please be aware that the LOOP criteria has been enhanced considerably. Please review the LOOP help topic for full details about the new options. **

field_data is always a field from the new table (the one named in the LOOP command); normal rules for field names apply (see the FIELD command for details).

text_data is either a piece of literal text (* see below) to compare against (normal rules apply, see the TEXT command for details), or a special form of a field of the form CURRENT.field_data. CURRENT and the dot are required, and indicate that the data should be compared against a field from the current row being examined (i.e., the one in progress before this LOOP command); once again normal rules for field names apply (see the FIELD command for details). Thus, a typical loop might be LOOP FROM "Away Talks" WHERE "Brother" ISNOT "J. Samuels" or LOOP FROM "Away Talks" WHERE "Last Given" IS CURRENT."Talk Date".

Note that you can combine multiple WHERE clauses by separating with commas. All such clauses are applied to the current row to determine if it is acceptable, and if not, the next row is fetched and so on, until none are left. Note that you must be prepared for the possibility that no rows at all match the criteria for a LOOP command, and thus it will appear to have no effect. Any WHERE clauses that cannot be understood are ignored and no attempt is made to apply them to the current row (but any other clauses on the line are still checked).

Note also that you can embed inner loops within existing loops. Each LOOP must be matched by an END_LOOP, and all commands between those two commands will be executed for each matching row. However, if an outer loop skips a row because it does not match the criteria, any inner loops will not be executed for that row; this is logical - if the row is not suitable for the outer loop, then it is not suitable for anything within that loop, including inner loops. Once a loop has ended the table it was examining is no longer 'current', and FIELD commands will revert to the outer loop (or nothing if there are no outer loops).

You can optionally sort the order in which rows are processed from this loop by adding SORTBY (increasing order) or REVERSE_SORTBY (decreasing order). field_data is exactly as for the FIELD command.

The NODATERANGE keyword will prevent the loop from using the date range specified when creating the report (or before entering the editor, if editing the script). Note, though, that the date range ONLY applies to Home Talks, Away Talks, Public Talk Titles and Congregations tables - it has no effect on any other table, even ones you may have added. It will be ignored for any other table.

You can optionally save the number of rows in the loop to a user defined variable by adding ROW_COUNT "$variable-name" to the end of the LOOP command. The variable needs to be already defined at the top of the script using REQUIRES. Be careful not to use this row count variable for any other part of the loop command, such as WHERE or SORTBY clauses, otherwise you won’t get the expected results.

Unlike commands such as FONT, the keywords and parameters for the LOOP command, if supplied, must be supplied in the order shown. WHERE clauses obviously can be in any order, though, within their section of the command.

Examples:

LOOP FROM "Home Talks" WHERE "Chairman" IS "Chairman 1" SORTBY "Last Given"
              (commands go inside loop)
END_LOOP

REQUIRES "Number Home Talks (internal variable)" AS $HomeTalksRowCount VALUES "0"
LOOP FROM "Home Talks" WHERE "Chairman" IS "Chairman 1" SORTBY "Last Given" ROW_COUNT "$HomeTalksRowCount"

              (commands go inside loop)
END_LOOP
TEXT "Number of rows found: $HomeTalksRowCount"
EOL

text_data* The text value can also be a variable name, such as $variable.  Also, it is important to use valid text if specifying literal text.  Depending on the field type, you must follow this set of rules (not that you don't need to worry if you are creating the script through the editor / control panel).

Text Field Text fields have no limitations.  Virtually any value is accepted.
Number Field Number fields expect to be numeric.  So only use numbers (0 to 9)
Tentative Field Tentative field is actually a YES/NO field.  Use 0 for YES and -1 for NO.
Date Field Date fields must follow a strict pattern: #YYYY MM DD#  For example, given the date "January 4th, 1999", it would be represented with:
#1999 01 04#

Advanced syntax:


LOOP [FROM] table_data [NODATERANGE] [WHERE where_clause[ {AND|OR} where_clause]] [[REVERSE_]SORTBY field_data] ...
                                                                                                                                                ... [ROW_COUNT $variable_name]
END_LOOP

where_clause is exactly as before, except that if you include it in brackets, you can put NOT in front to negate just that clause.

The original clause separator was the comma (,), which acted as an implicit AND. This is still perfectly valid, but you can now mix any combination of AND, OR and NOT, and by using brackets you can alter priorities. By default, OR will be evaluated before AND. It is strongly recommended to put brackets around combinations to show the intended priority clearly. If you mix the comma and AND / OR / NOT (not recommended), everything between each comma will be treated as if it were inside brackets.

Example:

LOOP FROM "Home Talks"  WHERE ("Congregation" IS "$LocalCong" AND “Brother” ISNOT “$strThisBrother”) OR (NOT “Talk Number” ISLESSOREQUAL “160”)

  (these commands will now execute if the congregation is your local one and the brother is not the one named;
  they will also execute if the talk number is 161 or higher (not less than or equal to 160) )

  (commands go inside LOOP)
END_LOOP

Advanced syntax 2:
 
LOOP SQL "full_sql_select_statement" [ROW_COUNT $variable_name]
    (commands go inside LOOP)
END_LOOP
 
full_sql_select_statement should be a complete SQL SELECT statement to gather the records that you require; it will be passed almost verbatim to the database drivers. Like the data for the TEXT command it can contain embedded variables, which will be translated before passing through. Unlike standard WHERE clauses it cannot contain CURRENT."field_name"; if you need this then you should use VARIABLE_FIELD to assign the field to a variable, and embed the variable instead.
 
Note that since SQL requires single quotes around strings, if you are embedding variables in the string, they must still be surrounded in the single quotes – this is not done automatically. This allows a numeric variable to be entered and still form legal SQL.
 
Note that since a SELECT statement can contain table joins, this can be used to simplify and speed up scripts by combining what would originally have been nested loops into a single action. However, unlike in most implementations of SQL, if two tables have a field of the same name, these cannot be accessed separately within your script. This is because fields are only accessed by the field name, with no table to qualify it. To overcome this you should us SQL’s AS keyword to create an alias for the field name. This will then provide a unique name that can be used to extract the field.
 
NODATERANGE and SORTBY / REVERSE_SORTBY are not supported when using raw SQL syntax; doing so will confuse the parser and will most likely result in failure. ROW_COUNT is still supported as normal.
 
Examples:
 
LOOP SQL “SELECT * FROM [Away Talks] WHERE [Brother] LIKE ‘$strThisBrother’ ORDER BY [Talk Date];” ROW_COUNT $iNumRows
    ...
END_LOOP

LOOP SQL "SELECT [Congregation Speakers].Speaker, [Congregation Speakers].Notes, Congregations.Notes AS [CongNotes]
                    FROM [Congregation Speakers]
                        INNER JOIN Congregations ON [Congregation Speakers].Congregation = Congregations.Congregations"
                    ORDER BY [Congregation Speakers].Speaker"
            ROW_COUNT $iNumRows    (statement split over multiple physical lines for clarity only)
    FIELD "Notes" (the speaker notes)
    EOL
    FIELD "CongNotes" (was the congregation Notes field, now aliased)
    EOL
    ...
END_LOOP

Option / Counter Loop

Literal options list:

LOOP AS $variable_name FROM “option 1, option 2, option 3”
END_LOOP

Options list from variable: LOOP AS $variable_name FROM $options_variable_name
END_LOOP
Counter loop: LOOP AS $variable_name FROM start_expression TO end_expression [INCREMENT increment_expression]
END_LOOP

REQUIRES prompt_data AS variable_data [VALUES "value1,value2,value3 ..."]

prompt_data is the text to be presented to the user for each variable required. It must be enclosed in quotes, unlike TEXT and FIELD data. If it is not, the variable line will be ignored. variable_data is the name that this piece of data will be known by in the script from now onwards. It should be a single word, and must begin with and contain exactly one dollar sign ($). If it does not fit that pattern, it will be ignored. Although the line will not be ignored if more text follows a legitimate variable name, that extra text is ignored and is not part of the variable name. The dollar sign, however, is part of the name and must be used for it to work. See the section Literal Text, Variables & Quotes for details of usage. REQUIRES commands can appear anywhere in the script, but logically they must appear BEFORE you try to use the variable somewhere else, otherwise they will show ???. It would be considered good practice, though, to declare them at the top of the script, or at least before each section that uses them.

There are some reserved variable names:

You can specify a set of options to associate with the variable. These values should be comma separated, and the list of values should be enclosed in speech marks. These values will be displayed in the editor in the drop list. You can still override those choices manually if so desired. Note, if you specify only one optional value, then it will be treated as a default value (see below) rather than an option for a drop list.

Default Values

The custom script editor will raise multiple errors whenever unititialised variables have been used for LOOP and IF criteria. Consider using default variable values to avoid this issue. The first option specified for the VALUES parameter will become the default. The editor will use ??? when nothing has been specified for the VALUES parameter.

Examples:

REQUIRES "Away Speaker:" AS $AwaySpeaker
REQUIRES "Show talk numbers?" AS $bShowTalkNos VALUES "Yes,No"


SHORTDATE
SHORTDATE_TODAY
LONGDATE
LONGDATE_TODAY
CUSTOMDATE format_string
CUSTOMDATE_TODAY format_string

SHORTDATE and LONGDATE  have no parameters.  These insert today's date in the current format specified by Control Panel on your computer.  But CUSTOMDATE requires a format_string. This determines how the date will be displayed in the report.  Please see the custom date format string help topic for details of this.

The command versions ending with _TODAY are exactly the same, and will be used by the control panel.  If you want to use the date range dates that you might have passed in to the editor, then you can use the following commands, which behave exactly the same, except they use the start and end range dates:

SHORTDATE_STARTDATE
LONGDATE_STARTDATE
CUSTOMDATE_STARTDATE format_string
SHORTDATE_ENDDATE
LONGDATE_ENDDATE
CUSTOMDATE_ENDDATE format_string

If you use these start and end range dates, and you haven't actually set a date range (because you checked the "All Entries" option) it will say "<No date range specified>" in the report.

Examples:

SHORTDATE
LONGDATE
CUSTOMDATE "%A, %d %b, %Y"


SEPARATOR
SEPARATOR
line_data[, line_data]

line_data is either a line style, or a number representing the percentage of the width of the page to draw along. The number may optionally include a % sign, although it is not required. The style is one of SOLID, DOT, DASH, DOUBLE (actual line styles) or THIN, MEDIUM, THICK (line thicknesses). Note that for DOUBLE, the thickness controls how far apart the double lines are; the double lines themselves are always thin. If the style is not supplied, SOLID is assumed. If the thickness is not supplied, THIN is assumed. If no percentage is supplied, 100% is assumed. If SEPARATOR is issued with no parameter at all, SOLID, THIN and 100% are assumed. Note that separators show over the top of the banner colour.

Example:

SEPARATOR 75%, MEDIUM, DASH


TAB
TAB [<=]
literal_number_or_expression[>]
TAB *
literal_number_or_expression

The TAB command has no affect if the current font alignment ALIGN is set to CENTRE or RIGHT.

 If the = sign form is used (= sign is optional, a number on its own will assume the = sign), tab_data is treated as an explicit column number to move to (0 is the very left-most column, left edge of the drawing area, WITHIN the margins but since you don't need a tab to reach the left margin, 1 is the smallest tab stop you can specify), moving backwards and overwriting text if necessary. Explicit (absolute) tabs can be aligned to the left, centre or right of the specified tab stop. Use < if you want it right aligned.  Use > if you want it left aligned.  And use < and > if you want it centred.  If the * sign form is used, tab_data is treated as the number of tab stops to move from the current position (again, moving 0 tab stops from the current position makes no sense, so 1 is the smallest you can specify).  Relative tabs ALWAYS move to the right.

Examples:

TAB
TAB =2
TAB *2
TAB <=2    (right alignment)
TAB <=2>  (centre alignment)
TAB =2>    (left alignment)

 


TAB SET DEFAULT
TAB SET literal_number
TAB
SET literal_number %
TAB SET literal_number mm

The TAB SET command is used to change the number of tabs across the page and remains in effect until it is changed and / or reset to default.

Because tab sizes are still calculated using whole units, you may get fractional differences but when you specify a literal count of tabs, you will always get at least that many.


TALK_THEME talk_data

talk_data is either a number representing a talk number to translate directly, or it is the name of a field in the current row (normal rules apply, see the FIELD command for details). The contents of the field, once extracted, are treated as the talk number and the scripter attempts to translate them. If the translation fails, the data supplied as a parameter (or read from the database) is simply shown instead.

Examples:

TALK_THEME "Talk Number"
TALK_THEME 122


TEXT text_data

PARAGRAPH text_data

See the section Literal Text, Variables & Quotes for details of what text_data may be.   If you want to include speech marks in the text_data, you must use a special text identifier: &speech . This must be in lowercase.  Every occurrence of  &speech will get converted into a speech mark. 

If you use the PARAGRAPH keyword, it will force a new line before and after the paragraph.  Also, it can only be done in one font face, size and colour combination for the whole of the paragraph.  It is still affected by the current alignment in effect.  Newline characters can be specified anywhere within the paragraph by using \r\n. Lastly, it will NOT split over the end of a page and onto the next; if it doesn't fit within the current page completely, it starts on the next page instead.

Examples:

TEXT "This is some text"
TEXT "This is some text using a $variable"
TEXT "&speech"
TEXT "&speechHello!&speech"
PARAGRAPH "This is a really long paragraph of text for $variable.  It will word wrap however many lines are required to show it on the page."


A description of using variables and literal text now follows:

Literal Text, Variables & Quotes

In several places field names and pieces of literal text can be used. The parser tries to be flexible in how it accepts the text, but there are limits. Unless otherwise explicitly stated, here are the rules where text is concerned:

If in doubt, quote it!

To use a variable, simply write the variable name (including the leading dollar sign ($) ) right into the text. The parser will substitute the actual value of the variable into the text. Even if the text is unquoted as allowed above, substitution of variables still takes place. If you need a dollar sign in the line for real, just make sure it does not come right in front of a word that could make a variable name. If a dollar sign is found with a name that does not exist as a variable, they are both printed out as is. If two dollar signs occur together and the second forms part of a legal variable name, the variable is substituted as normal and the first dollar sign is left on the line also (since it is not part of the variable name). A single dollar sign by itself will also be left intact.

A variable that represents a date can be formatted by using special identifiers. If you use the control panel then it will take care of all of this for you. But here are the full details about the syntax:

$DateVariable#SHORTDATE (this will display the $DateVariable using your computers short date format).
$DateVariable#LONGDATE (this will display the $DateVariable using your computers long date format).
$DateVariable#CUSTOMDATE[format_string] (this will display the $DateVariable using your specified format string).

Note that you can include the above syntax along with other variables and text. Thus, the following are examples of valid text or field names:

"&speech" (will just display a " - speech mark).

"&speechThis is quoted text&speech" (will display "This is quoted text").

"This is quoted text."

"This is quoted text with a $Variable embedded in it." (the value of $Variable will be put in instead).

"$Speaker" (quoted, variable only)

$Brother (unquoted, variable only)

This allows for much more flexible commands:

LOOP FROM "Away Talks" WHERE $FieldName IS $FieldValue

Hello $Brother. This report was printed on $Today#LONGDATE.