These functions do not fit in any other category, but perform useful functions, like conversion of EBCDIC data to ASCII and vice versa, sending data through mail, and so on.
Converts the current blob area from the ASCII to the EBCDIC character set.
None.
Appends the ASCII control character in the Arguments field onto the end of the current output blob area. Use the ASCII control characters from the list below. Use this filter as the first component of the first rule in a production object to place ASCII control characters at the beginning of an output transaction.
Arguments – one or more ASCII control characters.
Control Char |
Usage |
Control Char |
Usage |
Control Char |
Usage |
|---|---|---|---|---|---|
NUL |
Null |
SOH |
Start of Heading |
STX |
Start of Text |
ETX |
End of Text |
EOT |
End of transmission |
ENQ |
Enquiry |
ACK |
Acknowledge |
BEL |
Bell |
BS |
Backspace |
HT |
Horiz.Tab |
LF |
Line feed |
VT |
Vertical tab |
FF |
Form feed |
CR |
Carr. Return |
SI |
Shift In |
SO |
Shift Out |
DLE |
Data Link Escape |
DC1 |
Device Control 1 |
DC2 |
Device Control 2 |
DC3 |
Device Control 3 |
DC4 |
Device Control 4 |
NAK |
Negative Acknowledge |
SYN |
Synchronous DLE |
ETB |
End of Trans. Block |
CAN |
Cancel |
EM |
End of Media |
SUB |
Substitute |
ESC |
Escape |
FS |
Field Separator |
GS |
Group Separator |
RS |
Record Separator |
US |
Unit Separator |
DEL |
Delete |
SP |
Space Character |
ETX appends
an ETX to the current output blob area.
CR,LF appends
the sequence of CRLF to the current output blob area.
Generates either an 8-bit or a 16-bit binary variable length indicator (VLI) for the current blob area and places the VLI either at the beginning or the end of that blob area, depending on the information in the Arguments field. Use this function, or the formatted VLI function in a production object’s post-filter, to calculate the VLI for the entire output transaction.
Default (no arguments included) is a 16-bit VLI placed at the beginning of the blob area.
Arguments – “1” is
8-bit, “2” is
16-bit, and “post” specifies
to build trailing VLI.
“post” builds
a 16-bit trailing VLI.
“2post” is
same as “post”.
“1” builds
an 8-bit leading VLI.
“1post” builds
an 8-bit trailing VLI.
Translates data from one character set to another.
Source – the character set of the source data.
Target – the character set into which the source data should be translated.
The characters sets available for substitution for either source or target are ASCII, BCDIC, T-11 EBCDIC, and TN EBCDIC.
Appends a 16-bit CRC (Cyclical Redundancy Check) value to
an output blob area in the format HIGHBYTELOWBYTE.
The function processes the entire output blob area
to compute the 16-bit value.
Arguments – optional. Enter “pre” or “prefix” (without
the quotes) to place the CRC value at the front of the output blob area.
Replaces the value in the current blob with
the value contained in the column specified by the argument. To
use this filter, the content of the current blob must consist
of columns of data with each column separated by the character specified
in the argument. An example of data fitting this format is “here^is^some^data^”.
This example has four columns, each separated by a “^” character.
If the column specified in the argument does not exist or is empty, the function fails.
Column Number[,Separator] – where Column
Number is the number of the column whose contents you
want to use to replace the value of the current blob, and Separator is
the character that separates each column of data in the blob; for
example, “3,#”.
If a separator is not specified, the filter uses “^” by
default.
Data:
Here|are|6|columns|of|data| cutColumn(4,|)
Results in:
columns
Retrieves data from collection files (obtains collection file names by calling dbDiskList) into a temporary Binary Search Tree (BST), and replaces the current blob data with the sorted data from the BST, inserting an optional separator string between collection data in the current blob.
Returns “MCMEM” if
BST cannot be completed.
Retrieves only the data from collection files that match file name mask (key). Before end of function, the temporary BST is completely removed from memory.
Table – literal name of the collection on file subdirectory; dbDiskList error is blank or not found.
Key Field – enter tor select the field from which to retrieve the data.
Key Datalink – enter tor select the datalink for the field from which to retrieve the data.
Key Lit – enter the optional literal string by which to separate the output data.
Sep Lit – enter the optional literal separator by which to separate the output data.
Deletes the specified entry from the referenced collection file.
Table – the name of the collection file.
Key Field – the entry to delete.
Key Datalink – the datalink for the entry to delete.
The dbDiskAgeList built-in function builds up a key list based on the age of keys rather than using a mask on the key name like memKeyList.
See “memKeyList()” for a description of this function’s arguments.
Finds the elements in the referenced collection file that match a pattern and writes a list of those elements to a file, separated by a literal string.
Table – the name of the collection file.
Key Field – the entry for which to search.
Key Datalink – the datalink for the entry to for which to search.
Key Lit – the literal string by which to separate the elements in the list.
Sep Lit – the literal separator by which to separate the elements in the list.
Copies the contents of the current blob area to the referenced collection file.
Table – the name of the collection file.
Key Field – enter or select the field containing the data to copy and insert.
Key Datalink – enter or select the datalink for the field containing the data to copy and insert.
Copies the specified entry from the referenced collection file to the current blob area in the production object. The dbSelect() filter writes over the current contents of the blob area rather than concatenating the entry onto the current contents of the blob area. Call this filter from within an empty rule object each time you want to copy an entry from a collection file to the output transaction.
Table – the name of the collection file.
Key Field – enter or select the field containing the data to copy.
Key Datalink – enter or select the datalink for the field containing the data to copy.
Converts the current blob area from the EBCDIC to the ASCII character set.
None.
Sends the current blob area to the destination specified in the argument. The content of the argument is the e-mail destination.
Dest. – the e-mail address where the current blob area should be mailed.
Sends the current blob area to the e-mail destination specified in the argument.
Dest Fld – the field that contain the e-mail address where the current blob area should be mailed.
Sends the current blob area to the destination specified in the argument.
Dest Data – the datalink that contains the e-mail address where the current blob area should be mailed.
Generates a variable length indicator (VLI) for the current blob area and places the VLI either at the beginning or the end of that blob area. The formatting and position of the VLI depend on the information in the argument. Use this function, or the binaryVli function in a production object’s post-filter, to calculate the VLI for the entire output transaction.
The default (no arguments included) is a 16-bit VLI placed at the beginning of the blob area.
Format – format-control specifiers, as follows: %<len><type>,
where <len> is the size of the VLI in bytes,
0 for leading zero, and <type> is any one
of: “i” for
integer, “u” for
unsigned integer, “d” for
decimal, “o” for
octal, “orx” for hexadecimal.
Entering “post” anywhere
in the arguments generates a trailing VLI.
When the blob contains “12345”:
%04dpost -
builds a 4-byte, decimal, trailing VLI (“123450005”).
%04d “;” – builds
a 4-byte, decimal, leading VLI, with the “;” separator (“0005;12345”).
%04d “;” post – builds
a 4-byte, decimal, leading VLI, with the “;” separator
(“12345;00005”).
%02x – builds
a 2-byte, hexadecimal, leading VLI (“0512345”).
%010i – builds
a 10-byte, integer, leading VLI (“000000000512345”).
%03opost – builds
a 3-byte, octal, trailing VLI (“12345005”).
If you do not want to not have the length “0” filled,
remove the “0” from the command; for example, “%04dpost = %4dpost”.
Copies the contents of the file specified in the argument and places it in the current blob area, overriding the current contents of the blob.
Use only one of the available argument fields to identify the file to read. The argument can include a path or just the filename. When the argument includes a path, always use forward slashes (/). Leave the argument fields blank to use the contents of the current blob as the argument to the filter.
File – the name of the file to read.
FieldObj – the name of the field object containing the name of the file to read.
Datalink – the name of the datalink object containing the name of the file to read.
Appends the current blob area to the file name in the arguments. The file name can include its location. If the location is not included, then the file should reside in the current user’s PATH environment variable. If the function cannot find the file, it attempts to build the file and write to it. If the function cannot open the file, or cannot write to it, the function returns the system’s error number as a negative value to transaction production. Transaction production indicates in the current xlog file which operation failed (read or write), what the return value was, and ends processing of the current production object.
File – the location (optional) and name of a file
to which the current blob area should be appended;
for example, “/usr/impact/logfiles/accounting.log”.
Adds an 8-bit or 16-bit LRC (Longitudinal Redundancy Check)
value to the output blob area. The function processes
the current output blob area to compute the value.
Format of a 16-bit value is “HIGHBYTELOWBYTE”.
Arguments – enter “2” to
produce a 16-bit value. The default “LRC” is
an 8-bit value.
Retrieves node data from the BST specified by table, then replaces the current blob data with the sorted node data, inserting an optional separator string between node data in the current blob. Retrieves data only from nodes with key values that match the key mask.
Table – literal name of the
table. Generates an error if left blank (MCINPUT)
or not found (MCFIND).
The Key Field, Key Datalink, and Key Lit arguments are
required and mutually exclusive. The first non-null value to occur
is used. Generates an error (MCINPUT)
if all arguments are null (blank). The “Key..” is
used as a mask for a substring search (as opposed to an exact match).
Use “*” or “?” as
a wildcard. An error is generated (MCFIND)
if no data is found.
Key Field – name of field object to use as key mask.
Key Datalink – name of datalink to use as key mask; used only if the Key Field is left blank.
Key Lit – literal key mask; used only if both the Key Field and Key Datalink are left blank.
Sep Lit – optional. Literal string to separate
node data in the current blob. The default value
is “:”.
Removes a single node (releasing the node’s allocated memory) from the BST specified by the Table argument; if the table is empty after removing the BST node, the table node is also removed and its allocated memory released.
Table – literal name of the
table. Generates an error if left blank (MCINPUT)
or not found (MCFIND).
The Key Field and Key Datalink arguments a required
and mutually exclusive. Only one argument is used; that is, the
first non-null value to occur in the list. An error is generated
(MCINPUT) if both are null
(blank). The Key argument value must be exact. An error is generated
(MCFIND) if the key is
not found.
Key Field – name of the field object to use as the key.
Key Datalink – name of the datalink to use as the key; used only if the Key Field argument is left.
Removes (releases allocated memory of) all nodes from the table specified by the Argument, or it removes all nodes from all tables if the Argument is blank.
Arguments – literal name of the table to be completely
deleted. Generates an error (MCFIND)
if a table is specified but does not exist. If left blank (the default),
then all tables are deleted.
Adds the current blob data to a new node in the table.
Table – literal name of the
table. Generates an error if left blank (MCINPUT).
If the table does not yet exist then a new table node is created
and added to the table list. The MCMEM error
is returned if the memory cannot be allocated for a new table node.
The Key Field and Key Datalink arguments are required
and mutually exclusive. The first non-null value to occur is used.
Generates an error (MCINPUT)
if both arguments are null (blank). The “Key..” value
must be exact. An error is generated (MCDUPKEY)
if the key already exists in the table as specified by the Table
argument. The MCMEM error
is returned if memory cannot be allocated for the new node.
Key Field – name of field object to use as the key.
Key Datalink – name of datalink to use as the key; used only if the Key Field is left blank.
Replaces current blob data with an index (ordered list) of all node key values in the BST specified by the Table argument, inserting an optional separator string between each key value returned. Only retrieves key values that match the key mask.
Table – literal name of the
table. Generates an error if left blank (MCINPUT)
or not found (MCFIND).
The Key Field, Key Datalink, and Key Lit arguments are
required and mutually exclusive. The first non-null value to occur
is used. Generates an error (MCINPUT)
if all arguments are null (blank). The “Key..” is
used as a mask for a substring search (as opposed to an exact match).
Use “*” or “?” as
a wildcard. An error is generated (MCFIND)
if no matches are found.
Key Field – literal name of
the table. Generates an error if left blank (MCINPUT) or
if the specified table is not found (MCFIND).
Key Datalink – name of datalink to use as key mask; used only if the Key Field is left blank.
Key Lit – literal key mask; used only if both the Key Field and Key Datalink are left blank.
Sep Lit – optional. Literal string to separate
key names in the current blob. The default value
is “:”.
Replaces current blob data with stored data from a node, which is retrieved from the BST specified by the Table argument.
Table – literal name of the
table. Generates an error if left blank (MCINPUT)
or not found (MCFIND).
The Key Field and Key Datalink arguments are required
and mutually exclusive. The first non-null value to occur is used.
Generates an error (MCINPUT)
if all arguments are null (blank). The Key value must be exact. Generates
an error (MCFIND) if the
key is not found.
Key Field – name of the field object to use as the key.
Key Datalink – name of datalink to use as key mask; used only if the Key Field is left blank.
This function builds a key list based on the key age rather than using a mask on the key name, like memKeyList.
See“dbDiskAgeList()” for a description of the arguments.
The memUpdate function works like memInsert except if a key already exists, it overwrites the data behind the key, as opposed to failing. In reverse mode, the function appends the data.
See “memInsert()” for a description of the arguments.
Executes the UNIX command, or shell script file reference, in the arguments. The current blob area is not passed as an argument to the command or shell script.
Cmd – a UNIX command or the
name of a shell script file; for example, “myshscript”.
If you enter the name of a shell script file, the file must exist
in one of the directories included in your PATH environment
variable.
Status – optional. The exit status of the command. If the exit status does not match the status specified in this argument, then the shellCmd() filter function fails and returns a value of zero.
Select a status from the drop-down list or type a status in the entry field using this format (without the brackets):
<comparison
operator><blank space><integer value>
If the status entered does not match this format, the function fails and returns a value of -1.
If you do not use the Status argument, the filter does not fail regardless of the exit status of the command. However, it could still fail for other reasons.
WARNING! Use this function only with tables that are in a tag/value format.
Allows you to add, change, or delete a translation table file. The incoming transaction contains the delimiter (optional), the name of the translation table file to edit (optional), the action to perform on the table (add, change, delete, reload), the tag, and the value. You can also optionally write an audit trail to the significant event log. The audit trail shows the date and time the filter ran, the name of the filter (tblEdit()), the name of the acquisition module that sent the transaction (SRCRef in the route_rec() call), the directory location of the table, the action performed, the tag, and the value.
Table Name – enter the name
of the translation table file to edit only if the incoming transaction
does not contain the name of the table. To indicate when to write
an audit trail to the significant event log, enter “,AUDIT” after
the table name in this field. The comma in front of “AUDIT” is required
even if you do not enter the table name in this field.
For example, enter:
table_name,AUDIT
where table_name is the name of the translation table file to edit. Enter the table name in this argument only if the incoming transaction does not contain the name of the table.
If the table name is in the incoming transaction, you can
enter “,AUDIT”.
FieldObj – if the incoming transaction does contain the name of the table to edit, enter the field object that contains the table name.
For example, enter “FldObj_name”,
where FldObj_name is the name of the
field object containing the name of the translation table file to
edit.
The production object puts the action to perform on the table (add, change, delete, reload), a delimiter, the tag, the delimiter, and the value.
The tblEdit filter always uses the character following the action as the delimiter, therefore, the delimiter must be the same between the action and the tag, and between the tag and the value.
The information needed to edit the translation table file can either be part of an incoming transaction or the entire transaction. When it is the production object’s entire input transaction, run this filter in the production object’s post-filters. Otherwise, run this filter from a rule or rule component object.
WARNING! The tblEdit() filter reads the entire table from disk, performs the edit, and saves the table back to disk, which can affect throughput.
If the tblEdit() filter fails, e-Biz Impact places one of the following error codes into the error message text. Use the geterrtext() method within an error function to extract this error code from the error message. See “Writing error functions”.
Code |
Description |
|---|---|
0 |
The arguments to the filter are bad or invalid, or the system is out of memory, or the system suffered a disk I/O failure. |
-1 |
A change failed due to an invalid action code or not enough available memory. |
-2 |
An add failed due to a duplicate key. Seen only in releases prior to e-Biz Impact version 2.19. |
-3 |
An add failed due to not enough available memory. |
-4 |
A delete failed because the key could not be found. |
-5 |
A change failed due to not enough available memory. |
-6 |
File open error on input. |
-7 |
File open error on output. |
-8 |
File write error on output. |
-9 |
File write error on output items. |
-10 |
Rename error on regeneration of translation table. |
-11 |
Backup error on regeneration of translation table. |
-12 |
Unlink error on regeneration of translation table. |
-13 |
Translation table is not in a tag/value format. |
Example 1 – in this example, all of the necessary information is in the incoming transaction.
The incoming transaction data is:
^PRCECODE.TBL^C^123-45-678^55.60^
where “^” is
the delimiter, “PRCECODE.TBL” is
the name of the translation table file to edit, “C” is
the action to perform on the table, “123-45-678” is
the tag, and “55.60” is
the value to change.
The function builds this outgoing transaction:
C^123-45-678^55.60
The delimiter does not have to be the same in the outgoing transaction
as it is in the incoming transaction.
First the function builds field objects for the four data areas of the incoming transaction.
Next, the function builds rule component objects that place the action, tag, and value into the outgoing transaction.
Last, the function builds a post-filter to run on the outgoing transaction.
Select the tblEdit filter and place the
name of the field object that contains the name of the translation
table to edit into the FldObj argument field. If desired, place “,AUDIT” into
the Tbl Name argument field.
Example 2 – for this example, the name of the translation table to edit is not present in the incoming transaction.
The incoming transaction data is:
*A*55783*123.45
where “*” is
the delimiter, “A” is
the action to perform on the table, “55783” is
the tag, and “5.60” is
the value to change.
The function builds this outgoing transaction:
A*55783*123.45
First the function builds field objects for the three data areas of the incoming transaction.
Next, the function builds rule component objects that place the action, tag, and value into the outgoing transaction.
Last, the function builds a post-filter to run on the outgoing transaction.
Select the tblEdit filter and type the
name of the translation table to edit in the Tbl Name argument field.
You can put “,AUDIT” after
the name of the table to edit.
Example 3 – this example shows an incoming transaction that uses a trigger event.
The incoming transaction data is:
xyzzy#003|gamma|
“xyzzy#” indicates
that the following information is an addition for the ABC123.TBL file
and that the delimiter is a pipe ( | ) symbol. For example, the
programmer knows that a trigger event with “xyzzy#” is
for the specific table and uses that delimiter. “003” is
the tag and “gamma” is
the value.
The function builds this outgoing transaction:
A|003|gamma
First, the function builds field objects for the three data areas of the incoming transaction.
Second, the function builds rule component objects that place
the action, tag, and value into the outgoing transaction. You know
that the action should be “A” because “xyzzy#” indicates
an addition to the table.
Last, the function builds a post-filter to run on the outgoing transaction.
Select the tblEdit filter and in the Tbl
Name argument, then enter the name of the translation table to edit,
and, optionally, enter “,AUDIT”.
Writes the contents of the current blob area to the file specified in the arguments.
Use one of the available argument fields to identify the file in which to write. The argument can include a path or just the filename. When the argument includes a path, always use forward slashes (/). If the subdirectories specified in a path do not exist, the filter attempts to create them. Leave all argument fields blank to use the contents of the current blob as the argument to the filter.
File – the name of the file in which to write.
FieldObj – the name of the field object containing the name of the file in which to write.
Datalink – the name of the datalink object containing the name of the file in which to write.
| Copyright © 2005. Sybase Inc. All rights reserved. |
|
|
