User Fields and User Functions

This document covers the following topics:

• Introduction

• User Exit Programming

• User Fields

• User Functions

• Displaying Delta Values

• Evaluation within a Time Frame

Introduction

ASF offers functionalities to define additionally data fields and to combine the reported data in new ways. These functions are performed by user-written routines called user exits.

There are 20 fields on the ASF Data record which can be filled by the user. These fields are named user fields. Before ASF stores a record on the ASF Data file, the user exit ASFUEXIT is called, where the user fields can be supplied with data. The same user exit is called at every evaluation before the data is displayed. The user exit can fill the user fields with data which is then displayed in the evaluation. In the user exit ASFUEXNA, names of the user fields can be defined.

The user exit ASFUEX01 offers user functions to alter the ASF data values displayed in any evaluation. The user exit can contain up to 20 user functions. Two functions are already coded as described in the sections Displaying Delta Values and Evaluation within a Time Frame. Each user function can be switched on and off in the ASF User Exit Maintenance or by direct commands. In the user exit ASFUEXN1, short descriptions of the user functions can be defined which are then displayed in the User Exit Maintenance.

User Exit Programming

The ASF user exits are Natural subprograms delivered in source and catalog format in the library SYSASF. The executable user exits are named ASFUEXxy; the delivered source members are named XXXUEXxy, in which xy identifies the user exit. The source name differs from the catalog name, so that new delivered sources do not overwrite members modified by the user.

The following ASF user exits are available:

If you want to modify a user exit, perform the following steps:

• Edit the XXXUEXxy subprogram in SYSASF and save it as ASFUEXxy.

• Do not modify XXXUEXxy! It will be overwritten whenever a new ASF release is installed.

• Edit ASFUEXxy and modify it as desired. Stow the modified subprogram.

You should not remove the executable user exit programs from the SYSASF library. ASF always expects to find them, otherwise it fails.

When a user exit (ASFUEXIT or ASFUEX01) is called, the ASF Data record is supplied as input parameter. The ASF Data record consists of three types of data:

• General data

• Database-related data

• File-related data

The ASF Store Program stores one record for a database and one record for each file. Thereby it supplies always the general data. This comprises the technical ASF fields like the store time, the user fields and the database Id and name. Database related data like High-Water-Marks, is only supplied if the FCB-FNR field contains 0, i.e. for a DB record. File related data like TOP-ISN is only supplied if the FCB-FNR field contains a value greater 0, i.e. for a file record. Note that for evaluations of type 1-4 only DB records, for evaluations of type 5-8 only file records, and for Critical Reports and Critical Trends (type 9 and 10) all records are processed.

The following table lists the most important fields of the ASF Data record (ASF-STAMM). The other fields are described in the "DEFINE DATA" statement of the ASF user exit delivered.

User Fields

There are 20 user fields in the ASF Data record, 10 alphanumeric and 10 numeric (packed) fields. The user exit ASFUEXIT is provided to fill these fields with data before ASF stores or displays a record.

This section covers the following topics:

• ASF User Exit ASFUEXIT

• ASF User Exit ASFUEXNA

• Example

ASF User Exit ASFUEXIT

The ASF user exit ASFUEXIT is a Natural subprogram which is delivered as source and object module on the SYSASF library. The delivered source is named XXXUEXIT.

The ASF user exit is called twice: once immediately before ASF stores a record, and a second time at the evaluation, when any user field is processed. Field values which are created at the evaluation time are named virtual fields, in contrary to real fields which are stored on the ASF data record. Real fields are saved permanently on the ASF file; virtual fields are only available during an evaluation.

When you run an evaluation accessing a real field, data is only supplied for records which have been stored after the user exit modification. Virtual fields can be viewed for any kind of data, even before the modification, because the value is calculated at evaluation time.

The delivered user exit initializes the user fields before the store, i.e. it fills the alphanumeric fields with blanks and sets the numeric fields to zero. At the evaluation, it copies the values from the real fields to the virtual fields, so that the values of the real fields are displayed.

