Child pages
  • LSTPRC - List Processor
Skip to end of metadata
Go to start of metadata

The LSTPRC is a general purpose utility that allows users to create custom form letters and reports from their data. Data can be extracted from user files using any one of the various List Maker programs. The LSTPRC can then be used to combine or "merge" the data with a form to produce the desired output.

The form that the LSTPRC uses is created by the user or A-site personnel using a text editor, or by using the RPTGNR utility.

The following are typical applications for the LSTPRC:

  • Salary Notices
  • Form letters to vendors or employees
  • Mailing labels
  • Inventory worksheets
  • Import files for a spreadsheet program

The LSTPRC is a powerful and flexible utility, applicable to many different situations. However, although it does have some report writing capabilities, it is not a complete report writing utility. A-sites often have other tools available such as Datatrieve that may be more appropriate for more complex reports. However, the LSTPRC does provide adequate report writing capabilities for simple reports that many users can take advantage of.

The LSTPRC program also has the capability of creating spreadsheet files. LSTPRC will prompt you for the output report type. The default is "TXT" which will generate the usual printable text file. However, there are other output report types which will generate spreadsheets. By using the help key on this field, the following pop-up menu will appear. You can use the up arrow and down arrow keys to place the cursor on an option line. Then press the [Return] key to make the selection.


            ------Output Types Available------

     TXT           -  Text Report Format
     PDF           -  Adobe PDF
     CSV           -  Comma Separated Values
     TAB           -  Tab-delimited Values

When a delimited format is requested, the format will vary depending on how the form was created. See /SPREADSHEET qualifier on the <$SETUP> for more information on delimited output format.

By default the width of the ouput files is 132 columns unless the form file being used contains a <$SETUP> token specifying the desired width. While the 132 column width is acceptable for text output, the output may not be acceptable in PDF format. Therefore when creating PDF files, a <$SETUP> token may need to be added to the form file to specify the desired page width.

Please see Section 9.4, Qualifiers, for more details on the use of qualifiers.

As you read this chapter keep in mind that many of the tokens and qualifiers discussed are not needed for simple reports and forms. A usable form requires no more than a few tokens. If you're new to the LSTPRC then start with a very simple form and see what happens. You can start adding the fancy things later.

Running the program

The program may be executed by typing:

$ RUN OECN$:LSTPRC

at the $ prompt or from the menu system:

Menu> OECN
Menu> LM_TOOLS
Menu> LSTPRC

The program will prompt for the name of the list data file, the form file, the output file, and the output type.

Experienced users may wish to invoke LSTPRC as a "foriegn" command. This can be useful for running the program from a DCL command procedure:

$ LSTPRC :== $OECN$:LSTPRC
$ LSTPRC \{form_file\} \{data_file\} [output_file] \{output_type\}

Terms

Following are terms that are helpful to understand when using the LSTPRC.

Form File

A text file that defines the format for the output file. The form file defines the placement and format of values on the report, surrounding text, page headings, etc. A form file can be created using any text editor or can be created using the RPTGNR. RPTGNR can be used to create a template form file, which is saved, and then modified using an editor.

Text Editor

A text editor is a program that is provided with the computer system for creating and editing text files. It is much like a "word processor". Some users may be familar with the editor that is used
inside of the "Mail" utility on a VAX computer. If you need assistance accessing or learning the editor on your system, contact your computer center.

List Data File

Data file containing the data to be merged with a form file. List data files can be created using any of the list maker programs from other packages, such as USPS. They can also be created using Datatrieve and locally written programs. List data files are in the same format as list documents in WPS-Plus and All-in-One (products from Digital). Therefore, list files can be loaded into WPS-Plus and used with its "List Processing" capibilities.

LSTPRC will also accept delimited input files, CSV or tab-delimited. This permits LSTPRC to be used with files from sources outside state software. For example, LSTPRC can be used to convert CSV files received from a bank into reports or to transform them into another CSV format. Please see Section 9.3, Input Files, for specific details on the use of delimited input files.

Output Report Type

The output report type is used to determine if the output file generated by LSTPRC is to be a printable text file, or is to be one of several possible types of spreadsheet files. LSTPRC currently supports text, PDF, CSV and tab-delimited output.

Tokens

Field name inside angle brackets, e.g. <SSN>. Tokens in a form file define the placement of data in output file. There are several different types of tokens. The most common type are data tokens that represent data from a list data file.

Qualifiers

Qualifiers are used to define actions to take, or to specify the format of the data within a form. Qualifiers are always preceded by a "/". Table 9-1 defines the qualifiers that can be used with tokens.

Repeating Tokens

