Chapter 6: Route Calls

route_recx()

Use route_recx() to send a transaction to the SFM, through a specific production object, or through all the production objects currently available to the SFM when “ENGINE” is specified.

If the Opts argument does not contain the RO_BYPRODNAME mnemonic and the Transaction ID argument has a value other than “ENGINE,” the SFM checks its configuration file for a corresponding route, and routes the transaction to one or more delivery AIMs. If the SFM does not find a route in its configuration file, it writes the data into its unrouteable log file, and returns a value of -2 to the acquisition AIM.

If the Opts argument does not contain the RO_BYPRODNAME mnemonic and the TranID argument has a value of “ENGINE,” the SFM sends the input transaction through transaction production. Transaction production checks the transaction’s form and content against all production objects available to it.

If the transaction ID argument (TranID) has a value of “ENGINE:”

The SFM checks the transaction’s form and content against all production objects available to it:
1. The form of the data must match at least one field object set available to the current SFM.
2. The data must match the datatypes assigned to the field object definitions (for example, a field defined as a numeric datatype may not include alphabetic characters).
3. The field data must pass any non-optional qualification objects attached to the field objects.
4. The field data must pass any non-optional qualification objects attached to the production object.
If the transaction passes these tests for one or more production objects, the SFM writes it to the transaction log file and returns a value of 1 to the acquisition AIM to indicate that it received the transaction successfully.

If the transaction does not pass any of these tests, the SFM writes the transaction to its unrouteable log file and returns a value of -6 to the acquisition AIM.

If the Opts argument contains the RO_BYPRODNAME mnemonic, the SFM interprets the TranID argument as a production object name and sends the transaction data on to the specified production object. If the transaction passes the same transaction production tests described previously, the SFM writes the transaction to the transaction log file and returns a value of 1 to the acquisition AIM to indicate that the transaction was received successfully. If the transaction does not pass any of these tests, the SFM writes the transaction to its unrouteable log file and returns a value of -6 to the acquisition AIM.

Format

route_recx(int [flavor] Flavor, string [in] SRCRef, string [in] TranID, blob [in] *Data, int [in] Opts, char [in] Priority, blob [in] Fkey, blob [out] *Serial, blob [out] *ErrText, int [out] *Stat, blob [out] *Dests, blob [out] *SfmName, int [out] *SfmFlav {string | blob} [out] *hostname);

To use one of the optional arguments, you must define all of the other optional arguments that come before it so that the SFM can correctly parse the function. However, you can assign null values to the optional arguments that precede the argument you want to use.

