Variables in ELP

ELP provides a low level method to define and set variables, read variables from different sources and place them into the document. This works for any kind of data streams, so for example also for Postscript!

1. ELP provides quite some methods of gathering variables
2. ELP calculations with the key: Variable
3. ELP calculations with the key: Counter
4. Calculations with Trigger_variable

Identifiers of a variable must follow some rules:

• Must be enclosed by hashes: #<name-of-variable>#
• Some characters are not allowed like colon ':', '<', '>' and ' ' (blank)
• User defined ones (e.g. #MyVariableName#) should be initialized (e.g. “Not yet used”) in the in the rule GLOBAL like: variable=#MyVariableName#:Not yet used 

Short summary what is described in details in this document:

• Some variable names are predefined, they are listed in the next table.
• Variables can be defined using the key Variable=#name#:value.
• The variable name is treated case sensitive in alle Search, Trigger and Replacement-functions.
• Reading variables from Active Direcoriy, File, Registry, Environment etc. their names are searched in the existing variable list case insensitive. The new read content is replaced, but the name remains in the predefined sensitivity.
• Variables be loaded out of ASCII files using the key Variable_File. In that file is each line a definition like this: VariableName=Value
• Provide access to Active Directory and to the system environment variables
• ELP can also handle counter, which are normal variables, but they can be increased or decreased by any amount, once executed in a rule, maybe triggered by a searched Argument. Special counter are JobCounter.
• ELP searches for the names of the variables in the data stream, as well as in all loaded forms/macros. Once found they are automatically replaced with the current value. So for example page counter can be inserted.
• With search and StoreNextWordToVariable can ELP extract / read nearly any information out of the data stream into variables.
• With Search_RowNo is ELP able to read any information out of the data stream into a variable.
• Variable scan finally be stored into a file (Accounting and Reporting) or can be saved to hand them over to the next print job. (Counters)
• How Variables can be used

Please note, that the limitation for finding the tags in the data streams is the same, as explained in the Search and Trigger key sections. If ELP is not able to find the key, then please send your local distributor (W-ELP Control Center, License TAB, About box) the print data, we will try to find the reason.

Hints:

• To keep ELP fast processing the print jobs, wrap the search variables into the suggested start and stop characters: #! Like#Variable#.
• If leading blanks are used for right alignment, use double quotes for the value part: Variable=#MyVariable#:" 90,50Euro".
• You may format the variable values using any predefined font attributes, but also the formatting can be done in the value part, like this: Variable=#MyVariable#:\x0E\x1B)s1p12vs3b4099T 90,50 ?\x0F

How Variables can be used:

• Counters, JobCounter
• Generate a counter loop
• Watermarks
• Accounting
• Fill into a forms

1. ELP provides quite some methods of gathering variables

Variables can be used to collect information from various sources. See chapter 1. Later Variables can be used to automatically print then in forms or data streams, simply by putting the variable name in. if, for example, you did develop a form with the forms & filed installer and there the variable #DATENUM_US# is used, then the variable is replaced with "01/10/2010".

1.1. The predefined Variables which are available at start-up of the process:

A shortened list of the most popular variables.

Variables available on startup of each job, before any data stream bytes are read:

Available date and time variables (Available at start up)

Variables which are generated on demand during the treatment of the data stream

Additional variables for Accounting

Additional counters for Safe Monitored Printing:

Additional values for Plotter Multiroll support:

Note: Variables can be overwritten any time, using any method like: Variable=, Variable_File= or StoreNextWordToVariable= etc. It is NOT recommended, but possible. maybe make an own variable in the rule Global and copy the startup variable like:

[Global]

Variable=#MyUSER_NAME#:#USER_NAME#

1.2. Variables can be defined using the key Variable=[#]name[#]:value

Use the ini-files to define any additional variables. This function is for example a perfect way, to differentiate between several companies. If each company prints fixed to the same queue, the printer sections can define the variables for each company, which are used in the forms.

The syntax in the ini-file is:

Variable=#VarName#:VarValue

Notes:

• The character ':' is the differentiator between the variable name and the value. An empty value is defined, if the line ends with the colon.
• Variables are case sensitive searched.
• If a variables is found in macros / forms or in the incoming data stream, they are automatically replaced (Watermarks, Page counter )
• All read variables are not erased, when a new ini-file is selected (Search and Triggers are erased).
• Please encapsulate the variable value in "" in order to use blanks at the beginning or at the end of the value.
• Also the hex notation \x## can be used.
• If the surrounding # characters in the variable definition: #name# are missing, ELP adds them automatically
• If you add log_mode=100 (Help) to the default rule GLOBAL and after the process is finished click on the button Debug folder within ELP Control Center, Admin Tab and open the Log_file_<date-time-stamp>.txt within the <printqueue folder>. If line feeds are missing use e.g. Notepad++ for better reading. Then move nearly to the end of the file and you see a listing of all final variables.
• Variables can be overwritten any time, using any method like: Variable=, Variable_File= or StoreNextWordToVariable= etc. It is NOT recommended, but possible. Preferred: Make an own variable in the rule Global and copy the startup variable like shown at the end of last paragraph.
• Is the content of the variables being read out of the executed rule/section encoded in the Unicode format, please add this key to the same rule: Variable_Encoding=Unicode
  Please notice, while replacing within a variables other variables with a mixture of symbol sets, is currently not supported.

Example: VARIABLE=#COMPANY#:" My Company Ltd. \x22Germany\x22" From now on the variable #COMPANY# is searched in the data stream and is replaced with the ' My Company Ltd. "germany"' (without ').

Delete_Variable: This key deletes any, even ELP internal, variable from the memory. Missing # signs are added automatically.

Rename_Variable: Searches for a given variable by its accurate name and replaces the name to a new given one. Missing # signs are added automatically.
Note: The second parameter can be a new variable name as text or an existing variable where the variable value will be used as the new variable name.
Adding ;ON to the term does first replace any variables in the given new name with its values. Please make sure final variable name does not exist.

It is recommended to initialize all own defined variables in the rule GLOBAL. They also can be generated from existing variables, using operators like LEFT, RIGHT, ... operators from existing variables. See further down chapter 2.

Often they are used in a Boolean way to set them e.g. to FALSE, then if some searches come true they are set to TRUE and then later key Trigger_Variable can be used to activate rules on the state of the variable.

1.3. With Search_xxx and StoreNextWordTo[Int]Variable can ELP extract / read nearly any information out of the data stream into variables.

StoreNextWordToVariable The function will read the next word[s] behind the searched item into a provided ELP variable. It is recommended to initialize the variable in the rule GLOBAL with the key Variable. As an option you can specify up to 2 parameters: StoreNextWordToVariable=#MyVariableName#;x;y

By default, the gained word ends with a byte in the data stream which value is below or equal ASCII 32 (e.g. Space, Carriage Return, Line Feed etc.). Any leading bytes are ignored.

The optional x paramter reflects the minimum length of information retrieved. It can be used in any Search_xxx rule variants. With the y value any space between words do not stop the reading.

Examples Search_Binary:

StoreNextWordToVariable=#xxx#
Text: 123 456 789 0ABC DEF
Result: 123

StoreNextWordToVariable=#xxx#;10
Text: 123 456 789 0ABC DEF
Result are 11 characters: 123 456 789

Text: 123 456<CR><LF>
Result: 123 456

Text: 123 456<Esc>&a10H789
Result: 123 456

With Search_Windows PCL positioning sequences between the characters are ignored. 

Examples Search_Windows:

Search_Windows & StoreNextWordToVariable=#xxx#;10 (<Esc>&a10H is a PCL positioning sequence which is skipped within Windows)

Text: 123 456 789 0ABC DEF
Result are 11 characters: 123 456 789

Text: 123 456<CR><LF>
Result: 123 456

Text: 123 456<Esc>&a10H789 0ABC DEF
Result are 11 characters: 123 456 789

Text: 123 456<Esc>(10U789 0ABC DEF
Result: 123 456

If the second parameter y is set, the storing is stopped once a byte code below y is found. It can be set to e.g. 32 to ensure that spaces are included.

Example:

Text: 1234 567 890<CR>

Search_Binary & StoreNextWordToVariable=#xxx#
Result: 1234

Search_Binary & StoreNextWordToVariable=#xxx#;;32
Result: 1234 567 890

The y parameter can also be higher like e.g. 65 (ASCII code letter A) in order to stop filling up the variable once no more letter is found.

Example:

Text: This email address is being protected from spambots. You need JavaScript enabled to view it.

Search_Binary & StoreNextWordToVariable=#xxx#
Result: This email address is being protected from spambots. You need JavaScript enabled to view it.

Search_Binary & StoreNextWordToVariable=#xxx#;;65
Result: JOHN

The ELP key StoreNextWordToVariableMaxLen=## does end the storage after having ## characters read back from the data stream.

This stored variable can be used later in any form, even to generate variable HPS or archive index files. See chapter archive for further information.

The StoreNextWordToIntVariable reads the next number after the searched item.

If the searched section requests to delete the searched term using the Erase_Binary key, the found next word will also be erased.

Immediately after the variable is read from the data stream, the optional key TriggerSectionAfterStore is checked. Found in the same rule / section, ELP does call the provided rule name. So the variable content can be for example immediately analyzed, and actions taken.
But note, that the trigger analysis is always about Max_ReadBuffer Bytes behind the search analysis. So by default there will be no trigger available until the first 2048 bytes had been read and searched through. You may use the SetTrigger key in rule Global to activate a standard always true binary trigger in such a rule.
ADD_Binary can be used in those tested rules as well, but without ERASE_Binary. In that case the text added will be directly after the searched term and the searched term will contain the added information as well!

The key Add_BinaryAfterStore adds a provided text and/or print commands behind the information, which was read out of the stream. Erase_Binary can be used as well!
In conjunction with the TriggerSectionAfterStore the read information can be analyzed and direct new statements can be replaced or added.

The key TriggerSectionAfterStore can be used X times in the executed Search_xxx rule. E.g. in rule GLOBAL to analyze at startup some already passed information, like print queue or document name etc.

It is recommended to start and end the variable name with the # sign, as otherwise you may lose a significant processing speed.

The optional length indicates the requested minimum length in bytes of the stored item. Requested means, that if the data ends before with an escape sequence (Search_Binary mode) or any other character below ASCII 32, the parser stops reading into variable. In Search_Windows mode the positioning sequences are skipped.

If the length ends in the middle of a word, ELP will continue reading until the end of that word.

Example:

Notes for using the keys StoreNextWordTo[Int]Variable with Search_Windows_New or Search_Text_New triggered rules:

• Out of the manipulation keys, currently only ADD_Binary, Disable_Search and Search_Only_Once can be used.
• The search is processed parallel to the Trigger analysis, so after the complete data stream is read. This means, that with StoreNextWordTo[Int]Variable found variables are NOT replaced further down the data stream. But they are in later loaded macros.
• The command finds search texts coming from the new Windows drivers. The fonts themselves need to be UNICODE based! It might not work with current MS version of Calibri because the TrueType font is not Unicode compliant.
• It is not guaranteed, that characters above 127 are treated correctly.
• Does not search in Binary data. Only text and Escape sequences can be searched.
• The maximum length of read back information is 254 characters
• The Erase_binary=ON might not work under the following circumstances:
  - Downloaded characters are defined right before they are addressed. Load-CharA A Load-CharB B etc.
  - When the amount of bytes from the first character to the last may exceed the default Heap value of currently 4048 bytes or the overwritten setting using the ELP key: Max_ReadBuffer

1.4. Variables can be read out of ASCII files

The key Variable_File can read any defined variables from an ASCII file. It is recommended to store the files into the Workpath folder (e.g. c:\ProgramData\WELP) and open them with this key argument: #ELP_FORMS_PATH#ELP_VarsIn.var. You may recognize, that the filename definition of the Variable_File key may contain any previously defines variables. The file name maybe followed by a semicolon and the separator character between the variable name and variable value. Character must be > ASCII 32 (Blank). Character # is not allowed. Default sign is = ASCII 61 (Hex 3D). So the file name can be for example user or printer specific: Variable_File=#ELP_FORMS_PATH##PRINTERNAME#MyVarFile.var.

Together with the key Variables_Store values and information like for example counter can even be passed from the actual data stream to the next one or the any one coming sometimes in, you need the information.

The syntax for reading variables out of an own defined file is:

• One variable per line, VariableName=Value, like: #SURNAME#=Thomas.
• Lines starting with characters below ASCII 33 (= Blank and below) or with @ (ASCII 64) are ignored
• Leading characters in lines below ASCII 33 (= Blank and below) are ignored
• It is recommended to encapsulate the variable with # characters.
• If the variable contend is defined in Unicode, then please use the key: VARIABLE_FILE_ENCODING=Unicode to inform ELP.

Example: A plumping parts distributor has thousands of prices and a huge PageMaker based price list. For each new price list version he needed to sit down and compare 20.000 prices if they changed.
With ELP he just needed to

• export the prices from his ERP system in an external ASCII variable file, e.g. #ArticleNumber#=price
  #20.1234#=12,50 Euro
  #20.1235#=13,40Euro
• Modify the PageMaker file, and replace the prices with ELP variables, e.g.#ArticleNumber# (#20.1234#, #20.1235#,etc)
• Setup the rule to load that price file into ELP:
  

  [PriceListPrinter]

  VARIABLE_FILE=#ELP_FORMS_PATH#pricelist.txt

• Print the PageMaker file

The ELP did such a good job, that the client even started to generate client specific price lists. Another example: Send automatically printed copies to a user list.

The key Variables_Store writes all or a pack of named variables back into the provided file name, which may contain any ELP collected variable.

1.5. Reading variables out of the active directory

See here for further details: Reading ELP Variables from Active Directory

1.6. Reading from system environment

The ELP key GetEnvVariable reads any available environment viable into a ELP variable. The variable name is set to uppercase and surrounded by the # characters.

GetEnvVariable=os may lead to an ELP Variable #OS# with the content Windows_NT.

But a #OS# may also be found in the data stream (graphical data) it is recommended to make the variable name longer with: GetEnvVariable=os;MyOSNumber

Type SET in a DOS command window to view the environment settings.

1.7. [Job-] Counters

ELP can also handle counter, which are normal variables. They can be increased or decreased by any amount, once executed in a rule, maybe triggered by a searched argument. A special counter is generated with the key: JobCounter.

An example where similar variables with an own internal counter have to be counted is here: Send automatically printed copies to a user list.

1.8. The Search_RowNo key

Only used in conjunction with ASCII based print files! The key is used to read form a specific page, row and start colon number a text with a certain length into a variable.

1.9. Database variables

After a database file is opened and a special record was searched and found, ELP will read automatically some predefined variables.

The key DB_Variable can then be used to reads a field content from the database.

Notes:

1. ELP searches automatically for the names of the variables in the data stream, as well as in all loaded forms / macros. Once found they are automatically replaced with the current value. So for example a page counter can be inserted while writing the data stream out.
2. A variable name starts and ends usually with the character "#". The name itself is searched case sensitive, in binary and windows mode.
3. Please note, that the limitation for finding the tags in the data stream is the same, as explained in the Search and Trigger key sections.
4. *To ensure, if your requested variables are available, you may also store their latest values at the end of the conversion run into a file. The function is activated if the ini file key VARIABLES_STORE was found in any activated section.
5. You may use the same ELP PCL sequence in order to split a huge incoming data stream in the archive directly into its native documents. See Job Splitting for further details.

2. ELP calculations with the key Variable

Currently ELP supports the following none nestable functions for string manipulations. The Syntax of the case sensitive named functions are:

Some examples:

Notes:

• Currently ELP dos not support to combine several of those function like UPPER(LEFT(#Variable#, 5)). In this case use to command lines:
  Variable=#MyTempVar#:LEFT(#Variable#, 5)
  Variable=#MyTempVar#:UPPER(#MyTempVar#)

• Error: Will not work

  [Named Section as the user logon name]

  Variable=#FullUserName#:UPPER(Mike Miller)

  Results into the variable content: UPPER(Mike Miller). The name string is not converted, as it is no variable!

  This will do the job:

  Variable=#FullUserName#:Mike Miller

  Variable=#FullUserName#:UPPER(#FullUserName#)

Hint:

• If you add log_mode=100 (Help) to the default rule GLOBAL and after the process is finished click on the button Debug folder within ELP Control Center, Admin Tab and open the Log_file_<date-time-stamp>.txt within the <printqueue folder>. If line feeds are missing use e.g. Notepad++ for better reading. Then move nearly to the end of the file and you see a listing of all final variables.
• Use key variables_store for a listing of all collected ELP variables.

3. Performing mathematical calculations using the key: Counter

Counter=#VariableName#;*5 Does multiply the value of the variable: #VariableName#

Examples: Counter and generate a counter loop. Perform math calculations.

4. Calculations with Trigger_variable

See for an counter loop example right here.

5. Calculations with Check_TelNo

This function does erase all non digit characters out of the content of the named variable. A + at the beginning is turned into 00. Example: +49 (7031) 860910 is turned into 007031860910

How Variables can be used:

• Counters, JobCounter
• generate a counter loop
• Watermarks
• Accounting
• Fill into a forms

Related articles: Rule assistant, Search within data stream, Special keys for Searched rules, Trigger Rules, Special keys for triggered rules, Triggering rules with hierarchy