User Exits

User exits are Natural subprograms which are delivered as source members along with Predict. They can be used to enforce standards for documenting applications or to customize Predict functions. Examples for the use of user exits are:

• implementing security checks

• enforcing naming conventions

• logging changes to Predict data

• integrating third-party products into Predict

This section covers the following topics:

• Concept of User Exits

• New User Exits

• Old User Exits

Concept of User Exits

This section contains:

• Distinction between Old and New User Exits

• General Rules

• Format of Description of User Exits

Distinction between Old and New User Exits

The concept of user exits was redesigned with Version 3.3 of Predict. Although user exits of previous versions will be supported in future versions (to ensure compatibility) you are recommended to use the new user exits.

Old user exits are:

• ACMxxEX - Add/Copy/Modify objects

• CATELEX - Catalog fields

• CATOWEX - Catalog owners

• PURxxEX - Purge objects

General Rules

The following applies to both old and new user exits. Rules applying to either old or new user exits are described later in this section (see Old User Exits or New User Exits).

• User exits are either called before or after execution of a function
  User exits called before execution may, for example, be used to check naming conventions for object IDs; those called after execution may be used to perform security checks depending on attribute values. Old user exits are always called after execution of a function.

• User exits are delivered as source members together with Predict
  After Predict has been installed, the user exits delivered with Predict are located in the library SYSDIC.

  Warning: You are recommended to keep copies of the Natural source programs for your own user exits in a separate library to prevent them from being overwritten during installation of any new Predict version or software maintenance level.

• Message texts can be stored in the Natural message file
  Most user exits can display an online message. Message texts can be stored in the Natural system file, identified by a message number. For library SYSDIC, message numbers from 9000 to 9999 are reserved for user exit messages. Message texts are maintained with the Natural utility SYSERR. If the Natural Studio plug-ins Object Description or Schema Generation are used, the messages must be copied to library SYSDICAM with language code 1 (English). See the "Single Point of Development documentation" for further information about these plug-ins.

• Restrictions

  • Predict modules must not be used in user exits.

  • The stack must not be changed.

  • If any of the user exits issue BACKOUT TRANSACTION statements, the Natural parameter OPRB must be set to NOOPEN. This is not required under UNIX. For further details, see the respective "Natural Operations documentation".

  • The contents of the source area must not be changed.

  • Screen I/Os (like WRITE, INPUT, DISPLAY, PRINT, etc.) must not be coded in user exists if the Natural Studio plug-ins Object Description or Schema Generation are used, since this will lead to Natural I/O errors. Please refer to the "Natural Messages and Codes documentation" for detailed information on specific error messages you may receive. The Natural system variable *SERVER-TYPE can be used for the check instead (values 'DEVELOP' and 'DCOM').

Format of Description of User Exits

All descriptions of user exits are in the following format:

New User Exits

New user exits are of type subprogram and are called using the CALLNAT statement.

This section contains:

• Process Control Using MSG-NR

• Using the Parameter Data Area

• Activating New User Exits

• User Exits for Maintenance Functions

• User Exits for Retrieval Functions

• User Exits for Generation Functions

• User Exits for Other Function Groups

• SUMPRDEX - Maintain Rule in Natural Map Editor

Process Control Using MSG-NR

The parameter MSG-NR determines how a Predict function that called a user exit continues after the user exit processing terminated:

• If MSG-NR is zero, the function continues as normal. An END-OF-TRANSACTION statement is issued.

• If MSG-NR is non-zero, the function either quits or issues a BACKOUT-TRANSACTION statement. In either case the screen from which the Predict function was called is displayed, and the message identified by MSG-NR is displayed.

  Note:
  Some programs do not evaluate MSG-NR.

How the parameter MSG-NR is evaluated is described under Effect of MSG-NR in the descriptions of the individual user exits below.

Using the Parameter Data Area

Naming Conventions

The names for the parameter data areas to be used by user exits are composed by concatenating the name of the user exit and a "P" (for example, U-MNTP for the user exit U-MNT).

Use of Parameters

Depending on the user exit, some dozens of parameters may be passed to a user exit. Most of these parameters cannot be modified (Natural CALLNAT parameter AD=O). The following parameters can be modified:

• MSG-NR (I2)
  Used for process control and identification of a message. See the section Process Control Using MSG-NR above.

• MSG-TEXT1 (A34)
  To be inserted for the wild card :1: in the message identified by MSG-NR.

• MSG-TEXT2 (A34)
  To be inserted for the wild card :2: in the message identified by MSG-NR.

• SYSDIC-USER (A250)
  Reserved for users; represents the global data area variable G-USER.

Activating New User Exits

With the exception of the user exits U-MODEL and U-XREF, new user exits are activated in the first Activate User Exits screen:

Main Menu -> Defaults -> Activate User Exits ->User Exits (subprograms).

    10:02:37             *****  P R E D I C T  *****                     2007-05-31
                               - Activate User Exits -
   
    --- User exits (subprograms) ---                    Modified 2007-05-31 at 10:02
                                                              by STK
   
    Maintenance                         Active retrieval ................. N (Y/N)
      before any function .. N (Y/N)    File implementation .............. N (Y/N)
      add, copy, modify .... N (Y/N)    Comparison ....................... N (Y/N)
      purge, scratch ....... N (Y/N)    Incorporation .................... N (Y/N)
      modify description ... N (Y/N)    Administration ................... N (Y/N)
      redocumentation ...... N (Y/N)    Command processor ................ N (Y/N)
    Retrieval                           Defaults/Special functions ....... N (Y/N)
      before any function .. N (Y/N)    Check against naming conventions . Y (Y/N)
      after display .......* N
    Generation
      before execution ..... N (Y/N)
      after execution ...... N (Y/N)
   
   
    For HELP enter ? in the first input field. To leave enter .
    Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
          Help  Next  Stop  Last  LnkEl Flip  Print Impl  AdmFi SelFi Prof  Main
  

Y activates a user exit and N deactivates it (with the exception of U-DSP).

User Exits for Maintenance Functions

U-MNT and U-MNT1 - Before Any Function

U-ACMR - Add, Copy, Modify for All Object Types

U-ACM - Add, Copy, Modify for User-Defined Object Types

U-AM-A - Add, Modify for User-Defined Association Types with Attributes

U-PUR - Purge, Scratch

U-DESC - Modify Description

U-OW - Owner

U-REDOC - Redocumentation

User Exits for Retrieval Functions

U-RET - Before Any Function

U-DSP - After Display

U-MODEL - Execute Retrieval Model

U-XREF - Execute Retrieval Model / Cross Reference

Converting the User Exits U-DSP and U-MODEL

If these user exits have been used in versions of Predict 3.3 or below, they must be converted before they can be used in the current version. This section describes the changes and enhancements which must be considered:

• The parameter data areas U-DSPP and U-MODELP have been enhanced by the parameter SYSDIC-SESSION-NO. This parameter specifies the session number which is used for output; it must not be changed.

• The subprogram N-WRTEDT has been included in the user exits U-DSP and U-MODEL. This subprogram passes the output lines to the editor. N-WRTEDT has the following parameters:

  Parameter	Meaning
  SYSDIC-SESSION-NO	current session number used for output
  TABLE-LINE-OUT (A79/1:15)	table containing the output lines
  CHAR-DATE (A1/1:15)	defines the type of output data (subheader, header, etc., see example below)
  INTENSIVE-CHAR-BEG	user-defined character to mark the beginning of high-lighted text
  INTENSIVE-CHAR-END	user-defined character to mark the end of highlighted text
  SYSDIC-MSG-GR	message indicating whether processing will continue or whether the function is terminated
  SYSDIC-TRACE	for internal use only

Programming Hints

• AT TOP OF PAGE control is no longer needed since it is performed by the editor program.

• Each WRITE statement must be replaced by a MOVE or COMPRESS statement.

• The entries in the tables TABLE-LINE-OUT and CHAR-DATE refer to each other: An entry in CHAR-DATE determines the type of the data contained in the corresponding entry of TABLE-LINE-OUT.

Example:

Explanation:

• The first line to be displayed is a header (indicated by "H" in CHAR-DATE) with the text "header1" (corresponding entry in TABLE-LINE-OUT).

• The second line is also part of the header and contains the text "header2".

• The third line is a subheader (indicated by "S" in CHAR-DATE) with the text "subheader1".

• The forth line contains the data (indicated by blank in CHAR-DATE).

• The lines must be passed to the subprogram N-WRTEDT in the appropriate format.

• After N-WRTEDT has been called, MSG-NR must be checked. If MSG-NR is greater than zero, an ESCAPE ROUTINE statement must be performed.

• Possible values of CHAR-DATE:

  Possible Values
  P (Newpage)	User-defined page break; for this entry in CHAR-DATE, there is no corresponding entry in TABLE-LINE-OUT.
  H (Header)	A header can consist of one or more lines. The separation line between header and data is controlled by the editor program.
  S (Subheader)	Subheaders are highlighted and are not repeated on subsequent pages.
  T (Column header)	A column header: is repeated on any subsequent page; may consist of more than one line; is highlighted; is deactivated when a new header (CHAR-DATE = H) or a new column header is to be displayed.
  X (Permanent subheader)	Subheader which is to be repeated on any subsequent page. It is deactivated when a new header (CHAR-DATE = H) or a new subheader (CHAR-DATE = S or T or X) is to be displayed.
  D (Output using PM=C)	For lines to be displayed using the session parameter PM=C, the following must be entered in the tables (before the lines containing the data) to activate this parameter:
  	TABLE-LINE-OUT	CHAR-DATE
  	PM=C	D
  	To deactivate the session parameter, the following must be specified:
  	TABLE-LINE-OUT	CHAR-DATE
  	PM=	D
  	The output of headers cannot be controlled using PM=C.

