Automatic Entries

Automatic entries are used to pass ispec information between deployed applications. This information passing can occur between applications on the same or on different hosts. Transactions that initiate inter-application communication are fully recovered in the event of a system failure (except where the two-phase commit process abandons a transaction).

Internal Automatic Entries

Internal automatic entries occur between applications using the same database (or within the same application).

The automatic entry sends information from the originating ispec or report to the database via the database record buffer of the target ispec.

External Automatic Entries

External automatic entries occur between applications using different databases. The target application must have an ispec identical to that specified by the originating application, sharing the same attributes, and in the same order.

External automatic entries can be used to interface to an external system, using the NOF or USER interface methods. Refer to the Agile Business Suite Runtime for Windows® Operating System Administration Guide for your host type for more information.

Automatic Entry Processing

The target ispec must be an automatic entry ispec (its Auto Entry Capable property is set to true).

Note: An external-only ispec (its External Only property is set to true) is inherently an automatic entry ispec.

The data object used to pass information to the target application is specified as an instance of the target ispec as a non-persistent ispec attribute of the originating segment.

To send an automatic entry, perform the following:

In logic:

Call the target ispec's Initialize built-in method to clear it.
Set the members of the target ispec to the required values.
For members of the target ispec that are not given a value by an explicit assignment statement:
- For new records, any members omitted are set to zero (for number-primitive variables) or a space character.
- For existing records being modified, any members omitted retain their existing values. However, if the member's Clear When property is set to zero (for number-primitive variables) or a space character, the value is set to zero or a space character, as appropriate.
Specify the target application by setting one or more of the following built-in segment attributes:
- Glb.Destination to the destination database; it is set by default to Glb.Self.
- Glb.DestHost to the destination host; it is set by default to Glb.SelfHost.
- Glb.DestEnv to the destination environment; it is set by default to Glb.SelfEnv.
To specify an internal automatic entry, set the Glb.Destination built-in segment attribute to Glb.Spaces or Glb.Self and the Glb.DestHost built-in segment attribute to Glb.Spaces or Glb.SelfHost.
Call the target ispec's Store built-in method to send the automatic entry. Refer to Store for more information.
If the target ispec has at least one attribute set as a key, the Maint built-in attribute value should be passed as a parameter to Store.

Internal Automatic Entry Processing

For internal automatic entries, no transaction processing of the target ispec occurs. The database is updated immediately with the information.

External Automatic Entry Processing

For external automatic entries:

After the automatic entry is sent, the originating application is suspended while waiting for a response from the automatic entry.
The target application receives the automatic entry in the input buffer and processes the information as normal client input. All phases of the segment cycle , except for the Construct method, are performed for the target ispec.
The Glb.Origin, Glb.OriginHost, and Glb.OriginEnv built-in segment attributes can be used to identify the source of the transaction.
Whilst the target ispec is processed, a recall of a different ispec (using the Recall logic command) is ignored. A recall of the same ispec causes a reply to be returned to the originating application. Otherwise, a simple acknowledgment is returned, indicating that processing is complete. If the Glb.Error built-in segment attribute is set to “*****”, only an error acknowledgement is returned upon completion.
The originating application receives the response and the reply can be determined from the values of the members of the targeted ispec.
The Glb.Status and Glb.HubStatus built-in segment attributes can be used to identify the result of processing the message. Refer to Glb.Status and Glb.HubStatus Settings for more information on the values returned to Glb.Status and Glb.HubStatus.
The Auto Write & Clear command only clears the automatic entry buffer if no data is returned to the buffer, in which case it clears the buffer regardless of the Glb.Error built-in segment attribute value. However, if data is returned, the Auto Write & Clear logic command behaves identically to the Auto Write command.

Failure Behavior

An automatic entry is rejected if:

The Maint built-in attribute value is passed to the Store method as ADD, and the record already exists in the target database.
The Maint built-in attribute value is passed to the Store method as CHG or DEL, and the record does not exist in the target database.

Refer to Glb.Status and Glb.HubStatus Settings for more information on failure behaviour.

Data Truncation

If a mixed string and wide string value is input to a wide string-primitive variable, the value is moved character-by-character, and truncated to the length of the variable.

If a mixed string and wide string value is input to a string-primitive variable, the value is moved byte-by-byte, and truncated to the length of the variable. This truncation might occur after the first byte of a double-byte character, resulting in an invalid character. However, truncation does not occur when moving these values into a wide string array variable.

