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

Note:
The subprograms U-EXPSC, U-EXPSRP, U-IMPSC, and U-IMPSRP are also delivered as source members. They are used for transferring text between Predict and an external environment and are called automatically by the respective functions.Exporting Text to an External Target Importing Text from an External Source Predict Reference documentation. These user exits cannot be controlled by the Activate user exits function and are therefore not described in this section.

This section covers the following topics:


Concept of User Exits

This section contains:

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:

Activate with: Name of the parameter in one of the Activate User Exits screens that activates or deactivates the user exit, or - if the user exit is not activated in an Activate User Exits screen - the method to activate the user exit.
Applies to: Object types and/or functions the user exit applies to.
Called where and when: Where and when the user exit is executed (if active).
Effect of MSG-NR: How the parameter MSG-NR is evaluated. Only for new user exits. See also Process Control Using MSG-NR.
+SYSDIC-FUNCTION: How +SYSDIC-FUNCTION is evaluated. Only for old user exits. See also Process Control Using +SYSDIC-FUNCTION.
Additional remarks: Additional notes on how to use the user exit.
Any category that does not apply is omitted from the description.

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

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

Note:
If a user exit has to be cataloged under Predict 4.2, then the corresponding Parameter Data Area (PDA) has to be cataloged before since it is delivered with Predict 4.2 in source form only.

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 +SYSDIC-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).

Note:
If the user exit does not exist in the Predict system file, the respective parameter cannot be set to Y.

User Exits for Maintenance Functions

U-MNT and U-MNT1 - Before Any Function

Activate with: parameter before any function
Applies to: U-MNT applies to all object types except fields, U-MNT1 applies only to fields.

Note:
When the editor command SEL is used, the parameter +SYSDIC-FUNCTION must be set to T. See Selecting Text from another Source within Predict Predict Reference documentation.

Called where and when:
  • from Maintenance menus before a function is executed,

  • before a Predict editor is called,

  • before an object is added or modified with the .E command (in an editor),

  • before the Select function is executed in an editor,

  • before the Purge function with option SCRATCH is executed. The user exit is performed before dependent objects and references to the child objects are deleted. If, in this case, parameter MSG-NR is set, the dependent objects or references to the child object are not deleted and a message text is displayed (or printed in batch mode). No possibility for re-input is given here! See the respective section of the Predefined Object Types in Predict documentation for a list of objects that are deleted with the Purge function.

  • File and Database-Specific
    in case of add or copy after subtypes have been entered (second screen).

  • Field-Specific
    during saving of an edited field list and before a field is added, copied, modified, renamed or deleted.

Effect of MSG-NR:

If non-zero, the Predict function is not executed and the message MSG-NR is displayed.

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

Activate with: add, copy, modify
Applies to: all object types
Called where and when:
  • From the add, copy, modify function after attribute values have been written to the dictionary, before END OF TRANSACTION.

  • Before the user exits ACMxxEX are executed.

Effect of MSG-NR: If non-zero, BACKOUT TRANSACTION is issued and the message MSG-NR is displayed.

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

Activate with: add, copy, modify
Applies to: user-defined object types
Called where and when: From the add, copy, modify function before attribute values are written to the dictionary.
Effect of MSG-NR: If non-zero, the Predict function is re-executed and the message MSG-NR is displayed. Attribute values can then be changed in the input screen of the function.

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

Activate with: add, modify
Applies to: user-defined associations with attributes
Called where and when: From the add or modify function before attribute values are written to the dictionary.
Effect of MSG-NR: If non-zero, the Predict function is re-executed and the message MSG-NR is displayed. Attribute values can then be changed in the input screen of the function.

U-PUR - Purge, Scratch

Activate with: purge, scratch
Applies to: all object types
Called where and when: When the option Delete or Scratch has been specified after confirmation of the deletion.
Effect of MSG-NR: If non-zero, the Predict function is re-executed and the message MSG-NR is displayed. Attribute values can then be changed in the input screen of the function.

