The Type 3 Interface is also known as the Developer's Kit. It is an Licensed add-on product to ActionWare that includes sample programs and the following instructions:
ActionWare provides the ability to add/update information to a database through an interactive program. Usually, you will directly key the necessary information. However, some data elements can require editing or default input to supplement the interaction. In addition, data you enter can need to be passed on to another database or application area. The standard ActionWare maintenance program provides an automatic exit to an external program that can provide default data entry, editing, data transfer and other services.
USR100 Program and Subsidiaries:
The USR100 Program and its subsidiary sub-program examples, provided as part of this product, enable the development of these functional enhancements to ActionWare. These programs, referred to as the Maintenance Cycle Interface, include routines for the dynamic extraction of data elements from the ActionWare record and eliminates the need for recompiling every time an adjustment is made to the ActionWare record layout (a regeneration).
ActionWare does not require this dynamic extraction technique. However, when used in the USR100 programs, it offers protection against program failure when a recompile is not performed in a timely manner.
Group Jobs Menu:
ActionWare includes a Group Jobs Menu that can be accessed through the use of the attention key. This menu allows the user to:
Initiate parallel functions as group jobs.
Switch from one function to another by attention key and menu option.
This function switch is insulated against any involuntary data transfer between the functions and insures that the Group Jobs are effectively autonomous in their activities.
The starting point for data entry and inquiry functions is the identification of the customer or vendor to whom the transaction will be linked. ActionWare provides an ideal entry point for this process. When the correct business entity is located and displayed within ActionWare, another user exit can be invoked to switch control directly to the required application program. In addition, the master data within ActionWare can be immediately accessed for use in the application program.
A customizable version of the Group Jobs Menu provides initial guidance to the user for this control switch. Fast path capability is also available to allow an expert user to use only two keystrokes to effect the program switch.
USR200 Program and Subsidiaries:
The USR200 Program, and its supplementary program and sub-program examples, facilitates the development of these functional enhancements to ActionWare. This program is referred to as the Application Program Switch Interface. The programs include maintenance capability for files that provide a parameter driven implementation of this program control switch.
The Business Entity Identifier is used to link the ActionWare data record with the target application display. The Business Entity Identifier can be any field defined in the ActionWare data record. The same dynamic extraction technique used in the Maintenance Cycle Interface (USR100) is also used in the USR200 program.
Successful achievement of this Program Control Switch depends upon the ability of the target application program to accept a parameter list containing the Business Entity Identifier. The speed of program switching depends on not having to load application programs each time the switch is requested. The ActionWare and iSeries (AS/400) Group Jobs capability allows multiple application programs to co-exist within the single overall session. However, no matter how many application programs have been switched on, only one application is active at any given time. Each time a program is entered, time is saved because the user does not wait for the application to open files, etc. Productivity is increased by the time saved.
MAINTENANCE CYCLE INTERFACE
USR100 General Features:
ActionWare maintenance program detects a request by the user to add, change or delete a data base record.
After the user has keyed the data changes, ActionWare calls the external USR100 Program.
he requested action, the primary and secondary identities (PID and SID), and the contents of the modified record are passed to USR100 as elements of a parameter list.
USR100 returns a completion code or an error/information code. An error return code can instruct ActionWare not to update the record until the input error is corrected.
This USR100 program receives the parameter list and calls up to four sub-programs. Each sub-program is tested to ascertain its existence. The sub-programs are: USR110, USR120, USR130, USR140,
This same parameter list is passed to each sub-program. Cumulative changes to the data therein can be achieved if appropriate to the application requirements. The actual functions performed in the sub-programs depend on particular implementation requirements. In allocating functions to programs, it is preferable to keep each program as simple as possible. This will reduce development costs and facilitate program testing.
USR110
Performing basic editing.
Executing default replacement of keyed data.
Providing maintenance logging.
Capturing an unchanged data base record by reading key fields in an ActionWare record.
USR120
Capturing ActionWare data record as keyed and updated by USR110.
Transmitting captured record to another application.
Maintaining captured record for maintenance against supplementary data base files.
USR130
Performing any other functions associated with the final version of ActionWare before passing control back to the main ActionWare maintenance program.
USR140
Performing any other functions associated with the final version of ActionWare before passing control back to the main ActionWare maintenance program.
To enhance the flexibility of this interface in recognizing changes to the ActionWare data record, without major changes to the interface programs, the interface uses a mapping parameter file to relate the ActionWare data fields to other application database fields. A maintenance program for this mapping file is provided, as well as a control data area for multiple data file maintenance options.
ActionWare Record Update Flow: This section will identify the flow of automatic edits and calls to external programs that are made when ActionWare contact records are added or changed using ADD or CHANGE. Details on exactly how the ActionWare automatic PID/SID calculation operates plus a list of recognized field abbreviations used in the automatic calculation follows:
ADD New Contact Record Interactively
User presses Enter.
Complete standard edits.
Change Record Interactively:
User presses Enter.
Complete standard edits.
Automatic PID/SID Calculation Routine: The new automatic PID/SID calculation routine provides for a standardized Primary ID and Secondary ID for added or changed records. The following assumptions are made by this automatic routine:
If Primary ID (PID) is blank, use Company Name (COM) to calculate a new PID.
PID/SID Omit Words & Abbreviation List:
For these lists see related topic:
APPLICATION PROGRAM SWITCH INTERFACE
USR200 General Features:
The main ActionWare maintenance program recognizes the entry of the character "X" as a request to switch to another program. The program USR200 is invoked to execute this switch request. Upon execution, the current ActionWare record is passed as a parameter to the USR200 program.
USR200 locates the ActionWare field that contains the identity number that will be used by the target application program. The identity number is passed as a parameter, along with other specified data stored in the AW record, to the application program.
The current ActionWare record continues to be displayed while USR200 requests a single input character. You can key in an option number that corresponds to a previously set option list. The option list is controlled either by the individual user profile name or a group profile name. The option number, 1 though 8, causes the execution of the appropriate target application program. The target application program acts as a group job.
As an alternative, press the Enter key and a group jobs menu will be displayed with a list of the selection options. Choose the desired option from the list to invoke the desired program.
Flexibility: To improve the flexibility of the program switch function, three additional files are provided along with a maintenance program for each file.
A table file of all Interactive application programs available for the user to request program switch access. The file also defines the particular identity parameters that must be passed to the other application program. These application field names can be up to two parameters per program
A mapping parameter file that defines the relationship between ActionWare field names and other application field names.
A table file of program switch menu options, by user or group profile. It is used to control the program switch function described above.
Note: A maintenance program is provided for each of these additional fields. The interactive program file and the mapping file may require modification. This will depend upon the other application that is interfaced. The display files and maintenance programs for these two files will need changing also. The option list program should only need to be recompiled.
INTERFACE PROGRAM STRUCTURE
General Features:
The USR100 program, which is called directly by the main ActionWare maintenance program, is written in iSeries (AS/400) Control Language. It acts as a conduit between ActionWare and up to 4 user defined sub-programs. Existence checks within this program ensure that no call is made to a non-existent program. When all program calls have been completed, control is passed back to the calling ActionWare maintenance program.
USR100 Interface Parameters: The full definition of the parameter list passed to this program and the possible return code values are defined as follows:
|
Param 1: |
10 |
AW>USR: |
Primary ID of the Original Record |
|
Param 2: |
10 |
AW>USR: |
Secondary ID of the Original Record |
|
Note: If the PID or SID was changed by the user, the record image can contain a different PID/SID. For Delete, PID in the image will contain "DeleteXXXX". For Add, the above fields will contain the PDI/SID of the "Based On" record, or the record from which an Add Blank was requested. |
|||
|
Param 3: |
1 |
USR>AW: |
Return Code from User Program |
|
0= |
Continue. Image can have been changed. |
||
|
1= |
An error was detected and a message was sent to ActionWare message queue. ActionWare will remain in ADD or CHANGE mode with the user's message displayed at the bottom of the screen. |
||
|
2= |
An error was detected but no message was sent to ActionWare. ActionWare will remain in ADD/CHANGE mode with a generic error message displayed at the bottom of the screen. |
||
|
3= |
Continue. Image can have been changed. Same as 0 except, additionally, the main program will display any messages sent to its program message queue. |
||
|
9= |
Cancel Add/Change mode, ActionWare proceeds as if the user had pressed F12. |
||
|
X= |
Any other value. ActionWare behaves as if the return code was "2" |
||
|
Param 4: |
1 |
AW>USR: |
ActionWare action which initiated this: |
|
A= |
ADD |
||
|
C= |
CHANGE, PID/SID was not changed |
||
|
K= |
CHANGE, PID/SID was changed |
||
|
D= |
DELETE |
||
|
O= |
OVERLAY |
||
|
P= |
PROPAGATE |
||
|
Param 5: |
1 |
AW>USR: |
Action qualifier. |
|
For A = ADD |
A = Above |
||
|
For C = Change |
C = Normal |
||
|
For D = Delete |
None |
||
|
For O = Overlay |
D = Delete |
||
|
For P = Propagate |
K = Key Field Change (PID or SID) |
||
|
Param 6: |
6144 |
Both |
|
|
This is the contact record image immediately prior to the ADD/CHANGE write to disk. The user can map this with an externally defined data structure. User PGM will require a recompile after a regen. Alternatively, user can use DDAT, which does not require a recompile. |
|||
|
Note: The remaining parameters are used for Return Codes 1 and 2 only. They provide supplementary information when the user program returns an error status back to ActionWare. |
|||
|
Param 7: |
1 |
USR>AW: |
Panel Number |
|
'0' through '3' which the user program wants AW to display, along with the error. |
|||
|
Param 8: |
3.0 |
USR>AW: |
Row Number |
|
Where the user program wants AW to position the cursor when an error occurs. |
|||
|
Param 9: |
3.0 |
USR>AW: |
Column Number |
|
Where the user program wants AW to position the cursor when an error occurs. |
|||
|
Note: PID and SID are saved before the call to USR100. |
|||
For ADD:
A user generated PID/SID is allowed, but the combination cannot be a duplicate of an existing contact record. ActionWare checks to ensure the user program has not generated a duplicate. If the error is found, ActionWare reports it.
To change PID or SID, the user program must change the data within the image string. It must not change the two discreet parameter fields. PID and SID are always at positions 1 - 10 and 11 - 20 within the record image string.
This processing is done to ensure the integrity of the database.
For Actions Other Than ADD:
ActionWare checks for duplicates upon the return from USR100, to ensure database integrity. Although we strongly recommend against it, you can change the PID/SID in the program.
Additional Considerations for Overlay or Propagate:
It is recommended that the user program never generate a message to the program message queue. E.g., even in the case of the Code 1 return below, where this return would normally be used after issuing a message. The following are the only recommended returns:
0 = Continue Processing, update the current record.
1 = The current record will not be updated. Overlay or propagate processing will continue
9 = Cancel the Overlay or propagate request.
Note: If access is from the overlay or propagate function, a return code from your program of 0 or 3 will cause the overlay or propagate to occur. A return of 9 will cancel the overlay or propagate immediately. Any other return code will bypass the change to the current record only. Do not send a message to the calling program for overlay or propagate.
ActionWare Interface Code in the Direct Area of the Call:
|
*Like |
Defn |
PID |
SR65P |
|||
|
*Like |
Defn |
SID |
SR65S |
|||
|
MoveL |
PID |
PIDA |
||||
|
MoveL |
SID |
SIDA |
||||
|
Call |
"USR100" |
21 |
||||
|
PARM |
PIDL |
SR65P |
||||
|
PARM |
SIDL |
SR65S |
||||
|
PARM |
'0' |
WRK440 |
Return Code |
|||
|
PARM |
SR65A |
1 |
User Action |
|||
|
PARM |
SR65Q |
1 |
Qualifier |
|||
|
PARM |
CUW |
Cust Image |
||||
|
PARM |
'0' |
FNPANL |
1 |
Error Panel |
||
|
PARM |
0 |
FNROW |
Error Row |
|||
|
PARM |
0 |
FNCOL |
Error Column |
Program List - Control Language Programs
ADDTE Add parameter number of days to parameter date. This program accepts a date in *ISO format and adds or subtracts a number of days to it, returning the adjusted date. The parameter number of days can be positive or negative.
AM352C This is a sample program that calls AM352, the activity add API. It documents the parameters required. You can use this Control Language Program, modifying the program parameters passed to it, to include those you wish to prefill for the RPG program. You can also call the RPG program directly.
CHKDTE This program takes a date in local format (MMDDYY or DDMMYY, etc.) and converts it to *ISO format, validating it before returning. It is used in the sample USR110 program.
DOWEEK This program takes a date in *ISO format and calculates its day of the week, and week of the month.
GJ0 This is a modified version of the group jobs program that AW uses. It simply calls USR200.
MODIFY2 This program is called at the end of a regen stream. It is intended to be used to compile any user-created logical files, screens and programs that are dependent upon the CUST file. This program should be compiled into AW4L library.
AWMADD A Control Language Program that can be called within a program to send a message from that program to the program message queue. It can be used in programs within this interface.
USR100 This program is the main exit from AW during an add or update. It checks for the existence of four sub-programs and calls them. After each, it checks the error indicator and, if on, exits.
USR200C1 This Control Language Program is called if the user selects options 1 through 8 on the task switch menu. It retrieves the information about the option chosen from the GDA (group jobs data area) and calls the program indicated. Upon return from that program, it transfers to the ActionWare group job.
Program List - Report Program Generator
CMMNT This is a sample of an asynchronous update program. Its main routine is a loop that first executes a subroutine to receive data from a data queue. It waits there until it receives the data, then checks to see if the first character is an asterisk. If the first character is an asterisk, the routine ends. To end the program, send an asterisk to its data queue.
If it is not an asterisk, the update routine is performed. The program checks to see if a record already exists. If so, it updates the record with the new information from AW. If a record does not exist, it adds a record.
This is a sample program and will need to be modified to include coding for a specific application.
USR110 This sample program determines the record layout. Next, it edits any phone numbers, dates, and zip codes. Then it calculates the PID/SID. If an error code is invoked at any step, the program will end.
USR120 This sample program first retrieves the name and key field information from the XMAP file (maintained in the XMAPMT program) for up to three files, and performs an update subroutine for each.
In the sample, if the file CMP is to be maintained, the subroutine SRCMP is performed. This subroutine extracts the data from the record string, and reads through the map file to determine which fields are to be updated, and which fields are required to be filled in by the user. If a required field is blank, a line on an audit report is written.
Next, the extracted data is moved to the mapped field. The program (1) calls an update program and passes the data structure as a parameter; or (2) sends the data to a data queue. When data is sent to the data queue, a maintenance program that runs asynchronously waits for a record to be written to the data queue. The actual update occurs independent from the user's response time.
This program is heavily dependent upon the specific application involved, and although the structure of the program should not need modification, the specific fields and files involved will need adaptation to meet the target application's requirements.
USR200 The USR200 program is provided only in object form for licensing reasons. It is a simple program that calls several sub-programs to achieve the inter-application program switch functions. All the sub-programs are either modified versions of the standard ActionWare programs, or are new programs supplied in source form. Sub-programs include program USR210 which extracts the user's option list from the option file; program USR200C1 which handles program switching to one of the eight possible listed options; and, program GJ0 which is a replacement for the standard ActionWare attention key program and calls USR200 for full user interface capability.
USR210 This sample program retrieves the interface menu options from the options by user (XOPT) file so that the group jobs menu can be constructed. It also stores the parameter details for each target application program to permit faster program switching, once the user has selected the menu option.
Dynamic Extraction of ActionWare Data Elements
The program examples provided in this product use a dynamic technique for the extraction of data elements from the ActionWare contact record. Since the ActionWare record layout is variable, with field name, field size and field sequence determined by the controlling user, some exposure exists in not correctly locating data elements required for update or extraction purposes.
This problem can be minimized through the use of an externally defined data structure, and by re-compiling the user exit programs every time ActionWare regeneration is performed.
An alternative extraction method is provided in this product. Use the contents of the field definition file (which controls the ActionWare regeneration process)
to identify the starting position for the desired field and its length and then use array processing techniques to extract the data value. Since this technique does not rely on an external file definition to dissect the ActionWare record, it is unnecessary to re-compile programs when regeneration is performed. However, if the main ActionWare file is accessed directly by a program, for logging of data changes or similar reasons, then re-compilation of that program must be performed after any regeneration. This technique is also valuable for those with multiple AW databases, which can be slightly different. The same program can be used with both AW databases.
OPERATION INSTRUCTIONS
To ensure that the appropriate exit processing occurs, all user exit programs and sub-programs must be compiled into object form, and be accessible through the current library list when the main ActionWare program is used. ActionWare uses a data area (called LIBAUX) to identify one or more auxiliary libraries in which these programs can be found. When setting up the standard ActionWare product, enter the name(s) of the auxiliary library(ies) into the data area.
The exit program execution should otherwise be transparent to the user. If error messages are to be returned to ActionWare from one of the exit programs, the user should be provided with documentation to explain the meaning of the message, and suggest the corrective steps to complete the required activity.
INSTALLATION AND IMPLEMENTATION
All user exit programs and sub-program examples (except USR200) are provided in source form. USR100 and the USR200 programs only are provided in compiled object form. All components are contained in the library AW4AUX2, which can be restored and then renamed as required.
It should not be necessary to make any changes to the USR100 program, since it only calls the sub-programs, and performs no discretionary logical functions.
The USR110 program can need to be modified, as it is intended to be samples of edits that can be performed. You can not need all of them or you can wish to add edits of your own. If you accept the standard PID/SID calculation, you can remove the PID/SID creation routine.
If the mapping file concept is going to be used to translate ActionWare field data into other application database fields, then the mapping file will need to be set up. It is suggested that when you have determined all fields that should be in the mapping file, these should be entered using DFU or a similar utility program. They only need to be added once. The equivalent ActionWare fields can be entered using the Mapping file maintenance program. Some changes can be necessary to the USR100 sub-programs if unusual field requirements exist for the other application database.
To design and implement one or more of the sub-programs to be called by USR100, it is necessary to list the functions to be performed for each complete ActionWare maintenance cycle. The functions should be organized into:
Edit checks that cause a pause or cancellation in the maintenance cycle; and,
Updates, either of other fields in the ActionWare record or in other databases or applications.
The edit check functions should be included in the USR110 program, so that they are performed first. If this program finds a problem that requires further user interaction, a return code of '1' will cause an immediate return through USR100 back to the main ActionWare program. An error message can be displayed to the user indicating the problem, and the desired cursor position can be communicated. Another iteration of the user exit cycle will allow re-editing of the ActionWare record before control passes on to the next program.
Update or data extract functions should be included in the USR120, USR130 or USR140 sub-programs. Normally, these programs will not cause the maintenance cycle to stop, although the use of the same return code value ('1'), will cause an immediate return to ActionWare. Reversing updates or data extractions late in the cycle is difficult and can be error prone.
Extra Cautions
Finally, be careful not to have any other programs with the names USR110, USR120, USR130 or USR140, accessible through the current library list. If the USR100 program can find such a program, it will call it. Parameter list mismatches or program logic errors can cause unexpected failure of the ActionWare maintenance cycle.
For the application program switch functions, it will be necessary to determine what programs can be called in the other application. For each program, the required parameter list fields must be entered into the interactive program file.
Some modification of this program can need to be performed if unusual requirements exist in the other application. Where database interfacing is also being implemented, the mapping file will probably already contain the ActionWare and other application field links required for the resolution of parameter field values. If not, these links must be entered, or the program must be modified to handle the parameters correctly.