A repeating token is a data token from a list data file that has more than one value. For example, an employee may have more than one certificate. When LSTPRC encounters a repeating token it will print each value on a separate line until all of the values have been printed.

Predefined Tokens

Predefined tokens are those that have a predefined value known by LSTPRC. These tokens are not part of the data file but may be used at any time. For instance, predefined tokens are available for the current date and time.

Special Tokens

Special tokens are tokens that cause LSTPRC to take some special action or define special types of lines. For instance, special tokens can be used to define heading lines, control breaks, sort criteria, etc. Special tokens are not part of the data file, but can appear anywhere within the form file.

Virtual Tokens

A virtual token is one that is not part of the actual data file but is created when the form is used. A virtual token may be calculated from other tokens (for instance by adding two tokens together) or the user of the form may be prompted for the value of the token.

Input Files

The use of LSTPRC requires the use of an input file which contains the data to be merged with a form file. When running LSTPRC, the program will prompt for the name of the input file to be used. These files can be in standard list format created by any of the list maker programs from other state software packages, datatrieve, or locally written programs. The input files may also be CSV or tab-delimited files created by sources outside state software, such as a CSV file received from a local bank.

The extension of the file entered in LSTPRC determines how it will be processed. Files with a ".CSV" extension will be treated as CSV while files with a ".TXT" extenstion will be treated as tab-delimited. All other extensions will be treated as standard list format.

LSTPRC transparently converts the delimited records into tokens and merges them with the specified form files. The first record of a delimited file must contain field names that are to be converted to token names. The conversion from field names to token names uses the following rules:

  • special characters and spaces are converted to underscores
  • field names are converted to uppercase
  • field names beginning with a numeric character will be prefixed with an "X"
  • if necessary, field names are enclosed in angle brackets

The following table provides examples of how several field names would be converted to token names.

Field Name Token Name

"Last Name"

"<LAST_NAME>"

"last.name"

"<LAST_NAME>"

"401K-AMT"

"<X401K_AMT>"

"<FIRST$NAME>"

"<FIRST_NAME>"

Whether a delimited file or a list file is being used for the input file, there is no difference in the form file and how the tokens are referenced. That is, the form file being used can contain references to the tokens in the delimited files in the same manner as a standard list file.

Qualifiers

Qualifiers are used on tokens within a form file to control the format of the data and to cause the LSTPRC to take special action. The following sections describe the various type of qualifiers.

Editing Qualifiers

Editing qualifiers affect the format and position of the data as it will appear in the output file. These qualifiers can be used on data, virtual or predefined tokens.

Qualifier Definition

/TL

Trims Leading spaces from the value.

/POS=n

Causes the data to begin in the column position specified by n.

/POS=EOL

Causes the data to begin printing at the end of the current line.

/POS=EOL+n

Causes the data to begin printing at the end of the current line plus n characters.

/FIXED=n

Forces a fixed length field n characters long. It will truncate the field if the data is more than n characters, otherwise it will be padded with blanks.

/RIGHT

Right justifies the field, requires the use of /FIXED. The field will be right justified in a field n characters long (as specified in /FIXED=n).

/CENTER

Centers the field, requires the use of /FIXED. The data value will be centered inside of an area defined by the /FIXED qualifier.

/HIDE