U-DESC - Modify Description

Activate with: modify description
Applies to: all object types
Called where and when:
  • After an extended description was saved and before an END TRANSACTION statement is issued.

  • Additional remarks: If this user exit is activated, a copy of it must reside in library SYSLIB of the current Natural system file (FNAT). This is necessary to provide the same kind of processing of the description when added or modified using the Natural command edit description.

Effect of MSG-NR: If non-zero, BACKOUT TRANSACTION is issued and the message MSG-NR is displayed.

U-OW - Owner

Activate with:

U (only U-OW is performed) or
B (U-OW and CATOWEX are performed).

Applies to: each owner in the list
Called where and when: Before owners in an owner list are actually updated or deleted by the CAT command.
Effect of MSG-NR: If non-zero, the editor is called again and the message MSG-NR is displayed.

U-REDOC - Redocumentation

Activate with: redocumentation
Applies to: programs
Called where and when: after parameters for the function Redocument Program have been specified.
Effect of MSG-NR: If non-zero, the Predict function is not executed and the message MSG-NR is displayed.

User Exits for Retrieval Functions

U-RET - Before Any Function

Activate with: Retrieval / before any function
Applies to: all object types
Called where and when: from each retrieval menu after input parameters have been specified and before the function is executed.
Effect of MSG-NR: If non-zero, the Predict function is not executed and the message MSG-NR is displayed.

U-DSP - After Display

Activate with:
  • O
    Optional: U-DSP can be (de)activated by the user by setting the output option User exit or

  • F
    Force: U-DSP is active and cannot be deactivated by an output option.

Applies to: all object types
Called where and when: after an object has been displayed and before the extended description is displayed.
Effect of MSG-NR: No effect.

Note:
With this version of Predict, retrieval output is placed in an Software AG Editor session by default. See the section Editors in Predict in the Predict Reference documentation. If you used this user exit in a former version, you must convert it before using it with the Software AG Editor (see Converting the User Exits U-DSP and U-MODEL). If you do not wish to convert this user exit, you must set the parameter Use Software AG Editor for Retrieval output (under General > Miscellaneous) to N. In this case, retrieval output is handled as in former versions of Predict. See Software AG Editor in the Predict Reference documentation.

U-MODEL - Execute Retrieval Model

Activate with:

parameter Use U-MODEL in Add/Modify Retrieval Model definition screen when adding or modifying retrieval models

  • Y
    Objects found by the retrieval operation are processed exclusively by U-MODEL.

  • N
    U-Model is deactivated.

  • A
    Objects found are first displayed by the retrieval operation and then processed by the U-MODEL.

Applies to: all object types specified in the retrieval model
Called where and when:
  • for any object found by a retrieval operation with retrieval type Execute retrieval model. Further processing depends on the output mode:

    • With output mode structured list (code T), any object found by the retrieval operation can be processed by U-MODEL (for example: be displayed in a user-defined format). The scope of a report can be restricted using the parameter REJECT. If REJECT is set to TRUE for an object, processing of the retrieval model skips all objects on lower levels and continues with the next object on the same or a higher level.

      For example: Information on a Natural application using utilities implemented in COBOL are retrieved. Any information on internal structures of the COBOL utilities can be excluded from the report by setting REJECT=TRUE whenever a COBOL member is found.

    • With output mode cross reference (code X), the report can be restricted using the parameter REJECT. With this output mode, immediate further processing of object information collected by the retrieval operation is not possible: object data is written to a sort buffer (source area) before it is displayed. For further processing, U-XREF must be used.

Effect of MSG-NR:

No effect.

Note:
From the current Predict version, retrieval output is by default placed in an Software AG Editor session (see the section Editors in Predict in the Predict Reference documentation). If you used this user exit in a former version, you must convert it before using it with the Software AG Editor (see Converting the User Exits U-DSP and U-MODEL).