Parameter	Description
Flavor	The flavor assigned to the SFM module that should receive the data.
SRCRef	The Source Reference Name. A user-supplied reference name for the current Acquisition AIM. Allowable characters include A – Z, a – z, 0 – 9. The string datatype is required.
TranID	A transaction ID reference for the particular record type carried in the current Data argument. The SFM uses this transaction ID to route the transaction to the correct delivery AIM. A value of “ENGINE” routes the data through all available production objects. A custom engine allows you to group multiple production objects into one engine routing package. To create a custom engine, open the SFM properties window in the Configurator and select the Routing tab. Click New in the Engines section.The SFM Engine Info dialog box appears.Enter a user-defined engine name in the Engines Add field. In the ProdObjs box, select the production objects you want to include, then click the right arrows (>>) button to move the select objects to the Grouped ProdObjs box. Click Add. The engine name appears in the Engine section. Click OK to save your entries and close the window.
Data	A string or blob field that contains the transaction’s data.
Opts	Optional. This argument is a bit mask. Use one or more of the following mnemonics to specify the options to set. Separate each mnemonic with a pipe symbol (\|). Leave this argument blank to have the SFM interpret the TranID argument as a transaction ID (like route_vrec()). `RO_BYPRODNAME` – have the SFM interpret the TranID argument as the name of a production object (like route_vprod()). `RO_BYENGINENAME` – have the SFM interpret the Tranid argument as an engine name and route the transaction by engine. `RO_SERIALDISPATCH` – have the SFM serially dispatch the transaction among its intended destinations. `RO_MUSTBEUP` – have the SFM refuse the transaction if all of the destinations for the transaction are not up. If any of the delivery AIMs specified for this transaction are not currently active, then the route_recx() command returns with a value of -10. `RO_MUSTBEPOLLED` – have the SFM query the transaction’s destinations with a servayt() call and refuse the transaction if all of the delivery AIMs for the transaction are not up. If any of the delivery AIMs specified for this transaction are not currently active, then the route_recx() command returns with a value of -10. `QO_QUALFORONE` – when the TranID is “ENGINE,” use this value to have the SFM stop submitting the transaction to production objects once the transaction has qualified for one production object. Use this option only when you are certain that the transaction will qualify for only one production object. If it qualifies for more than one production object, depending upon the order that the SFM presents the transaction to the production objects, the transaction may never get to the production object you want it to reach.
Priority	Optional. Place a number from 0 through 255 in a character argument to assign a priority to the transaction, where 1 is the lowest priority and 255 the highest.Using a priority of 0 removes a priority set in the transaction ID record. You may want to limit priorities to the 0 through 16 range, as the 17 through 255 range are reserved for future use. Any priority assigned in this argument overrides the priority assigned for the transaction in the transaction ID record in the SFM configuration. Whenever the SFM receives a transaction that has a priority set, it processes that transaction before any non-prioritized transactions that are in the log file. When more than one prioritized transaction is waiting for processing, the SFM processes transactions from the highest priority to the lowest. If multiple transactions have the same priority, the SFM processes them based on their timestamp. You can also set or change a transaction’s priority with the tranPriority built-in filter function in the Post-Qualify Rule in a production object. A priority set with the tranPriority built-in function overrides the priority assigned in this argument. When the SFM receives a transaction that has a priority set, it ignores all blocking and serialization options and processes the prioritized transaction first.
Fkey	Optional. A user-supplied foreign key that endpoints can use to further identify a transaction. The SFM uses this value in the “Once and Once Only” feature in TRAN-IDE to prevent servicing duplicate transactions. The SFM does not change the value of this argument. See the e-Biz Impact TRAN-IDE Guide for more information.
Serial	Optional. The serial number assigned by the SFM to this transaction. The SFM passes this value back to the acquisition AIM when returning from the route_recx() function.
ErrText	Optional. The error text generated by the SFM and/or the production object. The SFM passes this value back to the acquisition AIM if the route_recx() function fails.
Stat	Optional. The status of the transaction. The SFM passes this value back to the acquisition AIM when returning from the route_recx() function with a value greater than 0. Possible statuses are: `RT_QUEUED` – the transaction is queued for processing. `RT_SENT` – the transaction is being processed.
Dests	Optional. The name of the destinations to receive the transaction.
SfmName	Optional. The name of the SFM that serviced the route_recx() function.
SfmFlavor	Optional. The flavor of the SFM that serviced the route_recx() function.
hostname	This argument is optional and is used to return the host name of the SFM servicing this transaction to the acquisition AIM.

Return values

Integer.

Value	Description
> 0	The SFM accepted the record and has written it to the transaction log file.
0	General error. Check for DFC errors and the standard UNIX “errno” field.
-1	e-Biz Impact could not pass the transaction on to the SFM. Your program should check for DFC errors to find the problem.
-2	The SFM could not find the route (the transaction ID) in its configuration.
-3	The SFM could not process the transaction because the log file was full.
-5	The SFM refused the record because it is in Refuse mode.
-6	The transaction ID was “ENGINE” and transaction data did not pass form and content validation for the production objects available to the SFM.
-7	There are no valid destinations for the production objects for which the transaction qualified. Occurs when the production objects uses the setDestName() and/or the setDestNameData() dynamic routing built-ins to override the production object’s configured destinations but the built-ins do not specify valid destinations.
-8	The SFM could not process the transaction because an invalid destination was specified with a dynamic routing built-in filter function.
-9	The SFM could not append file contents to the transaction.
-10	The Opts argument contains `RO_MUSTBEUP` or `RO_MUSTBEPOLLED` and one of the delivery AIMs for the transaction is down.

Example

Example 71

// format for the route_recx() functionc	[idempotent]	int route_recx (		int [flavor] flv,		string [in] src_ref,		string [in] tranid,		string [in] *databuf,		int [in] opts,		char [in] pri,		string [in] fkey,		string [out] *serial,		string [out] *errs,		int [out] *status,		string [out] *dests,		string [out] *sfmname,		int [out] *sfmflav,	);

View this book as PDF