Automatic Entry Restrictions

The following restrictions also apply to the use of automatic entries:

They are not valid in Edit methods of copy ispecs.
Signed number-primitive variables are corrupted if passed in an external automatic entry to an application deployed to a platform with a different character set, that is, between EBCDIC (applications deployed to MCP) and ASCII (applications deployed to UNIX, Windows® , or OS 2200).
Only the values ADD, CHG, and DEL can be passed as parameters to the Store method. The Glb.Status built-in segment attribute is set to “*****” when the automatic entry is sent if any other value, such as PUR, is passed.
A signed number-primitive value cannot be transferred between different host platforms. To transfer a signed value between applications deployed to different host platforms, specify a separate variable for the sign, and transfer the absolute value.
A string value cannot be transferred to an unsigned number-primitive variable with decimals (or vice versa).
A string value cannot be transferred to a signed number-primitive variable (or vice versa).
A number value cannot be transferred to a wide string-primitive variable (or vice versa).
Number array variables are implemented as COBOL COMPUTATIONAL fields. Moving a number array to anything other than an identically defined number array might result in data that is invalid for use in either computation or display.

Numeric Arrays

Numeric arrays are stored in COMP data format, which is different from how string arrays are stored (as string values).

To calculate the required size for the receiving attribute to store an incoming numeric array:

Allow one byte for every two digits.
Add half a byte for each array element, rounded up to the nearest byte.
For example, an array with ten elements, each three digits in length, would be calculated as:
```
((10 * 3) / 2 + (0.5 * 10)) := 20 
```

Graphical Interface Workbench

If a Graphical Interface Workbench interface is used to view the output from copy ispecs that contain external automatic entries, the automatic entry buffer that holds the information from the external automatic entry is also used for the video output items for the copy ispec for the Graphical Interface Workbench interface. This can result in corrupted data on the output screen.

To avoid this, when coding copy ispecs to use automatic entries for Graphical Interface Workbench-type interfaces:

Code any Initialize method calls before setting up any display fields on the screen. The BEGIN.EDIT logic command can be used to help do this. Refer to Segment Cycle for Copy.From Ispecs in the Enterprise Application Host Builder Guide and BEGIN.EDIT and End.EDIT later in this section for more information.
Store the fields in the automatic entry buffer immediately into SDs or GSDs, by using the Move.ARRAY; command. This prevents the fields from being initialized on each copy cycle, being overwritten by other external Automatic Entries, or being overwritten by setting up display fields on the screen.
Reference the SD or GSD, rather than using the Move.ARRAY; command, in the Ispec user logic.

Automatic Entry Example

This example in the logic of a report calculates each customer's bank balance and makes internal automatic entries updating the interest amount. It also makes an external automatic entry to the database of a different application if the customer is unemployed.

LookUp Every Cust : Iterate through every customer
 Determine Total Deposits (Cust.Customer) Amount : Determine the total amount
 : of the customer’s deposits
 Glb.Total := Glb.Total * Cust.Interest : Calculate the interest
 SD_Interest := "Interest" : Give a description
 Deposit.Initialize()
 Deposit.SetMaint("CHG")
 Deposit.Customer := Cust.Customer
 Deposit.Amount := Glb.Total
 Deposit.Narration := SD_Interest
 Deposit.Store() : Store in Deposit database table
 Deposit.Initialize() : Clear the Deposit buffer values
 : Logic
 Journal.Initialize()
 Journal.SetMaint("ADD")
 Journal.Ledger := SD_Interest
 Journal.Amount := Glb.Total
 Journal.Amount.Contra()
 Journal.Store() : Store in Journal database table
 Journal.Initialize() : Clear the Journal buffer values
 DoWhen Cust.EType = "N" : For unemployed customers
 Glb.Destination := "EmployDB" : The interest amount is sent to
 Deposit.Initialize() : the Employ application
 Deposit.SetMaint("ADD")
 Deposit.External(true) : (running against EmplyDB)
 Deposit.Customer := Cust.Customer
 Deposit.Amount := Glb.Total
 Deposit.Narration := SD_Interest
 Deposit.Store()
 Deposit.Initialize()
 DoWhen Glb.Status = "NOEXT" : Check external automatic entry
 Message Error "External application not identified"
 EndExit
 Glb.Destination := Glb.Self : Reset Glb.Destination
 End