The information in this section is provided "as is" for technical personnel only, ActionWare billable services are available to assist you with your custom programs.
For more information see related topic:
USR100 INTERFACE PROGRAMS
USR100 is an optional user written program that can perform additional functions whenever an ActionWare user adds, changes or deletes a contact record. Additionally, USR100 can be called when a record is updated as the result of a PROPAGATE or an OVERLAY. System Option #48, (USR100 P=propagate O=overlay Y=both N=neither) is used to determine if USR100 gets called for either or both or neither.
USR100 must have 9 parameters defined. Their use, type and length, are described below. The PID and SID passed to USR100 is exactly as it is on the screen. Immediately on pressing enter, PID and SID are validated if either field contains an entry, but not if both are blank. The SID is considered blank if it contains only the record type id of two periods or two slashes. The main program AM015 then makes an independent determination of either key field being changed, and if so, drops into the type "K" USR100 routine.
The data in the record image passed to USR100 is now exactly as per what is on the screen. The program continues to make the determination as to whether or not the PID or SID was changed by the USR100 routine, and if so it loops back for a re-edit. When it gets to this point for the second time, it bypasses the call to USR100, and continues on to validate PID and SID for containing legal data. If either is blank, it will be calculated at this point. It is possible the recalculation will generate what was there originally. So we make a final determination as to whether or not the current PID/SID is different than it was originally, and if it is different, it goes on to make a duplicate check, and if it passes that test it proceeds to change the PID/SID in other files (eg TRAN) as before.
Sample Program: AW4/QMODSRC is distributed with an example USR100 program, along with an associated display format source member USR100FM. This USR100 is an example of an interactive program that gets control whenever a ActionWare user adds, changes or deletes a contact record.
To see how the USR100 interface works, compile display file USR100FM and program USR100 distributed in AW4/QMODSRC. Note:- be sure to compile these into library AW4L or your test library. Then enter ActionWare normally.
When you Add or Change contact records, you will be presented with an extra screen from the USR100 test program. You can view and or work with the parameter data supplied to observe how ActionWare reacts to various types of input from a USR100 program. The USR100 program which you will write will be presented with data in the form you see, and must return data to ActionWare according the rules below. When finished with this exercise, delete program USR100 and the USR100FM display file. Note: Activities should not be created except by using a special Activity API (USR600).
USR100 PARAMETERS:
|
Param 1: |
10 |
AW>USR: |
Primary Id Of The Original Record |
|
Param 2: |
10 |
AW>USR: |
Secondary Id Of The Original Record |
|
Note that if the PID or SID has been changed by the user, the record image may contain a different PID/SID. For delete, PID in the image will contain "DELETExxxx". For add, the above fields will contain the PID/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 = 1 =
2 =
3 =
9 = X = |
Continue. Image may have been changed. An error was detected, and a message was sent to the AW program's message queue. ActionWare will remain in add or change mode, with the user's message displayed at the bottom of the screen. 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. Continue. Image may have been changed. Same as 0 but additionally, the main program will display any messages sent to it's program message queue. Cancel add/change mode, aw proceeds as if the user had pressed F12. Any other value. AW behaves as if the return code were "2" |
||
|
Param 4: |
1 |
AW>USR: |
ActionWare action which initiated this |
|
A = C = K = D = N = O = P = S = |
Add Change, PID/SID not changed by the User. Change, PID/SID was changed by the User. Delete Notepad Statistic Overlay Propagate Script |
||
|
Param 5: |
1 |
AW>USR: |
Action Qualifier. |
|
K = |
FOR A=ADD:
FOR C=CHANGE OR K=CHANGE:
FOR D=DELETE:
FOR N=NOTEPAD STATISTICS:
FOR O=OVERLAY: |
||
|
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), or use ddat, in which case no recompile is needed. |
|
The remaining parameters are used for return codes 1 & 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' thru '6' which the user program wants aw to display along with the error. This will normally be determined from file "FIELG" |
|
Param 8: |
3.0 |
USR>AW: |
Row number where the user program wants aw to position the cursor when an error occurs. This will normally be determined from file "FIELG" |
|
Param 9: |
3.0 |
USR>AW: |
Column number where the user program wants AW to position the cursor when an error occurs. This will normally be determined from file "FIELG" |
CONSIDERATIONS FOR GENERATING OR CHANGING PID OR SID.
A user generated PID/SID is ok, but the combination cannot be a duplicate of an existing contact record. ActionWare checks to ensure the user program has not generated a duplicate, and reports the error if found. To change PID or SID, the user program must change the data within the image string, not the 2 discreet parameter fields. PID and SID are always at positions 1-10 and 11-20 within the record image string. If you change PID or SID, ActionWare will, after validation, change them in the contact record (file "CUST"), and in the notepad and activity files.
ADDITIONAL CONSIDERATIONS FOR OVERLAY OR PROPAGATE, it is recommended that the user program never generate a message to the program message queue, eg 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 contact record
1 = The current contact record will not be updated but Overlay or Propagate processing will continue
9 = Cancel the Overlay or Propagate request
Note that 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.
ADVANCED USR100 TOPICS
Despite inferences to the contrary, ActionWare does not directly call the USR100 program. Instead, it is called via an interceptor CL program AM100C. This interceptor program is normally transparent to the USR100 programmer.
The number of parameters passed from ActionWare to the interceptor program is greater than the 9 documented above which are passed from the interceptor program to USR100. This allows the ActionWare development team to change the first level interface, but to maintain a consistent second level interface (as documented above) to the USR100 program.
In the situation where the USR100 program needs more information than is provided by the standard interface, the USR100 programmer may need to change the interceptor program directly. The source code for CL program AM100C can be retrieved using command RTVCLSRC. You must specify the library as AW4. We cannot guarantee that the interface to program AM100C will not change from one version to another, or even from one level to another. This aspect of the USR100 interface is provided as a convenience for those needing it, the penalty for this is the risk that your customized interface may need changing when you upgrade ActionWare. Some of the additional fields available are:
|
Param TRAID: |
`11.0 |
AW>USR: |
ID of the "current" activity. If Zero,there is no current activity. Logical file tran41 is keyed on activity id, use the data in this field to access the activity record in your program. |
|
Param TPAID: |
`11.0 |
AW>USR: |
id of the activity used or created by Dial or take call. Valid only up to the point where a hangup is done. If zero, we do not have a phone call in progress. At the point where hangup is done, this field will already be zero, and the required activity is identified by the previous parameter. Logical file tran41 is keyed on activity id, use the data in this field to access the activity record in your program. |
Creating Activities in USR100: If your user exit requirement is to create activities as a result of a user action, please refer to the Activity API document for more information. Activities should not be created except by using the Activity API.
USR600 INTERFACE PROGRAM
Because of the complexity of the activity structure, this interface is conceptually different to the USR100 interface. It does not give the degree of control that the USR100 interface gives to the programmer.
The call to USR600 is immediately after the output operation for an activity add or change, and immediately before for a delete. The user program can in no way influence the action, or report back errors, it is simply informed of what is happening. It is passed the id of the activity (field TRAID), and some other basic information (see the parameter list below), and enough information for it to determine what the ActionWare user was doing. No other record information is made available. If it needs data, it has to read it from a logical, say TRAN41. It may also need to access earlier versions of the record in the archive file ACTH.
ActionWare determines on the first call (to each program in the list below) if the USR600 program exists or not, so subsequent calls are not made.
It is not expected that the user program will make changes to the activity file as a result of the interface call, but instead would use the information to inform their own application of what ActionWare has just done. Any change made to any ActionWare file by any external process, whether it originates from any ActionWare interface or is completely independent of ActionWare, is outside of the scope of our standard support agreement.
As with any external interface exit, we do not undertake to maintain compatibility with this interface in subsequent releases of the product. We will endeavor to do so, but if in future changes to this interface are deemed to be necessary, we will attempt to implement those changes according to standard practices for such interfaces as defined by IBM.
If your user exit requirement is to create activities as a result of a user action, please refer to the Activity API document for more information. Activities should not be created or added to ActionWare except by using the Activity API.
Demonstration:
A demonstration of the USR600 facility can be achieved by compiling display file USR600FM and CL program USR600 from ActionWare library AW4/QMODSRC (not AW4L) into your database library, normally this will be library AW4L.
This test program can also be very useful to a programmer developing their own USR600 program. It provides an easy way to see what data is provided under what circumstances.
When finished the demonstration or test, simply delete program USR600 from the database library.
Parameters
All parameters are input only parameters to program USR600.
|
Param 1: |
11.0 |
AID (Activity Id) of the activity involved. |
|
Param 2: |
3,0 |
Version of the activity involved. |
|
Param 3: |
1,A |
Return code, not currently used. |
|
Param 4: |
10,A |
Name of program issuing the call. |
|
Param 5: |
1,A |
Action being taken. A=add new record, C=change existing record, D=delete. (Records can be deleted by the UNDO function.) |
|
Param 6: |
1,A |
Action qualifier, a sequential letter A, B, C, etc which is unique within a given program to identify the exact ActionWare function being performed, |
|
Param 7: |
1,A |
Internal reserved field, do not use or change. |
|
Param 8: |
1,A |
Internal reserved field, do not use or change. |
|
Param 9: |
1,A |
Internal reserved field, do not use or change. |
Programs
This is a list of programs which perform a call to the USR600 interface.
AM340 Main Activity Add & change windows, small & large.
AM341 Work with related activities.
AM347 Retrieve next/prior activity from message list. Message List, 	status change only.
AM348 Change activity PID/SID after contact record change.
AM350 Automatic add/change after phone, wordprocessing, fax functions.
AM352 Add activity API
AM433 Message List, status change only.
AM452 Work with linked group window.
AM456 Campaign Management Activity Change.
AM459 Campaign Management Mass Mail Generation.