Defining Ispecs
An external Automatic Entry requires a minimum of two classes: one on the Originating application (an <<ExternalIspec>> class that does not have any persistent members, that has presentation), and the other (with identical attributes) on the Destination application (<<Ispec>> class that might have persistent members and has presentation).
The <<Ispec>> class (Ispec) on the Originating application must have the AutomaticEntryCapable model property set to True using the Ispec Properties window in Developer. The Ispec on the Destination application accepts external Automatic Entries regardless of its AutomaticEntryCapable property setting.
Note: The first five characters of the transaction identify the Ispec. In earlier versions, Ispec names were limited to a maximum of five characters which meant that the Ispec field in the NOF format had length equal to five. In Agile Business Suite, full Ispec names can be up to 65 characters in length. However, to maintain backwardscompatibility, the NOF format continues to allow only five characters for the Ispec name, and therefore uses the Ispec Alias value (which is limited to five characters)to identify the Ispec.
Three possible designs that represent some of the more common approaches to using external Automatic Entries are described in the following subsections. The coding required for the external Automatic Entry mechanism remains the same, regardless of which design is used.
Design 1
This design uses the minimum of two Ispecs: one on the Originating application, and the other (with identical attributes) on the Destination application. The code to initiate the external Automatic Entry is contained in the Ispec on the client application.
For example, customer records might be shared between two applications. If a customer inquiry is performed on one of these applications, and the customer is not found, the Ispec could perform an inquiry on the other application by using an external Automatic Entry.
Design 2
This design uses an identical Ispec on the Originating and Destination applications, and an additional Ispec on the Originating application that contains the code to initiate the external Automatic Entry. This approach is generally used to centralize external Automatic Entry code in a limited number of Ispecs.
For example, users of an accounting application might occasionally need to update employee records and asset records, which are stored in other applications. The code in the accounting application that performs the external Automatic Entries to both the staff and asset applications could be centralized in one Ispec.
Design 3
This design, which gives most flexibility with external Automatic Entries, uses special Ispecs to handle interfacing. This means defining a pair of identical Ispecs (one in each communicating application) solely for external Automatic Entries. These Ispecs would contain all the attributes needed, but need not reflect any database structures.
An external Automatic Entry is passed using these Ispecs, and the Destination application then inspects the data passed and performs required actions, such as an internal Automatic Entry to another Ispec.
For example, an application might be required to pass all new customer records to another application that has a different customer record structure. You can define a pair of Ispecs that contained all the attributes required, and use these for external Automatic Entries. The server Ispec, having received the customer record in the form it was entered, must perform an internal Automatic Entry to its own customer Ispec.
This approach to external Automatic Entries might increase the amount of code required to handle an external Automatic Entry, but where a number of different external Automatic Entries are required, it could be used to reduce the total number of Ispecs. This would reduce the need for database reorganizations when changes are made to external Automatic Entry structures on the Destination application.
External Ispecs
An Ispec can be reserved for the use of external Automatic Entries only. You can do this by setting the Ispec’s IsExternal property to True using the properties window in Developer. This avoids the requirement for a physical database structure for an Ispec that is only required for external Automatic Entries, whilst still making all attributes available for their execution.
Refer to the Agile Business Suite Administration Guide for your host platform for more information on how to perform an external Automatic Entry to an External Ispec.
Defining Attributes
The maximum size of the data transferred in an Automatic Entry to another application is 2,000 bytes.
For external Automatic Entries, the Originating and Destination Ispecs must have identical Automatic Entry and Input Buffers. This means that Direction property value and screen order must match, within certain limitations.
The Ispec Type of the Originating Ispec should also match the Ispec Type of the Destination Ispec (for example, Event, Standard, Direct or Table). This is required because of the additional attributes provided automatically by Agile Business Suite (for example, Maint on Standard and Table Type Ispecs).
The actual rule is that the order of attributes within the Automatic Entry Buffer of the client Ispec and the Input Buffer of the server Ispec must match exactly. The screen placement line and position of attributes and their Direction property value define their location in these buffers. The order of attributes within the buffers is shown in the following table.
Agile Business Suite Attribute Properties | Order in the Automatic Entry Buffer | |
|---|---|---|
Direction | Persistence | |
InOut | No | Appear first in the buffers, in screen order. These two directions are interchangeable. |
InOut | Yes | |
In | No | |
In | Yes | |
None | Yes | Appear second in the buffers, in alphabetic sequence. Refer to the restrictions following the table |
Out | No | Appear last in the buffers, in screen order. |
Restrictions
When performing external Automatic Entries between hosts with different collating sequences, and if the Automatic Entry <<Ispec>> class contains attributes with Direction set to None, ensure that the order of attributes with Direction set to None does not differ between the applications. This is achieved by careful naming of attributes, as difficulties can often arise when names are chosen with the same alphabetic stem, with both numeric and alphabetic suffixes. For example, F1 and FA would cause problems, whilst F1 and F2 would not.
Note: This restriction applies between UNIX and MCP environments, between OS 2200 and MCP environments, and between Windows and MCP environments.
When applications are generated with the Network Applications Platform (NAP) option, external Automatic Entries can only be performed from Ispecs in subsystem 1. If an external Automatic Entry is attempted from any other subsystem, then an INVALID INDEX error occurs.
Note: The NAP option applies only to MCP based hosts. Refer to the Agile Business Suite Developer User Guide for more information.
Automatic Recovery and Duplicate Protection
Agile Business Suite ensures that in a recovery situation, transactions resubmitted through an external Automatic Entry are not duplicates of completed transactions.
When a transaction fails due to an environmental, system, or software fault, the transaction recovery process is implemented. This guarantees that all uncompleted transactions submitted up to the point of failure are automatically resubmitted during recovery.
As only some participants involved in an external Automatic Entry might be affected by a fault, a mechanism is required to ensure that when transactions are resubmitted by recovery, they do not duplicate already-completed transactions. This process is explained in the following subsections, for each of the following levels of transaction:
Immediate Commit Transactions
To detect duplicates when an Immediate Commit transaction system replies to an external Automatic Entry, the process shown in the following table is adopted.
Stage
Action
1
Transaction header details are stored by the receiving host in a file. Each header records the following:
Details of the transaction received
Details of the response given to the sending application
A unique transaction number and station ID
2
When an application receives a transaction, it checks the recovery indicator on the transaction header to see if the transaction is being resubmitted in recovery.
3
For those transactions being resubmitted, the receiving application checks the file for an existing entry.
If an entry exists, the receiving application returns the original reply to the sending application, and does not process the transaction.
If an entry does not exist, the receiving application stores the header details for that transaction, processes the transaction, and returns a reply.
Two-Phase Commit Transactions
Where an external Automatic Entry is made up of several subordinate transactions, the sum of these transactions is called a global transaction.
When either a client or server application has failed during a global transaction, all participants in that global transaction aborts their part of the transaction. In this case, the client application replays from the beginning, in the normal way.
With two-phase commit transactions, duplicates are thus avoided.
Manual Recovery
Within a Originating/Destination environment, you must take care when manually rolling back a subset of the participant databases.
There is no automatic method of synchronizing systems in this situation. |
CautionUndefined TCP Host Names
External Automatic Entries require that host names are defined.
Receiving an Automatic Entry from an Undefined TCP Host
When an external Automatic Entry is received from a remote host that is not defined, the remote host IPADDRESS is accessed. An attempt is made to derive a hostname (from the first level of the domain name) by using the Domain Name Service (DNS) to look up the domain name associated with the IPADDRESS.
If successful, that host name is used, and the Automatic Entry can be processed. If unsuccessful, the connection is refused (the Automatic Entry is rejected) and an error is returned to the remote host application.
Sending an Automatic Entry to an Undefined TCP Host
If your application sends an external Automatic Entry to a host that is not defined, the host name in Glb.DestHost is not recognized and an error is returned.
Note: This restriction applies to TCP only, and does not apply to BNA connections.
Sending Multiple External Automatic Entries
If you send multiple external Automatic Entries in the same transaction, ensure they are all sent to the same subsystem. Sending multiple external Automatic Entries in a single transaction to different subsystems might cause loops in the receiving subsystems.
Commit Levels
You can use Glb.Status and Glb.Hubstatus to determine failure of security checks. There are two types of commitment available to external automatic entries: immediate commit or two-phase commit.
Immediate Commit
With immediate commitment, destination applications make (commit) all changes immediately, as follows:
The originating application sends an external automatic entry.
The destination application attempts to commit the changes.
The originating application commits or aborts its changes as appropriate.
Note: If the originating application sends multiple automatic entries to the same destination application, each automatic entry is treated as a separate transaction.
Two-phase Commit
Two phase commitment ensures that all destination applications are able to commit all changes before any of these applications (including the originating application) commit.
With two-phase commitment:
The originating application sends an external automatic entry.
The destination application determines whether it is able to make (commit) the changes. It processes the transactions, but does not commit the changes to its database.
The destination application sends a message to the originating application to commit the changes.
If the destination application is able to commit, the originating application sends a message to the destination application to commit the changes.
If the destination application is not able to commit, the originating application sends a message to the destination application to abort the changes.
The originating application then commits or aborts its changes as appropriate.
Note: If the originating application sends multiple automatic entries to the same destination application, all of the automatic entries are treated as a single transaction.
Series of Automatic Entries
It is possible that an external automatic entry from the originating application causes another external Automatic Entry from the destination application. For example, when application 1 sends an Automatic Entry to application 2, the receiving transaction in application 2 cannot send an Automatic Entry back to application 1 directly, or through other applications.
If this restriction did not exist, a transaction deadlock situation could occur; for example, where application 1 is waiting for application 2, which is waiting for application 3, which is waiting for application 1.
To define the requirements for each application, consider the applications as originating and destination application pairs. Ensure that each application fulfills its role as an originating and destination application.
It is recommended that you use a two-phase commit in this situation. This ensures atomicity, that is, either all automatic entries succeed, or all fail.
Note: Closed cycles (where a destination is one of the originating applications) result in an error. Glb.Status is set to ***** and Glb.Hubstatus is set to Cycle.Error.
Atomicity
Where an external Automatic Entry is made up of several subordinate transactions, the sum of these transactions is called a global transaction.
A global transaction is said to be atomic when, if any one of its subordinate transactions fail, and is backed out, all other subordinate transactions for that global transaction are also backed out. In effect, atomicity is an all-or-nothing process.
The benefits of atomicity are shown in the following examples:
An application 1 global transaction sends an Automatic Entry to application 2. The application 1 global transaction then fails due to an edit/validation error, timeout error, or a non-recoverable system or environmental error. Without atomicity, application 2 can commit, whilst its initiator has failed.
An application 1 global transaction sends an Automatic Entry to application 2, then sends an Automatic Entry to application 3. The application 3 transaction then fails. Without atomicity, application 2 can commit whilst application 3 (and possibly application 1 also) has failed.
In both examples, if Two-Phase Commit is set, no participating transaction in the global transaction commits until all transactions are ready to commit. This means that the global transaction cannot undergo a partial commit.
Note: When Two-Phase Commit is set to True, if a global transaction is required to be backed out in a situation determined by user logic, the Abort command might be used.
Two-Phase Commit ensures that global transactions are atomic.
Note: The only situations where atomicity could be lost with the Two-Phase Commit option set is when a client or server fail after the decision to commit (or not) has been made. For example, if the originating application has passed the commit message, and is itself at the commit stage, but then fails irrecoverably.
Multilanguage Support
The external Automatic Entry mechanism supports the Agile Business Suite multilanguage facilities on all host types.
The session language of the Originating transaction is passed to the server transactions. (The language name is passed, not the language number.) This language name is used to set Glb.StaLang and the internal pointers to the message and attribute structures in participating Ispecs. If the language name is not defined in a Destination application, Glb.StaLang reverts to the default language of the server application.
The Originating transaction might thus receive replies in the originating language; for example, where logic in the Destination application uses translatable attributes to return errors in the reply.
Note: It is the application developer's responsibility to ensure that the required languages are defined and available on the Destination applications.
Security
The external Automatic Entry facility supports the Security Module (LSM) and additional security features.
The usercode from the originating transaction is passed with the external Automatic Entry, and is automatically moved into Glb.User. Any server application that receives an external Automatic Entry and has its Security Module enabled checks this usercode against its security tables. If the usercode is not valid, the transaction returns a Glb.Status value of five asterisks (*****) and a Glb.HubStatus value of SECURITY.ERROR.
Note: It is the System administrator's responsibility to ensure that the required security levels have been set up on the server applications.
Connection-level security is provided between hosts to guard against unauthorized connections. A password code is passed between participants, using authentication algorithms to ensure that participants are not emulating the HUBRouter protocol. Any mechanism illegally attempting to establish a connection to a by emulating the protocol is denied access.
Note: This security mechanism cannot protect against intruders “piggy-backing” onto an established connection at the TCP packet level. This is a TCP/IP security issue.