If you do not wish to convert this user exit, you must set the parameter Use Software AG Editor for Retrieval output (under General > Miscellaneous) to N. In this case, retrieval output is handled as in former versions of Predict. See Software AG Editor in the "Predict Reference documentation".

U-XREF - Execute Retrieval Model / Cross Reference

Activate with: parameter Use U-XREF in Add/Modify Retrieval Model definition screen when adding or modifying retrieval models
Applies to: all object types specified in the retrieval mode
Called where and when: after object information has been read from the sort buffer (source area) for display (retrieval type Execute retrieval model and output mode cross reference).
Effect of MSG-NR: No effect.

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:

Index TABLE-LINE-OUT CHAR-DATE
1 header1 H
2 header2 H
3 subheader S
4 actual data  

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

Activate with: before execution
Applies to: all object types processed by generation functions
Called where and when: after generation parameters have been specified and before the generation is executed.
Effect of MSG-NR: If non-zero, the Predict function is not executed and the message MSG-NR is displayed.
Additional remarks: U-GEN is active after installation. U-GEN as delivered rejects the Generate Adabas file function in order to prevent data from being overwritten inadvertently. Before the function Generate Adabas file can be used, U-GEN must be modified or before execution must be set to N.

Note:
Adabas files can also be protected by means of Natural Security. For more information see the section Protecting External Objects in Predict with Natural Security Predict Security documentation.

U-GEN1 - After Execution

Activate with: after execution
Applies to: all object types processed by generation functions
Called where and when: after successful execution of generation (a member must have been saved).
Effect of MSG-NR: No effect.

U-OGEN - Object ID Generation

Activate with: U-OGEN is always active
Applies to: API USR3005N
Called where and when: This user exit willl be performed if the value *GENERATE* has been specified as object ID in an ADD or RENAME request of API USR3005N.

User Exits for Other Function Groups

U-ACT - Active Retrieval

Activate with: Active retrieval
Applies to: object types processed by active retrieval functions
Called where and when: from each active retrieval menu after input parameters have been specified and before the function is executed.
Effect of MSG-NR: If non-zero, the Predict function is not executed and the message MSG-NR is displayed.

U-IMPL - File Implementation

Activate with: File implementation
Applies to: File implementation
Called where and when: Before an implementation plan is added, extended, listed, modified, purged or executed.
Effect of MSG-NR: If non-zero, the Predict function is not executed and the message MSG-NR is displayed.

U-COM - Comparison

Activate with: Comparison
Applies to: all object types processed by comparison functions
Called where and when: after comparison parameters have been specified and before the function is executed.
Effect of MSG-NR: If non-zero, the Predict function is not executed and the message MSG-NR is displayed.

U-INC - Incorporation

Activate with: Incorporation
Applies to: all object types processed by incorporation functions
Called where and when: after incorporation parameters have been specified and before incorporation is executed. Exception: With the functions Incorporate Natural Security User and Incorporate Super Natural User, the user exit is called before specification of the parameters and before execution, but all selected object types are incorporated during the same run.
Effect of MSG-NR: If non-zero, the Predict function is not executed and the message MSG-NR is displayed.

U-MIP - Administration Implementation

Activate with: Administration
Applies to: all external objects processed by administration functions
Called where and when: from the Administration Implemented Object menu after parameters have been specified and before the function is executed.
Effect of MSG-NR: If non-zero, the Predict function is not executed and the message MSG-NR is displayed.
Additional remarks: U-MIP is active after installation. U-MIP as delivered inhibits execution of the functions Purge/Refresh Adabas file to prevent accidental loss of data. Before the functions Purge/Refresh Adabas file can be used, U-MIP has to be modified or Administration must be set to N.

Note:
Adabas files can also be protected by means of Natural Security. For more information see the section Protecting External Objects in Predict with Natural Security in the Predict Security documentation.