When the ASF user exit ASFUEXIT gets control, the input parameters described below are supplied. Input parameters cannot be modified in the ASF user exit.

When the user-exit returns control, the output parameters described below are returned to ASF. The output parameters can be filled with any value, as long as the corresponding format is respected.

The input field #FIELD-NUMBER indicates why the user exit has been called. If the field has the value "0", the exit has been called immediately before ASF stores the data record, i.e. it is going to create a real field. The fields of the ASF Data record are supplied with their final values by ASF, except the user fields, which are still empty. When the user exit returns control to ASF and the response code is set to "0", all user fields in the DATA record will be overwritten by the corresponding user fields from the output parameters (#USER-FIELDS). If the response code is not equal to "0", the record will not be stored.

If the field #FIELD-NUMBER has a value greater then "0", the user-exit has been called during an evaluation, i.e. it is going to create a virtual field. All fields of the ASF Data record including the user-fields ("USER-FIELDS") are filled with their original stored values. The value of the field #FIELD-NUMBER indicates which user fields ASF is currently evaluating. The field numbers from 1 to 10 correspond to the alphanumeric fields; the field numbers from 11 to 20 correspond to the numeric fields.

The following table shows lists the ASF user fields as given at an evaluation:

For an evaluation, only 10 digits of a packed user-field are displayed, because one position is reserved for the sign.

When the user exit returns control to ASF and the response code is set to "0", the returned user field is used for the evaluation. If the response code is greater than "0", the original user-field from the ASF DATA record is used.

The following table lists the response codes of ASFUEXIT and their meaning at a store and at an evaluation:

Thus, for a store, all user fields are returned to ASF, whereas for an evaluation only one user field is returned, namely the one indicated in the field #FIELD-NUMBER.

Note:
The delivered user exit ASFUEX01 uses the user fields #USER-FIELD-A(1), #USER-FIELD-A(2), #USER-FIELD-A(3) and #USER-FIELD-A(10). See the section User Functions for more details.

ASF User Exit ASFUEXNA

The ASF user exit ASFUEXNA is a Natural subprogram which is delivered as source and object module on the SYSASF library. The delivered source is named XXXUEXNA.

The ASF user-exit ASFUEXNA defines the names of the user fields. The delivered program uses the names USER-FIELD-A(01) to USER-FIELD-A(10) for the alphanumeric fields and USER-FIELD-P(01) to USER-FIELD(10) for the packed fields. You can edit the user exit and overwrite the INIT-values of the #NAME variable in the DEFINE DATA area. The specified names are subsequently used when you create an evaluation profile and in every evaluation output.

It is recommended that you use only uppercase characters for the names. When you specify a field name at the evaluation profile maintenance, all characters are translated into upper case, and a field containing lower case characters is not found.

Do not use field names already used by ASF. The names of the ASF fields are outlined in the section ASF Group and Field Names in the ASF Examples documentation.

Example

We create a real ASF field containing a time-dependent value returned by the external subprogram ANYPROG. This program expects as input a date and a time, and returns as output a packed field of length 11.

Additionally we create a virtual field containing the sum of the commands in the threads 100 to 199.

First copy the Natural subprogram XXXUEXIT to ASFUEXIT, and XXXUEXNA to ASFUEXNA.

Edit ASFUEXNA and define names for both fields. In the DEFINE DATA area, replace the lines

           (11)  <'USER-FIELD-P(01)'>
           (12)  <'USER-FIELD-P(02)'>

with the lines

           (11)  <'SPECIAL VALUE   '>
           (12)  <'THREAD 100 - 199'>

Edit ASFUEXIT and add the following lines to the LOCAL DATA area:

 1 #DATE (A10)
 1 #TIME (A8)

Then replace the executable part of ASFUEXIT with the following:

  IF #FIELD-NUMBER = 0             /* before store
*
* Default: Initialize the user fields
*    FOR #I = 1 TO 10
      MOVE ' ' TO #USER-FIELD-A (#I)
      MOVE  0  TO #USER-FIELD-P (#I)
    END-FOR