User Exits for Generation Functions

U-GEN - Before Execution

U-GEN1 - After Execution

U-OGEN - Object ID Generation

User Exits for Other Function Groups

U-ACT - Active Retrieval

U-IMPL - File Implementation

U-COM - Comparison

U-INC - Incorporation

U-MIP - Administration Implementation

U-CMD - Command Processor

U-SPEC - Defaults / Special Functions

U-OBJID - Add, Copy, Rename, Incorporation, Redocumentation

U-PGMLAN - Define New Program Language

U-MTOT - Translate UDEs from Earlier Versions

U-MOBJ - Reject Objects During the Migrate Format Conversion.

SUMPRDEX - Maintain Rule in Natural Map Editor

SUMPRDEX does not fit into the 'old/new' scheme we use to categorize user exits. It is in fact an old user exit because it already existed in Predict V2.3, is a Natural program (not a subprogram) and is activated in the User exits (programs) screen. But unlike other old user exits, SUMPRDEX cannot be substituted by a new user exit and is therefore contained in this section on new user exits.

User Exit SUMPRDEX

Old User Exits

All old user exits are of type program. Old user exits are still supported to ensure compatibility with earlier versions of Predict. You are recommended to use new user exits.

This section contains:

• Overview of Old User Exits

• Process Control Using G-FUNCTION

• Using the Global Data Area

• Activating Old User Exits

• ACMxxEX - Add/Copy/Modify Objects

• CATELEX - Catalog Fields

• CATOWEX - Catalog Owners

• PURxxEX - Purge Function

Overview of Old User Exits

ACMxxEX

The Predict functions Add, Copy, Modify and Rename call the user exits ACMxxEX.

xx stands for one of the object type codes: DA, EL, FI, KY, PR, RL, SY, US and VE.

For example: the user exit ACMFIEX is called before a file is added, copied or modified.

PURxxEX

The Purge function calls the user exits PURxxEX before the deletion is executed.

xx stands for one of the object type codes: DA, EL, FI, KY, PR, RL, SY, US and VE.

For example: the user exit PURELEX is called before a field is purged.

CATELEX and CATOWEX

The CAT command calls the user exit CATELEX (only valid for the fields of a file) or CATOWEX (only valid for the owners of an object).

Process Control Using G-FUNCTION

With old user exits, the parameter G-FUNCTION determines how a Predict function that called a user exit continues after the user exit processing is completed:

• If G-FUNCTION is not blank, the program continues as normal.

• If G-FUNCTION is blank, the Predict function issues a BACKOUT-TRANSACTION statement.

If G-FUNCTION is not reset and therefore no BACKOUT TRANSACTION issued, an END OF TRANSACTION statement must not be coded.

Using the Global Data Area

The following variables in the block ROOT of the global data area PGDA-Vvr contain information which may be of use in user exits.

Using the Global Data Area with Type-Dependent User Exits

• Old user exits must be cataloged with the Predict global data area PGDA-Vvr (where the notation vr represents the relevant product version (see also Version in the Glossary) using the following statements:

  DEFINE DATA GLOBAL USING PGDA-Vvr WITH ROOT
  END-DEFINE

• With the exception of G-FUNCTION and G-USER, variables in the global data area must not be changed.

• G-ID, G-ISN and G-OLD-ISN deliver values that may be needed for user exits (see table above).

Activating Old User Exits

Old user exits are activated in the second Activate User Exits screen: Main Menu > Defaults > Activate User Exits >User Exits (subprograms) > User Exits (programs).

    10:36:25             *****  P R E D I C T  *****                     2007-05-31
                               - Activate User Exits -
   
       ----------- User exits (programs) -----------   Modified 2007-05-31 at 10:32
                                                             by STK
                          ACM     PURGE     CAT
       Database .......... Y (Y/N)  N (Y/N)
       Elementary field .. N (Y/N)  N (Y/N)  N (Y/N)
       File .............. N (Y/N)  N (Y/N)
       Keyword ........... N (Y/N)  N (Y/N)
       Program ........... N (Y/N)  N (Y/N)
       File relation ..... N (Y/N)  N (Y/N)
       System ............ N (Y/N)  N (Y/N)
       User .............. N (Y/N)  N (Y/N)
       Verification ...... N (Y/N)  N (Y/N)
       Owner ............*                   N
   
   
    For HELP enter '?' in the first input field. To leave enter '.'
    Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
          Help  Next  Stop  Last  LnkEl Flip  Print Impl  AdmFi SelFi Prof  Main
  

Old user exits are activated by entering Y in the respective line and column. In the example above, ACMDAEX is activated; all other old user exits are deactivated.

ACMxxEX - Add/Copy/Modify Objects

CATELEX - Catalog Fields

CATOWEX - Catalog Owners

PURxxEX - Purge Function