U-CMD - Command Processor

Activate with: Command Processor
Applies to: Predict commands
Called where and when: after the syntactical analysis and before interpretation and execution of a command. A command not recognized as a Predict command is passed to the user exit with SYSDIC-COMMAND-TYPE 'US'. The user exit can be used
  • to interpret user-defined commands

  • to inhibit commands.

Effect of MSG-NR: If non-zero, the Predict command is not executed and the message MSG-NR is displayed.
Additional remarks: U-CMD allows implementation of user-specific command codes. An example is contained in U-CMD.

U-SPEC - Defaults / Special Functions

Activate with: Defaults / Special functions
Applies to: all Predict administration functions contained in the Defaults / Special functions menus
Called where and when: before any of the functions in the Defaults or Special Functions screen is displayed
Effect of MSG-NR: If non-zero, the calling of the Defaults or Special Functions screen is rejected and the message MSG-NR is displayed.
Additional remarks: U-SPEC can be used to protect Predict Administration functions contained in the Defaults / Special functions menus.

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

Activate with: add, copy, rename, incorporation, redocumentation
Applies to: all object types
Called where and when: after the object ID has been checked (first character is a letter, length and disallowed characters defined under Metadata Administration) and before END TRANSACTION is executed.
Effect of MSG-NR: If non-zero, BACKOUT TRANSACTION is issued and the message MSG-NR is displayed.

U-PGMLAN - Define New Program Language

Activate with: U-PGMLAN is always active
Applies to: program objects
Called where and when: Whenever Predict functions display a selection window for programming languages and if changes to the attribute language are validated.
Effect of MSG-NR: No effect.
Additional remarks: Up to ten new languages can be defined.

U-MTOT - Translate UDEs from Earlier Versions

Activate with: Migrate Conversion function
Applies to: Migrate objects
Called where and when: This user exit will be performed at the beginning of the migrate format conversion.
Effect of MSG-NR: No effect.
Additional remarks: This user exit translates the codes that are reserved in Predict Version 4.1. For user-defined object type codes and object typ names of earlier versions, you must enter a new code and/or name or you can use the assigned defaults.

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

Activate with: Migrate Conversion function
Applies to: Migrate objects
Called where and when: This user exit will be performed before the conversion of an object from migrate 3.1, 3.2 or 3.4 format to migrate 4.1 format.
Effect of MSG-NR: No effect.
Additional remarks: Migrate objects of the versions 3.1, 3.2 and 3.4 can be explicitly excluded from the conversion based on:
  • Migrate version,

  • Current object type,

  • Current object ID,

  • Current object subtype.

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.

Note:
See also Protecting Processing Rules in the section Protecting External Objects in Predict with Natural Security in the Predict Security documentation.

User Exit SUMPRDEX

Activate with: Y for verification in the column ACM of the Activate user exits - User exits (programs) screen. See Activating Old User Exits. If you specify Y in this field, the user exit ACMVEEX is activated, too.
Applies to: Free rules.
Called where and when: Immediately after a rule has been added or modified with the Natural map editor, the program SUMPRDM in library SYSLIB is called. This program issues a CALLNAT SUMPRDEX statement and passes the variables listed in the table below.
SUMPRDEX uses SYSDIC-RSP for process control.
Additional remarks: No global data area is available. SUMPRDEX has to be stored in library SYSLIB.
Variable Meaning
VERIFICATION-ID(A32) ID of the variable currently being processed.
SYSDIC-ISN(P8) ISN of the record just processed.
SYSDIC-FUNCTON(A1)

Current function:

A add

M modify

SYSDIC-RSP(N1)

Response code:

0 ok

2 BACKOUT TRANSACTION

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

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 +SYSDIC-FUNCTION

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

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

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

If +SYSDIC-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 contain information which may be of use in user exits.

