Version 8.1.1
 —  Adabas Statistics Facility (ASF) Version 8.1.1 User's Guide  —

User Fields and User Functions

This document covers the following topics:


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.

Top of page

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:

User Exit Source Description
ASFUEXIT XXXUEXIT Supply data for user fields before ASF stores the record or when an evaluation runs.
ASFUEXNA XXXUEXNA Define the names of the user fields.
ASFUEX01 XXXUEX01 Define user functions which operate on the ASF data when an evaluation runs.
ASFUEXN1 XXXUEXN1 Define the short descriptions of the user functions.

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

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:

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.

FCB-FNR Record General Data DB Data File Data Evaluation Type
0 DB record Yes Yes No 1-4, 9, 10
≥ 1 File record Yes No Yes 5-8, 9, 10

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.

Level Name Format Description
1 ASF-STAMM   Full ASF Data record.
2 TIME T Store time or synchronized store time (for synchronized records).
2 INV-DATE P13 Inverted time.
2 REAL-STORE-TIME T Real store time.
2 USER A8 User Id of saver.
2 STORE-TYPE A2 Store type like "AH" or "DA".
2 PROFIL-ID P5 Profile ID of the store profile.
2 GCB-DBID P5 Database ID.
2 SART-KZ A2 Record type (NU=nucleus record, TR=trend record).
2 GCB-DBNAME A16 Name of Database.
2 FCB-FNR P5 File Number.
2 FCB-FILENAME A16 Name of File.
2 USER-FIELDS   User fields in the view.
3 USER-FIELD-A A11/1:10 Alphanumeric user fields.
3 USER-FIELD-P P11/1:10 Numeric user fields.

Top of page

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

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.

Level Name Format Description
1 #FIELD-NUMBER N3

Before a store (create real field): 0

At evaluation (create virtual field): the field number of the user field to be evaluated, i.e. 1-10 for alphanumeric fields, 11-20 for numeric fields.

1 -*-*-*-* ASF-STAMM   A copy of the full ASF Data record as described above. Do not modify the user fields in ASF-STAMM!

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.

Level Name Format Description
1 #USER-FIELDS   User field group
2 #USER-FIELD-A A11/1:10 Alphanumeric user-fields.
2 #USER-FIELD-P P11/1:10 Packed user-fields.
1 #RSP N3 Response code.
1 #MSG A79 Message (currently not used).

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:

#FIELD-NUMBER Field Evaluated
1 #USER-FIELD-A(1)
2 #USER-FIELD-A(2)
... ...
10 #USER-FIELD-A(10)
11 #USER-FIELD-P(1)
12 #USER-FIELD-P(2)
... ...
20 #USER-FIELD-P(10)

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:

Response Store Evaluate
0 The record is stored including the user fields supplied by the user exit. The user field value calculated in the user exit is displayed.
> 0 The record is not stored. The user field value stored in the ASF Data record is displayed.

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.

Top of page

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

                                                                                
 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

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:

Direct Command Purpose
ASFUEX Display the ASF User Exit Maintenance Menu.
ASFUEX ? Display the current status of the ASF user functions.
ASFUEX OFF De-activate all ASF user functions.
ASFUEX ON Activate all ASF user functions.
ASFUEX n Activate ASF user function n, where n is a number from 1 to 20.

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.

Type Level Name Format Description
I 1 #EVAL_TYPE P2 Evaluation type: 1-10
I 1 #P_SATZART P2 Value of ORIGIN field: NU, TR, ALL
I/O 1 #UEX A1/1:20 User function marks as specified in the User Exit Maintenance.
I/O 1 #UEX_ANY L User exit flag, true if any user function is activated.
I/O 1 #UEX_SAVE A32 Save area for the user exit.
I/O 1 ASF-STAMM   The ASF Data record as described in the section User Exit Programming.
O 1 #RETURN_CODE N2 Response code from the user exit.

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:

Response Meaning
0 The returned values of ASF-STAMM are used for the evaluation.
4 The record is suppressed, i.e. it is not displayed in the evaluation.
8 The evaluation is finished as if the end of the data has been reached.

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.

Field Description
#UEX_PROG The default name of the ASF user exit 01 program. The value can be overwritten at run-time in the ASF User Exit Maintenance. In the delivered member this name is set to "ASFUEX01".
#UEX_NAME Short description of the user functions. The descriptions are displayed in the ASF User Exit Maintenance.
#UEX_SAVE The user exit save area can be used to forward any information to the user exit or to save some values between succeeding calls to the user-exit.
#UEX_SAVE_N This field describes the layout of the user exit save area. It is displayed in the User Exit Maintenance.

Top of page

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":

TIME 8:00 9:00 10:00 11:00 12:00
CMD L9 110 180 230 240 350

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":

TIME 8:00 9:00 10:00 11:00 12:00
CMD L9 40 70 50 10 110

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:

Field Description
USER-FIELD-A(01) The date of the additionally read ASF Data record used for the calculating of the difference.
USER-FIELD-A(02) The time of the additionally read ASF Data record used for the calculating of the difference.
USER-FIELD-A(03)

Indicates, whether the nucleus has been restarted.

Nucleus has been restarted and end-nucleus record found: "EN-Rec_fnd"

Nucleus has been restarted but end-nucleus record not found: "No_EN-Rec"

Nucleus has not been restarted: Field is empty

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.

Top of page

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.

Top of page