Hides the token (doesn't print on the form). Can be used as a place holder to control placement of subsequent tokens.

/UPPER

Converts characters to uppercase.

/LOWER

Converts characters to lowercase.

/CAP

Capitalizes first character of each word and converts the remaining characters of the words to lowercase. Note that /UPPER, /LOWER and /CAP are mutually exclusive.

/EDIT="string"

Edits the token data depending on the characters given in 'string'. Datatrieve-like editing characters are used.

/FIRST=n

For repeating tokens, specifies the first occurrence of the token to print. If not specified then repeating tokens begin printing with the first occurrence.

/LAST=n

For repeating tokens, specifies the last occurrence of the token to print. If not specified then repeating tokens print until the last occurrence. /FIRST and /LAST may be used together or separately to control which occurrences of a repeating token is printed.

These qualifiers may be used in any combination and may be specified in any order. The following examples show how to use qualifiers with a token and what action is taken as a result of the usage.

List Processor Examples of Qualified Tokens


<CONTRACT_AMT/TL>      - The CONTRACT_AMT field will be
                                    trimmed of leading spaces.
<TITLE/POS=10>         - The TITLE field will start printing
                                    in print position 10.
<DAILY_RATE/TL/POS=60> - The DAILY_RATE field will be trimmed
                                    of leading characters and start
                                    printing in position 60.

<HEADING/FIXED=40/CENTER> - Centers the value of HEADING in a
           field 40 characters long.

Using the /EDIT Qualifier

The /EDIT qualifier will format the value based on an "edit mask". For instance, an edit mask can specify decimal or comma positions within an numeric field or slashes within a date field.

If the EDIT `string' is a numeric edit (ie. contains a 9,$,-- or z), then the token data must contain a valid numeric string. It may contain commas, decimal point, dollar signs, etc. If the token data contains an invalid numeric string, then the data will print without any editing (ie. it will print as is).

If the EDIT `string' contains only alpha editing characters, then the token data string may contain any sequence of characters.

The following editing characters are supported:

Data Characters:


A — Alphabetic (removes numerics and compresses)
X — Alphanumeric
9 — Numeric


Operation Symbols:
S — Causes output field to contain trailing overpunch sign

(compatible with COBOL display-type numeric data

items)
V — Assumed decimal position


Replacement Characters:
Z — Zero suppression (leading zeros)
$ — Zero suppression with floating dollar sign
– — Zero suppression with floating minus sign


Insertion Characters:
B — Inserts blank (alpha edit fields only)
/ — Slash (alpha only)
, — Comma
. — Decimal point

All other special characters (not listed above) will be treated as insertion characters.

The following are examples of valid numeric edit strings:

Qualifier Definition Before Edit After Edit

<AMT/EDIT="ZZZ,ZZZ.99">

Zero suppressed with commas and explicit decimal position

000999.99

999.99

<AMT/EDIT="- - , - -.99">

Same as above with floating negative sign

-000999.99

-999.99

<AMT/EDIT="$$$,$$9.99">

Floating dollar sign with at least one numeric position to the left of the decimal

000999.99

$999.99

<AMT/EDIT="9999V99">

Zero filled numeric with assumed decimal

9.50

000950

The following are examples of valid alphanumeric edit strings:

<SSN/EDIT="XXXBXXBXXXX">

SSN edited with blanks.

<DATA/EDIT="XX/XX/XX">

Date edited with slashes.

The /EDIT qualifier can be used with other qualifiers such as /TL, /CAP, /POS etc. to further affect the format of the field.

Value-assignment Qualifiers

Value-Assignment Qualifiers can be used to create virtual tokens. A virtual token is simply a token created using the value from other tokens. These qualifiers are highly flexible and offer a great deal of control over how the output file is produced.

Since virtual tokens are created by the form itself, care should be taken not to duplicate the name of another data or predefined token. For this reason it is recommended that you create all virtual token names beginning with an underscore (_). For example, a token called <_SAMPLE> would not conflict with another token because the list makers never begin their token names with an underscore.

Qualifier Definition

/PROMPT=`string'

Prompt the user for value of token. Optional prompt string may be specified. The user is prompted once for the value of the token prior to LSTPRC merging any data. The value that is entered at the prompt may be used throughout the form. This type of token can be used to create a single form that may be used by many people. For example, forms can be created to prompt the user for the school district name, so more than one district could use it.

/DEFAULT=`string'

Assigns a default value to the prompt. Therefore it is only useful with /PROMPT. `String' can contain text, other tokens or both.

/VALUE=`string'

Assigns a value to a token that can then be used throughout the form. `String' can be text and/or other token names. If another token is used inside the /VALUE string, the inner token cannot also contain a /VALUE token. However, the token can be another virtual token created elsewhere in the form. /VALUE also can not be used with a series of repeating tokens.

/VALUE='expression'

This form of the /VALUE qualifier allows a simple arithmetic expression within the value. In this way, tokens can be added, subtracted, multiplied or divided. See the section below for more information about expressions.

/TOTAL

Special qualifier used with numeric tokens for totaling the value of the token. See the details which follow for the use of /TOTAL.

/SUBSTRING

Special qualifier which allows a portion of a string from a token to be extracted. See the details which follow for the use of /SUBSTRING.

Using Value-assignment Qualifiers

For example, the following line creates a virtual token called <_DIST_NAME> using /PROMPT.

<_DIST_NAME/PROMPT="District Name">

Before the LSTPRC begins formatting the output, the user will be prompted to "Enter District Name". The value that is entered is assigned to the token named <_DIST_NAME>. The token can be used throughout the form, wherever the district name is needed. /DEFAULT can be used with /PROMPT to supply a default for the prompt.

One way to use the /VALUE qualifier would be like the following:

<_NAME/VALUE="<FNAME/FIXED=1> <INITIAL> <LNAME>">

In this example, the data tokens <FNAME>, <INITIAL> and <LNAME> are placed in a single token. Then, later in the form file the token <_NAME> can be used instead of the 3 different parts of the name. Notice that qualifiers can be used on tokens inside of the /VALUE. In this case, /FIXED is used to get just the first character of the first name.

VALUE with an arithmetic operation

A special form of the /VALUE qualifier allows simple arithmetic operations to be performed on tokens that contain numeric data. The /VALUE qualifier allows the following syntax:

<_RESULT/VALUE="\{value1\}\{operator\}\{value2\}">

Where {value1} and {value2} are either tokens or numeric literals. And {operator} is one of the following:

<$PLUS>

value1 plus value2

<$MINUS>

value1 minus value2

<$TIMES>

value1 times value2

<$DIVBY>

value1 divided by value2

The result of the calculation is placed in the virtual token. Following are several examples:

    <_PLUSONE/VALUE="<YEARS><$PLUS>1">

The above token causes one (1) to be added to the value of <YEARS> with the result being placed in <_PLUSONE>.

    <_RATIO/VALUE="<EXPENDED> <$DIVBY> <BUDGET>">
    <_PERCENT/VALUE="<_RATIO> <$TIMES> 100">

The above example first divides the amount expended by the budgeted amount and places the result in <_RATIO>. This value is then multiplied by 100 to give a percentage. Notice how the result of the first calculation is used in the second. In this way, more complex calculations may be performed.

LSTPRC by default rounds at the fifth decimal position. When working with arithmetic operations it may be necessary to have the resulting figures rounded up to the nearest whole dollar. The following provides an example of how LSTPRC can be "forced" to round up to the nearest whole dollar:

<$SUPPRESS><_EXTAMT1/VALUE="<NEW_EXTENDED_SERVICE><$TIMES>
           <NEW_UNIT_AMOUNT>">
<$SUPPRESS><_EXTAMT2/VALUE="<_EXTAMT1><$DIVBY>1000">
<$SUPPRESS><_EXTAMT/VALUE="<_EXTAMT2><TIMES>1000">
<$SUPPRESS><_CONTAMT/VALUE="<NEW_CONTRACT_AMOUNT><>$MINUS><_EXTAMT>">

The result of the first calculation is being divided by 1000 to move the decimal to the left for rounding purposes. The resulting rounded figure is then multiplied by 1000 for printing purposes.

The /TOTAL Qualifier

The TOTAL qualifier is used to sum the values of different occurrences of a particular token. The token may appear anywhere in the text, but is frequently used for subtotaling at a break point or at the bottom of a page. When a token with the /TOTAL qualifier is processed, the program will print the accumulated total of that token up to that point.

The following rules apply to the use of the /TOTAL qualifier:

  • The /TOTAL qualifier can be appended to any token except tokens in the /BREAK qualifier, and tokens inside a /VALUE string.
  • If /TOTAL is appended to a non-numeric token, the result will always be zero. If /TOTAL is appended to a numeric token, each time the data record is read, the value of the token will be added to the total. If a token is sometimes numeric and sometimes non-numeric, only the numeric values will be added to the total.
  • Totals which are located on page footing lines are cleared each time the page breaks. Totals which are located on control footing lines are cleared each time a control break occurs at that level. Totals which are located on any other type of line are running totals for the entire report.
  • The program can handle a maximum of 10 of each type of total (page footing totals, control footing totals at each page break level, and running totals.)
  • Use of an /EDIT qualifier with the /TOTAL qualifier is recommended. Totals have a picture clause of S9(13)V9(5) and by default are displayed as --(13)9.99. An /EDIT qualifier can be used to display the totals in a more desirable format.

Please see the <$AT_TOP> and <$AT_BOTTOM> tokens for examples of the /TOTAL qualifier.

The SUBSTRING Qualifier

The /SUBSTRING qualifier is used to extract a portion of a string from a particular token. The format of the /SUBSTRING qualifier is as follows:

    /SUBSTRING = "\{pos\},[length]"

Where "POS" specifies the position the string to be extracted will start and "LENGTH" specifies the number of characters to be extracted. If "LENGTH" is omitted, the remainder of the string will be extracted.

The following demonstrates the use of the /SUBSTRING qualifier in extracting the month portion of a date where the "<DATE>" token is in the YYYYMMDD format.

<DATE/SUBSTRING="5,2">

Using the above example, the month would be the only portion of the date to be printed.

Predefined Tokens

The following tokens are predefined and may be used in any form file. The qualifiers may be used with them (except /PROMPT and /VALUE).

<$USERNAME>

Prints the username of the user running LSTPRC.

<$FF>

Generates a form feed.

<$DATE>

Prints current date in Mmm DD YY Format.

<$TIME>

Prints current time in HH:MM AM/PM format.

<$PAGE>

Generates a page number. Page number is incremented every time headings are printed (as generated by <$HEADING>). If no headings exist in the form, then page number is incremented once for each <$FF> token processed. If neither headings or form feeds exist, then the page count is the same as the number of list data records processed.

Special Tokens

Special tokens define special lines or determine special actions that LSTPRC is to take when it encounters them.

<$HEADING>

Marks the line as a heading line. These lines will print at top of every page.

<$FOOTING>

Marks the line as a footing line. These lines will print at the bottom of every page.

The heading and footing tokens must be in column 1 of the form file and appear on all heading and footing lines. Heading and Footing lines may contain text and other token names.

<$COMMENT>

Marks line as a comment line. This token applies to both the form and list data file. For those users that are familiar with Digital Standard Runoff (DSR), lines that begin with DSR comments ( .! and .; ) are also ignored.

<$DISPLAY>

Displays the line on the user's terminal. This may be used to provide additional information to the users as LSTPRC is merging/processing.

<$PAUSE>

Pauses the display and prompts the user to 'Press any key to continue'.

<$SUPPRESS>

Suppresses printing of the line. Normal token replacement is still performed. This is useful for placing tokens that contain /PROMPT or /VALUE qualifiers. This allows the value assignment to take place separately from the printing portion of the form. The /IF qualifier may be placed on the <$SUPPRESS> token to conditionally suppress printing of the line.

<$DISABLE>

Similar to the above <$SUPPRESS> token except that it also disables any <$POSITION> tokens on the line. For example, the following suppresses an entire line and prevents the current line from being changed if the condition is false:

<$DISABLE/IF="<AMOUNT><$EQ>0"><$POSITION/LINE=40> Amt: <AMOUNT>

<$PRINT>

Explicitly causes printing of the line. This token is the opposite of <$SUPPRESS> and in fact is the default if no other special tokens are present. This token is only useful when used with the /IF qualifier to conditionally print the line.

<$POSITION>

Allows vertical positioning within the form. By default, LSTPRC prints each form line on the next available output line. However, using <$POSITION> the current print line may be moved forwards or
backwards in the output form. The <$POSITION> accepts the following qualifiers:

/LINE=n

Changes the current line to n within the form.

/SKIP=n

If n is a positive number then advances the current line by n lines. If n is negative then backs up the current line by n lines.

<$POSITION> can only be used in the detail portion of the form. It cannot be used in headings, footings, etc.

<$SELECT>

Allows you to select whether or not a record(s) will be printed on a report based on the value of one or more tokens.

For example:

<$SELECT/IF="<ABSENCE_DAYS><$GT>6">

This means that only records in the list with ABSENCE_DAYS greater than 6 will be printed on the report.

AND Condition

You may use multiple IF qualifiers on one SELECT token. In this case all conditions must be met in order to select a record.

For example:

<$SELECT/IF="<JOB><$EQ>2"/IF="<ATTEND_DAYS><$GT>100">

That is, select only records with JOB equal 2 and ATTEND_DAYS greater than 100 for printing on the report.

OR Condition

You may use multiple SELECT tokens for an "OR" condition.

For example:

<$SELECT/IF="<JOB><$EQ>2"/IF="<ATTEND_DAYS><$GT>100"> <$SELECT/IF="<ABSENCE_DAYS><$GT>6">

In this case any record with JOB = 2 and ATTEND_DAYS greater than 100 or any record with ABSENCE_DAYS greated than 6 will be printed.

<$SETUP>

Sets up form parameters. The following special qualifiers may be used with this token:

Qualifier Action

/PAGE=n

Sets the page length

/LIMIT=n

Set the last line on which a new form can be started. After the limit is reached headings are generated.

/WIDTH=n

Sets the page width

/BREAK="token"

Forces a page break (or form feed) when the specified token changes.

/SPREADSHEET

Indicates that the form file may be automatically converted to delimited spreadsheet output (CSV or TAB)

The $SETUP token must begin in column 1, and it must be on a line by itself. Page /BREAK tokens can handle all qualifiers except the non-editing qualifiers /VALUE, /PROMPT, /DEFAULT, and /TOTAL.

The /SPREADSHEET qualifier specifies that the form may be formatted for spreadsheet output automatically by LSTPRC. By default, when LSTPRC attempts to format a form into delimited format, each token is placed on the output file in approximately the same position as the print format. The default behavior is not generally useful unless the form file was specifically designed for delimited output.

When /SPREADSHEET is specified, LSTPRC will automatically convert data from any form file into a format suitable for loading into a spreadsheet application. The following will occur when /SPREADSHEET is specified:

  • Each token from the detail portion on the form is formatted onto a single output line
  • Headings, control breaks and line positioning are ignored.
  • The first record of the file will contain the field names

/SPREADSHEET is ignored when the user requests TXT or PDF output. Therfore, a single form file may be used for both printing and delimited output.

<$SORT>

Causes LSTPRC to sort the data file prior to producing the output file. The <$SORT> token must begin in column 1 and must be followed by one or more tokens to sort by. The tokens must be data tokens and cannot be virtual tokens and cannot contain any qualifiers.

<$CALLBACK>

Defines a token based on a 3GL callback. The 3GL subroutine must exist in a sharable image. The routine must accept up to 10 arguments as strings passed by descriptor. If the routine returns more than one string, only one of them may be defined as the return value for the token.

The callback convention is modeled after UDMS' 3GL functions. Any routine written for use in UDMS should be useable in MERGE as well, provided it accepts and returns string parameters (integers passed by reference are not supported).

The <$CALLBACK> token accepts the following qualifiers:

/TOKEN="token"

The value token to be created by the callback.

/IMAGE="logical"

Logical name of the sharable image containing the routine.

/ROUTINE="routine"

Name of the routine to call.

/ARG={"argument"|"$RETURN""}

One or more string of arguments to be passed to the routine or $RETURN keyword. The /ARG's must be in the same order as the 3GL's argument list.

The value of the /ARG qualifier can contain a hardcoded value or other tokens. Processing of the /ARG value is similar to a /VALUE qualifier except that arithmetic operators are not supported. Tokens in an argument are replaced with tokens from the current data record. /ARG's may contain references to other value tokens, including other callback tokens.

Exactly one /ARG qualifier must contain the keyword "$RETURN". This argument is the one expected to contain the return value from the 3GL. The value returned by this argument will be assigned to the token in the /TOKEN qualifier.

Tokens defined by <$CALLBACK> can not be used inside any other /VALUE tokens. However, they can be used inside /IF qualifiers and thus can be used for conditional processing or record selection.

The following is an example of the <$CALLBACK> token:

    <$CALLBACK/TOKEN="<_PAYGRP>"/IMAGE="OECN$USPS_SHR"
    /ROUTINE="GETJOBINF"/ARG="<EMPID>"/ARG="PAYGRP"/ARG="$RETURN">

This example calls GETJOBINF from the USPS sharable image. The current value of <EMPID> is passed as the first argument while the string "PAYGRP" is passed as the second argument. The third argument is the return value and assigned to the token "<_PAYGRP>". The "<_PAYGRP>" token can then be used elsewhere in the form similar to other value tokens.

<$TRNLNM>

Translates an OpenVMS logical and assigns it to a value token. The resulting token can then be printed elsewhere on the form. This could be used to pass custom values, such as a district name for headings, to the form.

The format of the <$TRNLNM> token is as follows:

    <$TRNLNM/TOKEN="\{new_token\}"/LOGICAL="\{logical_name\}">

For example, the following would print the value of the "MY_DIST_NAME" logical on a heading line if the logical is defined. However, if the logical does not exist, the heading is suppressed.

    <$TRNLNM/TOKEN="<_DIST_NAME>"/LOGICAL="MY_DIST_NAME">
    <$HEADING/IF="<_DIST_NAME>">District Name: <_DIST_NAME>

<$FILL> and <$END_FILL>

These two tokens are used in pairs to cause a group of form lines to be "filled" between specified margins. Filling lines means that the output lines are adjusted so that each line starts at the left margin and comes as close to the right margin as possible. Entire words are moved one line to another as necessary to fill the lines.

These tokens are often used in the body of a form letter to reduce the ragged margins left when tokens are replaced in a paragraph.

<$FILL> and <$END_FILL> are placed before and after the lines to be filled, respectively. The <$FILL> token accepts the following qualifiers:

/LMARGIN=n

Specifies the left margin. If not specified the default is 1.

/RMARGIN=n

Specifies the right margin. If not specified the default is 80.

There may be more than one pair of <$FILL> and <$END_FILL> in a single form file, each with different margins. However, they cannot be nested and each <$FILL> must have a corresponding <$END_FILL>. Blank lines are not filled, so paragraphs within fill area will be preserved.

<$AT_TOP> and <$AT_BOTTOM>

<$AT_TOP> marks the line as a control heading at the top. While <$AT_BOTTOM> marks the line as a control footing at the bottom of a list. These lines will be printed when the specified token changes.

Following are the rules for using these tokens:

  • To use control headings and footings in a report, the report must also contain a <$SORT> line and the <$SORT> line must must occur before all <$AT_TOP> and all <$AT_BOTTOM> lines in the report.
  • When using $AT_TOP, the headings need to be on the $AT_TOP lines, not on the $HEADING token line. With the $HEADING, the /BREAK on the $AT_TOP will not work.
  • These tokens must have at least one qualifier to define the control break level at which the heading or footing will print. However, the tokens can have as many break qualifiers as will fit. Multiple qualifiers mean that the text following the qualifier will print at multiple break levels.

The following special qualifiers may be used with these tokens:

Qualifier Action

/REPORT

Indicates that the line will be printed at the top of the report only (for headings) or at the bottom of the report only (for footings).

/BREAK="<break-token>"

Indicates that the text following the qualifier will be printed when the value of the break-token changes.


The break-token must exactly match a token defined in the <$SORT> line. Qualifiers and virtual tokens may not be used.

  • Break levels are determined by the order of the tokens in the <$SORT> line. The maximum number of break levels is 10. The heading or footing lines will print in the order defined by break
    levels. Within each break level, they will print in the order they are encountered in the form.
  • Control headings and footings are always printed within page headings and footings.
  • A report may contain up to 10 control heading lines and 10 control footing lines at each break level.

Examples of <$AT_TOP> and <$AT_BOTTOM> Tokens

Use of the /REPORT Qualifier

<$AT_TOP/REPORT> Text ...

will print "Text ..." at the beginning of the report only.

<$AT_BOTTOM/REPORT> Text ...

will print "Text ..." at the end of the report only.

Use of the /BREAK Qualifier

Consider the following set of tokens defined in a report.

<$SORT> <DISTRICT> <BUILDING>

<$AT_BOTTOM/BREAK= "<BUILDING>"> End of building

<$AT_BOTTOM/BREAK= "<DISTRICT>"> End of district

The report might produce the following set of detail lines:


    District 123 ...... Building 1 ......
    District 123 ...... Building 1 ......

       End of building  (Break on <BUILDING>)

    District 123 ...... Building 2 ......
    District 123 ...... Building 2 ......
    District 123 ...... Building 2 ......

       End of building
       End of district  (Break on <DISTRICT>)

    District 456 ...... Building 1 ......
    District 456 ...... Building 1 ......

       End of building
       End of district  (Break on <DISTRICT>)


Note that a change in the <DISTRICT> token, which is the primary break-token, forces a break in the secondary break-token <BUILDING>. Also note that the <$AT_BOTTOM> token will cause the break lines to print at the bottom or end of the report.

Use of the /TOTAL Qualifier

Consider the following sample report which sums the grades for all of the students in a building, then prints, clears the total, and starts retotaling when a different building occurs. There are four column headings in the report.


<$HEADING>      Building      Student ID      Student Name      Grade
<$SORT> <BUILDING>
<$AT_BOTTOM/BREAK="<BUILDING>">Total for Building <BUILDING>: <GRADE/TOTAL>
<BUILDING> <STUDENT_ID> <NAME> <GRADE>

The report might produce the following set of detail lines:


      Building      Student ID      Student Name      Grade

      Building 123      1000          D. Jones          100
      Building 123      1005          J. Smith           70
      Building 123      1010          S. Green           80

      Total for Building 123:  250


      Building 456      2100          T. Calvin         100
      Building 456      2200          B. Jones           80

      Total for Building 456:  180


Conditional Processing using /IF

A special qualifier, /IF, may be used to cause *conditional processing* to occur. This means that it is possible to specify under what conditions a token or line will be processed or printed.

/IF may be used on any data token, virtual token and on the <$HEADING>, <$POSITION>, <$PRINT>, <$SUPPRESS>, and <$SELECT> special tokens. It cannot be used on other special tokens. When /IF is used on a data or virtual token, the token will only be printed if the condition is true. When used on <$PRINT> the entire line will be printed if the condition is true. When used on <$SUPPRESS> the entire line will be suppressed if the condition is true.

Regardless what type of token /IF is used with it always takes one of the following formats:

In the following syntax definitions braces ({}) indicates the portion of the syntax that is required. Square brackets ([]) indicate the syntax is optional. Braces and brackets are not to be entered into the form.

  • /IF="[<$NOT>]{token}"
    This determines if the token is defined. "Defined" in this case means that the token exists and has a non-blank value. The optional <$NOT> token may be specified to determine if the token is not defined.
  • /IF="{value1}[<$NOT>]{condition}{value2}"
    This determines if the specified condition is true. "Value1" and "value2" may consist of tokens and/or text. Tokens are permitted on either or both sides of the condition. "Condition" may be one of the following:
Condition Meaning

<$EQ>

True if value1 is equal to value2

<$LT>

True if value1 is less than value2

<$GT>

True if value1 is greater than value2

<$LE>

True if value1 less than or equal to value2

<$GE>

True if value1 greater than or equal to value2

<$MATCH>

True if value meets specified wildcard pattern


The optional <$NOT> may be specified to test for the opposite of the condition. For example, <$NOT><$EQ> means "not equal to".

In either form /IF will cause the token which it is applied to, to become active whenever the condition is true. Below are several examples of using /IF.

These examples use tokens from the USASLM/CASHLM list maker from the USAS package.

<CUR_ENCUMBERED/IF="<CUR_ENCUMBERED><$GT>500.00">

The above example prints the <CUR_ENCUMBERED> token only if it is greater than 500.00.

<$PRINT/IF="<CUR_ENCUMBERED><$GT>500.00">  <FUND> <SCC>

The above example prints line containing the fund and SCC if the <CUR_ENCUMBERED> is greater than 500.00.

Use of <$MATCH> Condition

The <$MATCH> condition can be used in an /IF expression to test a value against a specified wildcard pattern. The format for using this condition is as follows:

"\{STRING\}<$MATCH>\{WILDCARD\}"

Where the "string" or "wildcard" may contain other token values which will be replaced prior to checking the wildcard. For example, the following statement will select records only if the full name contains "SMITH":

<$SELECT/IF="<FULL_NAME><$MATCH>*SMITH*">

Any of the standard OECN wildcard characters may be used with the <$MATCH> condition.

<$SELECT/IF="<SCC><$MATCH>%%%@">

The above example would select only accounts with the last digit of the special cost center being alpha numeric.

Form File Examples

If the district is creating a salary notice using the field names from the New Contract data, the salary notice form file could look like the following example.


                           S A L A R Y   N O T I C E
<USER_1/POS=29>
<USER_2/POS=29>


<FNAME> <INITIAL> <LNAME>
<STREET>
<CITY>, <STATE>  <ZIP>

         Dear <FNAME>,

         Your contracted salary for the 1991-92 school year will be
        <CONTRACT_AMT>, payable in <NUM_PAYS> pays.  The amount
         will be <PAY_PER_PERIOD> in nearly equal pays.

                           _________________________
                                   TREASURER

                           _________________________
                                BOARD PRESIDENT

After processing LSTPRC the first page of the finished document would look like the following example.

List Processor Example form file created with a text editor
List Processor Example output produced by LSTPRC

                           S A L A R Y   N O T I C E

                            Sample School District
                            Sample City, OH   45000



         John H. Doe
         125 Ridgeview St.
         Sample City, OH   45000

         Dear John,

         Your contracted salary for the 1991-92 school year will be
         26000, payable in 26 pays.  The amount will be 1000 in nearly
         equal pays.


                           _________________________
                                   TREASURER

                           _________________________
                                BOARD PRESIDENT

The following is an example using some of the more advanced features.

<$SUPPRESS> <_DISTRICT/PROMPT="District Name">
<$SUPPRESS> <_DIST_ADDR/PROMPT="District Address">
<$SUPPRESS> <_FULLNAME/VALUE="<FNAME> <INITIAL> <LNAME>">
<$SUPPRESS> <_EMP_ADDR/VALUE="<CITY>, <STATE>  <ZIP>">

                           S A L A R Y   N O T I C E
<$DATE/CENTER/FIXED=80>

<_DISTRICT/CENTER/CAP/FIXED=80>
<_DIST_ADDR/CENTER/FIXED=80>

<_FULLNAME>
<STREET>
<_EMP_ADDR>

<$FILL/LMARGIN=10/RMARGIN=70>

         Dear <FNAME>,

         Your contracted salary for the 1991-92 school year will be
         <CONTRACT_AMT>, payable in <NUM_PAYS> pays.
  The amount will be <PAY_PER_PERIOD> in nearly equal pays.

<$END_FILL>

                           _________________________
                                   TREASURER

                           _________________________
                                BOARD PRESIDENT

The printed document would look like the following.

List Processor Example of the advanced features
List Processor Example output using the advanced features

                           S A L A R Y   N O T I C E
                                 Oct 30 91

                            Sample School District
                                 123 Main St.


         John H. Doe
         125 Ridgeview St.
         Sample City, OH   45000

         Dear John,

         Your contracted salary for the 1991-92 school year will be
         26000, payable in 26 pays.  The amount will be 1000 in nearly
         equal pays.

                           _________________________
                                   TREASURER

                          _________________________
                                BOARD PRESIDENT
  • No labels