Variable Meaning
+SYSDIC-ID(A32) With the rename function: old ID of the object.
With the catalog function: ID of the object (field or owner) currently being processed.
+SYSDIC-ISN(P10) ISN of the record just processed.
+SYSDIC-OLD-ISN(P10) With the copy function: ISN of the record that was copied.
+SYSDIC-FUNCTION(A2) When this variable is passed by the Predict function, its first character indicates the function:
  • A
    add

  • C
    copy

  • M
    modify

  • N
    rename

  • P
    purge

  • O
    edit owners

  • W
    edit description

+SYSDIC-FUNCTION must be reset to issue a BACKOUT TRANSACTION statement.
(See Process Control Using +SYSDIC-FUNCTION above).
+SYSDIC-USER(A250) Reserved for the user.

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 +SYSDIC-FUNCTION and +SYSDIC-USER, variables in the global data area must not be changed.

  • +SYSDIC-ID, +SYSDIC-ISN and +SYSDIC-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.

Note:
Setting ACM/Verification to Y activates the user exits SUMPRDEX and ACMVEEX.

ACMxxEX - Add/Copy/Modify Objects

Activate with: Y for any object type in the ACM column.
Applies to: object types DA, EL, FI, KY, PR, RL, SY, US and VE.
Called where and when: depending on the function and the object type.
  • Add, Copy and Modify
    The user exit is executed before the editors (for extended description, owner list, sub-object list) are activated.

  • Add, Copy and Modify Field
    The user exit for fields (ACMELEX) is executed before rippling takes place.

  • Rename
    For all object types except files, the user exit is executed after the object has been renamed. With the function Rename/renumber file, the user exit is executed before the File is renamed and before the fields and related files are processed.

+SYSDIC-FUNCTION: To issue a BACKOUT TRANSACTION statement, +SYSDIC-FUNCTION must be reset.
Additional remarks: If an object list is edited and several .E(n) line commands have been entered, the appropriate user exit (ACMxxEX) is invoked for each object. If a BACKOUT TRANSACTION is issued by the user exit, processing does not continue with the next object in the list, and Predict returns to the object list editor.
With the function Browse through fields of a file, a BACKOUT TRANSACTION in the user exit ACMELEX causes Predict to return to the Field Maintenance menu.

CATELEX - Catalog Fields

Activate with: Y for field in the CAT column.
Applies to: Fields
Called where and when: After storing, updating and rippling (including delete rippling) have taken place and before deletion takes place.
+SYSDIC-FUNCTION: To issue a BACKOUT TRANSACTION statement, +SYSDIC-FUNCTION must be reset.
Additional remarks: CATELEX is invoked after the CAT command if a field in the field list has been modified, unless it has been modified using the .E editor line command. If the .E editor line command was used, the user exit ACMELEX is invoked instead.
Unless rejected by the user exit ACMELEX, the editor line command .E is executed and the dictionary is updated.

CATOWEX - Catalog Owners

Activate with: Y, B or U for field in the CAT column.
  • Y
    only CATOWEX is executed

  • B
    CATOWEX and U-OW are executed

  • U
    only U-OW is executed

Applies to: Owners
Called where and when: After an owner list has been edited and a CAT command has been issued, CATOWEX is executed before storing/updating or deletion takes place. It is invoked once for each owner in the list.
+SYSDIC-FUNCTION: To issue a BACKOUT TRANSACTION statement, +SYSDIC-FUNCTION must be reset.
Additional remarks: Unless rejected by the user exit ACMUSEX, the editor line command .E is executed and the dictionary is updated.

PURxxEX - Purge Function

Activate with: Y for any object type in the PURGE column.
Applies to: object types DA, EL, FI, KY, PR, RL, SY, US and VE.
Called where and when: before the confirmation screen of the function purge appears.
+SYSDIC-FUNCTION: To issue a BACKOUT TRANSACTION statement, +SYSDIC-FUNCTION must be reset.