*
* Define special field
*
    MOVE EDITED TIME (EM=DD.MM.YYYY) TO #DATUM
    MOVE EDITED TIME (EM=HH:II:SS)   TO #TIME
    CALL 'ANYPROG' #DATE #TIME #USER-FIELD-P(1)
*
  ELSE         /* before evaluation
*
* Default: Move input field to output field
*
    IF #FIELD-NUMBER <= 10         /* alpha field
      #I := #FIELD-NUMBER
      MOVE USER-FIELD-A (#I) TO #USER-FIELD-A (#I)
    ELSE                           /* numeric field
      #I := #FIELD-NUMBER - 10
      MOVE USER-FIELD-P (#I) TO #USER-FIELD-P (#I)
    END-IF
  END-IF
*
* Define virtual field for threads 100 - 199
*
  IF #FIELD-NUMBER = 12
    RESET #USER-FIELD-P (2)
    FOR #I = 100 TO 125        /* thread 100 - 125
      ADD THREAD-NR-CMDS-1 (#I) to #USER-FIELD-P (2)
    END-FOR
    FOR #I = 1 TO 74           /* thread 126 - 199
      ADD THREAD-NR-CMDS-2 (#I) to #USER-FIELD-P (2)
    END-FOR
  END-IF
*
* The store is performed, if #RSP=0.
* The value is used for evaluation, if #RSP=0.
*
  RESET #RSP #MSG                  /* reset response code and message
*
END

After we have cataloged both user exits, we start the ASF application. In the Main Menu, we select the code "E" (Evaluation Profile Administration) and then "A" or "M" to add a new Evaluation Profile or to modify an existing Evaluation Profile.

In the "Profile Element: Accumulation" screen, we press the PF5 key to display the "Active help: Select groups" screen. We mark the group "User defined fields" with "X". The "Active help: Select fields" screen is displayed. Here we see the field names that we have specified in the ASFUEXNA subprogram. We select the fields 'SPECIAL VALUE' and 'THREAD 100 - 199' and leave the active help with PF6.

When we run this evaluation, the 'SPECIAL VALUE' is supplied for all records that have been stored since we modified the user-exit. The (virtual) field 'THREAD 100 - 199' is displayed for all records, even if they were stored before the user-exit modification.

User Functions

The user exit 01 (default name: ASFUEX01) offers up to 20 user functions to alter the ASF data values displayed in any evaluation. Each user function can be switched on and off in the ASF User Exit Maintenance or by direct commands as described later in this section.

Two functions are already coded in ASFUEX01 as described in the sections Displaying Delta Values and Evaluation within a Time Frame. These functions can be used as they are but may also serve as samples how to code a user function.

In the user exit ASFUEXN1, the name of the user exit 01 can be altered and short descriptions of the user functions can be defined. These descriptions are listed in the User Exit Maintenance.

This section covers the following topics:

• User Exit Maintenance Menu

• Direct Commands

• ASF User Exit ASFUEX01

• ASF User Exit ASFUEXN1

User Exit Maintenance Menu

                                                                                
 11:04:27          *** A D A B A S  Statistics Facility ***          2008-02-01
 USERID                      - User Exit Maintenance -                  MUEX0001  
                                                                               
 Mk  Nr Description                      Mk  Nr Description                    
 --- -- ------------------------------   --- -- ------------------------------ 
  _   1 Delta values (End-Nuc=EN)         _  11 N/A                            
  _   2 Time frame: 12:00 to 18:00        _  12 N/A                            
  _   3 N/A                               _  13 N/A                            
  _   4 N/A                               _  14 N/A                            
  _   5 N/A                               _  15 N/A                            
  _   6 N/A                               _  16 N/A                            
  _   7 N/A                               _  17 N/A                            
  _   8 N/A                               _  18 N/A                            
  _   9 N/A                               _  19 N/A                            
  _  10 N/A                               _  20 N/A                            
                                                                               
 User Exit Name .........: ASFUEX01                                            
 User Exit Savearea .....: EN12001800______________________                    
 Savearea Layout ......... ENhhmmhhmm                                          
                                                                               
     Direct command ==> _______________________________________________________
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
      Help  More  Term  Off   On    Selct                               Menu

Figure 6-1: User Exit Maintenance menu

Purpose

This screen lists the user functions available. Selected user functions can be activated or deactivated and the name of the user exit 01 program can be altered. The value of the user exit save area can be modified.

Screen selection

This screen is reached

• by selecting the service code "X" in the ASF Utilities and Services menu;

• by typing the command "ASFUEX" in the direct command line of any screen

Description

The ASF User Exit Maintenance lists the user functions. You can activate a function by marking it with an "X" or any other non-blank character. The function itself is coded in the user exit 01 program as described in the section ASF User-Exit ASFUEX01. The short description of each function which is displayed on the screen can also be defined in a user exit as described in the section ASF User-Exit ASFUEXN1. The same section describes how to set the default name of the user exit 01 program and the initial value and layout of the user exit save area.

The ASF user exit 01 is called if at least one function in the User Exit Maintenance is marked with a non-blank value. The values of the marks are given to the user exit in the parameter data array #UEX (1:20).

If you want to use another program as user exit 01, you can overwrite the "User Exit Name" field. Make sure that your user exit 01 subprogram uses the same parameter data area as ASFUEX01, otherwise ASF will fail.

The sub-program ASFUEX01 is already delivered with two user functions coded. The function "Delta values" is described in the section Displaying Delta Values. The function "Time frame" is described in the section Evaluation within a Time Frame. Both functions use a part of the user exit save area. This is also described in the corresponding sections.

You can switch on (mark with "X") all functions of the ASF user exit 01 by pressing PF5, or switch off (mark with blank) all functions by pressing PF4.

When you have marked the desired functions or modified any value on the screen, press PF6 for the selection before pressing PF3, otherwise ASF ignores your changes and returns to the calling screen.

The user function remains active until you deactivate it in the User Exit Maintenance or with the direct command "ASFUEX OFF", or until the end of the Natural session. Other ASF users are not affected, when you activate or deactivate a user function.

Direct Commands

The following direct commands are available for the maintenance of the ASF user functions:

ASF User Exit ASFUEX01

The ASF user exit 01 is a Natural subprogram which is delivered as source and object module on the SYSASF library. The default name of the user-exit is ASFUEX01. The delivered source is named XXXUEX01.

You can also use another Natural subprogram as user exit 01 by changing the default user exit name in the program ASFUEXN1 or by specifying the name in the ASF User Exit Maintenance. If any function in the ASF User Exit Maintenance is marked, but the specified user exit cannot be found, the evaluation will fail with the message

Invalid command, or object does not exist in library.

In this case check whether you have specified the user exit name correctly.

The ASF user exit 01 is called immediately after ASF has read the data record from the ASF Data file and before it is displayed on the screen, printed or downloaded to a PC. It gets control before the ASF user exit ASFUEXIT is called, which fills the user fields. Because the ASF user exit 01 can modify any ASF data field, the content of the modified fields are in the responsibility of the user. Thus if a user function is activated, the content of the ASF data fields can differ from what is described in the section ASF Group and Field Names in the ASF Examples documentation.

When the ASF user exit 01 gets control, the parameters described below are supplied. Input parameters (I) are filled by ASF and cannot be modified. Input/output parameters (I/O) are filled by ASF and can be modified in the user exit. Output parameters (O) are given back from the user exit to ASF. The modifiable parameters can be filled with any value, as long as the corresponding format is respected.

The #EVAL_TYPE parameter indicates which type of evaluation is currently performed. Possible evaluation types are 1 – 10.

The array #UEX(1:20) contains the user function marks as specified in the User Exit Maintenance. In general, a function is not performed if the corresponding mark is not set (blank). The mark is forwarded unchanged to the user exit, i.e. it can contain a code to perform specific sub-functions of the user function. You can set and reset the marks in the user exit itself if, for example, the function should be deactivated after a certain event.

The flag #UEX_ANY is set to TRUE if any user function has been activated in the ASF User Exit Maintenance. When control is given to the user exit, this flag is always TRUE, because the exit is only called under this condition. You may set the flag to FALSE at a certain event, to prevent a further calling of the exit.

The field #UEX_SAVE can be used to save values between two succeeding calls to the user-exit. Note that the first user function of ASFUEX01 uses the first two bytes of #UEX_SAVE and the second user function uses the bytes 3 through 10. The values in the save area can be overwritten in the User Exit Maintenance.

The group ASF-STAMM contains the complete ASF Data record as read in from the ASF Data file. The field FCB-FNR contains the Adabas file number. If it is equal to "0" the ASF Data record contains database-related data, otherwise file-related data.

In the delivered ASFUEX01 the user field USER-FIELD-A(10) is filled with the value "UEX_ACTIVE" if any user function is activated. When you add this field to an evaluation profile, it can easy be determined whether a user function has been activated during the evaluation or not.

On return to ASF, the field #RETURN_CODE contains the response code from the user exit. The meaning is as follows:

ASF User Exit ASFUEXN1

The ASF user exit ASFUEXN1 is a Natural subprogram which is delivered as source and object module on the SYSASF library. The delivered source is named XXXUEXN1.

The ASF user exit ASFUEXN1 defines initial values used by the ASF User Exit Maintenance or by the user-exit itself. You can overwrite the initial values as required.

Displaying Delta Values

With the first user function in the delivered user exit ASFUEX01, so-called delta values (or difference values) can be displayed. When the user function gets control, it reads the previous ASF Data record in the sequence of the time. For all cumulative values like "Number of L9 commands", it calculates and returns the difference between the two values (current - previous).

Example:

An evaluation has shown the following values for the field "CMD L9":

After the activation of the user function "Delta values" in the ASF User Exit Maintenance, the same evaluation would show the following values for the field "CMD L9":

Figure 6-2: Cumulative and delta values

The ASF user function reads one record back, even for the first record displayed. Thus it has found a record (7:00) with 70 L9 commands, giving a difference of 40 commands. If there is no record before the first one, the output of the first record is suppressed, i.e. #RETURN_CODE is set to '4'. In the example there would be no column of "8:00" in this case.

If the Adabas nucleus has been restarted between the two points in time which are used for the calculating, the result of a simple subtraction is not correct (probably a negative value). For this reason the user function compares the values of the nucleus-start-time in both records. In case they are different, it reads all "End-Nucleus" record between the 2 points in time. The store type of the End-Nucleus record can be defined in the ASF User Exit Maintenance by overwriting the first two characters of the user exit save area. The values found are used to correct the delta values calculated before.

The user function uses the first three user fields for returning some additional information:

Note:
The differences between the user function "Displaying Delta Values" and the ASF utility "Condense records to delta records" are described in the section Delta values displayed by the User Exit.

Evaluation within a Time Frame

With the second user function in the delivered user exit ASFUEX01, evaluations can be restricted to a specific time frame. The specified time frame is from 12:00 to 18:00. If this user function is activated, only those values are used in the evaluation, which have been stored in the time from 12:00 to 18:00.

You can define your own default time frame by overwriting the corresponding initial values in the user exit ASFUEXN1. At runtime you can modify the time frame in the ASF User Exit Maintenance. Just overwrite bytes 3 to 6 in the user exit save area with the From-Time (hhmm) and bytes 7 to 10 with the To-Time (hhmm).

If the From-Time is smaller than the To-Time, the values between the both times are displayed (daytime). If the From-Time is bigger than the To-Time the values outside of the range are displayed (nighttime).

Example

If the user exit save area looks like

EN09001800

only values between 9 a.m. and 6 p.m. are used in the evaluation.

If the user exit save area looks like

EN18000900

only values between 6 p.m. and 9 a.m. of the following day are used in the evaluation.