CA Endevor Integration for the Natural Environment › How to Install the Software › Install User Exits

Install User Exits

Certain user exits supplied by Software AG are required. In addition, optional exits are provided that allow you to customize security and exit procedures.

The Natural administrator usually performs this procedure.

To install the user exits

1. Copy the object code of the following Natural objects from the SYSEXT library to either the SYSTEM library or the EINELIB library (in the Natural environment in which CA Endevor SCM Integration for the Natural Environment was loaded). The following Software AG supplied user exits are required and must reside in either the SYSTEM library or the EINELIB library:

   USR0050N USR0210N USR0320N USR0420N USR1033N

   USR1043N USR1051N USR1054N USR1055N USR1056N

   USR1057N USR2004N USR2014N USR2018N USR2019N

   USR2027N USR3013N

2. (Optional) Modify the initialization exit. The CA Endevor Integration for the Natural Environment initialization exit (UEXIT00) is used to control configuration options for the EINE Natural application. The initialization exit is invoked (by fetch) immediately subsequent to invocation of a CA Endevor Integration for the Natural Environment session from the Natural command prompt.

   Modify UEXIT00 by logging on to the EINELIB Natural library, update UEXIT00 to your site requirements, and issue a STOW command. Once the modifications are complete and the exit STOWed, the EINE Servers must be shutdown and restarted.

   Note: If you are upgrading from Version 15.0 or Release 15.1 and saved your current UEXIT00 to a temporary Natural library, you can use it as a model for updating the Version 16.0 UEXIT00.

   You can make the following changes to UEXIT00:

   1. Add security checks to allow the session to be terminated from within the user-exit module.
   2. Change the values for the following variables if you want to change the default values:

      +UEXIT00-RJE-GEN-USERID-PASSWORD

      Defines the logical variable that is used to tell EINE whether or not to include USERID= and PASSWORD= as part of the job card for jobs submitted using RJE.

      Valid values are TRUE or FALSE. The default is TRUE.

      +EINE-TIMEOUT-INTERVAL-SERVER

      Defines the wait time limit for the server to begin processing a request. This is the time in seconds that the server is allowed to begin processing a queued request before returning control to the user. The user may choose to wait for the request or return to EINE. Timeouts for this value can indicate that additional servers may be required.

      Valid values are 10 to 180 seconds. If the value is set outside this range, the default is used. The default is 30 seconds.

      +EINE-TIMEOUT-INTERVAL-API

      Defines the wait time limit that the API has to process a request from the server. This is the time in seconds that the API is given to process a request before returning control to the user. The user may choose to wait for the request to complete or return to EINE.

      Valid values are 10 to 180 seconds. If the value is set outside this range, the default is used. The default is 30 seconds.

      +EINE-TIMEOUT-INTERVAL-PWD

      Defines the timeout interval for user passwords. A zero value causes a prompt for a password to occur for every logon attempt. If the value is greater than zero, the user is not prompted to reenter a password for each new session until the timeout interval has expired. The encrypted password is stored in the User Profile record and is used with the user ID to verify access to EINE. If the logon attempt fails, the logon window reopens.

      Valid values are 0 to 999999. The value is defined in minutes (1440 = one day, 10080 = one week, 525600 = one year). The default is zero (0), which forces the user to log on every time upon entering EINE.

      +EINE-CLEANUP-LATENCY-MINUTES

      Defines the time in minutes after which a request found on the message queue file is deleted.

      Any positive value is valid. The default is 240 minutes (four hours).

      +EINE-MAX-ADD-RETRIEVE-PER-JOB

      Defines the maximum number of Add or Retrieve actions to be processed by one batch job submitted by the EINE application. If more than this number is requested, multiple jobs are submitted.

      Valid values are 1 to 240. The default is 240.

      +EINE-STARTUP-CMD

      Defines the name of the EINE program used to startup the EINE application.

      The default is EINE.

      +EINE-INSTALL-LIBRARY

      Defines the name of the Natural library into which the EINE executables have been installed.

      The default is EINELIB.

      +EINE-SCL-LIBRARY

      Defines the name of the Natural library into which an SCL Text Object is saved.

      The default is EINESCL.

      +EINE-SYSTRANS-SYSOBJH

      Defines the Natural utility program used to load and unload Natural objects from Natural libraries.

      Valid values are:

      O— Specifies SYSOBJH Internal format which includes the Natural line numbers when the Natural object is unloaded and stored in CA Endevor SCM meta data files. This is the default.

      F— Specifies SYSOBJH Transfer format which does not include the Natural line numbers when the Natural object is unloaded and stored in CA Endevor SCM meta data files.

      L— Specifies SYSOBJH Transfer USE-LINE-NUMBER-INCREMENT which works the same as the Transfer option, F, except that the USE-LINE-NUMBER-INCREMENT keyword is specified in the Transfer clause. The USE-LINE-NUMBER-INCREMENT keyword causes the linenumber increment to be unloaded with the Natural object during the SYSOBJH unload process. If line number increment was unloaded with the Natural object, it is used to rebuild the line numbers of the Natural source object during the SYSOBJH load process.

      Note: The USE-LINE-NUMBER-INCREMENT option is only available with Natural 8.2.3 SP07 or higher.

      T— Specifies SYSTRANS. The SYSTRANS utility is no longer supported in Natural v8.2 and higher. If currently using SYSTRANS, switch to the SYSOBJH Transfer format.

      Note: For more information about how the +EINE-SYSTRANS-SYSOBJH setting affects line numbering, see the example at the end of this topic.

      +EINE-RESTRICT-JOBCARDS

      Determines if the Job Cards presented in the Batch Submittal window can be modified or not.

      Valid values are 'Y' and 'N'. The default is N.

      +EINE-LOGON-EXIT-ENABLED

      Used to determine whether the EINE Logon exit, UEXIT01, is enabled or not. If +EINE-LOGON-EXIT-ENABLED is enabled (set to Y ), then UEXIT01 is FETCHed during the EINE logon process. Sites can use UEXIT01 to perform any custom logon processing necessary.

      Valid values are 'Y' and 'N'. The default is N.

      +EINE-DSPLY-MENU-PACKAGES

      Determines if the Packages Option is displayed on the EINE Main menu.

      Valid values are Y or N. The default is Y.

      +EINE-DSPLY-MENU-SAVEDSCL

      Determines if the Saved SCL Option is displayed on the EINE Main menu.

      Valid values are Y or N. The default is Y.

      +EINE-DSPLY-MENU-DDM

      Determines if the DDM Option is displayed on the Foreground and Batch Processing Menus.

      Valid values are Y or N. The default is Y.

      +EINE-DSPLY-MENU-PREDICT

      Determines if the Predict Option is displayed on the Foreground and Batch Processing Menus.

      Valid values are Y or N. The default is Y.

      +EINE-DFLT-SIGNOUT

      Defines the initial default Signout Element action option value for Retrieve actions.

      Valid values are Y or N. The default is N.

      +EINE-DFLT-REPLACE

      Defines the initial default Replace if Present action option value for Retrieve actions.

      Valid values are Y or N. The default is Y.

      +EINE-DFLT-GENERATE

      Defines the initial default Generate Element action option value for Add and Transfer actions.

      Valid values are Y or N. The default is Y.

      +EINE-DFLT-UPDATE

      Defines the initial default Update if Present action option value for Add actions.

      Valid values are Y or N. The default is Y.

      +EINE-DFLT-W-HIST

      Defines the initial default With History action option value for Move and Transfer actions.

      Valid values are Y or N. The default is N.

      +EINE-DFLT-RET-SIGNOUT

      Defines the initial default Retain Signout action option value for Move and Transfer actions.

      Valid values are Y or N. The default is N.

      +EINE-DFLT-ACK-JUMP

      Defines the initial default Acknowledge Jump action option value for Move actions.

      Valid values are Y or N. The default is N.

      +EINE-DFLT-DEL-FROM

      Defines the initial default Delete from Element action option value for Move and Transfer actions.

      Valid values are Y or N. The default is Y.

      +EINE-DFLT-COPYBACK

      Defines the initial default Copyback action option value for Generate actions.

      Valid values are Y or N. The default is N.

      Note: The +EINE-DFLT-xxxxxx parameters are used to establish site specific initial default values presented on the Foreground and Batch Processing screens for the CA Endevor SCM Action Options: Signout Element, Replace if Present, Generate Element, Update if Present, With History, Retain Signout, Acknowledge Jump, Delete 'From' Element, and Copyback. If the user modifies the value of one of these Action Options on an EINE Processing screen, the user specified value is retained in the user's System Profile record. That retained value is used the next time the Action Option is presented.

      +EINE-DFLT-EW-FROM-DATE

      Defines the default value to be used for the package Execution Window From date field when a package is created.

      The default value of blank will cause the panel to display the current date in the Execution Window From date field.

      +EINE-DFLT-EW-FROM-TIME

      Defines the default value to be used for the package Execution Window From time field when a package is created.

      The default value of blank will cause the panel to display 00:00 in the Execution Window From time field.

      +EINE-DFLT-EW-TO-DATE

      Defines the default value to be used for the package Execution Window To date field when a package is created.

      The default value of blank will cause the panel to display 31DEC79 in the Execution Window To date field.

      +EINE-DFLT-EW-TO-TIME

      Defines the default value to be used for the package Execution Window To time field when a package is created.

      The default value of blank will cause the panel to display 00:00 in the Execution Window To time field.

      Note: The +EINE-DFLT-EW-xxxx-xxxx parameters are used to display default values for the package Execution Window From and To dates and times when a package is being created. These fields are not edited for content. If non-numeric values are coded for the Execution Window parameters, the user will need to enter valid execution window dates and times when creating a package. Usually, there is no need to provide a value other than blank for these parameters.

3. (Optional) Enable the CA Endevor Integration for the Natural Environment logon exit, UEXIT01, to customize any site specific logon procedures. UEXIT01 is called during the online session initialization and logon process. The exit is invoked after the user has logged on and their credentials have been authenticated, UEXIT00 has been initialized and validated, and processing of the Site Symbolics has completed. Use UEXIT01 to do the following:
   • Perform customized logon validation
   • Customize the job cards that are presented in the Batch Job
   • Customize the job cards that are presented in the Batch Job Submittal window specifically for the user logging on

     Note: The UEXIT00 +EINE-RESTRICT-JOBCARDS parameter can be used with this option to prevent users from modifying the job cards presented in the Batch Job Submittal window.

   • Abort a logon attempt

   To enable UEXIT01, the UEXIT00 +EINE-LOGON-EXIT-ENABLED parameter must be set to Y. You must provide and write the logon processing logic for UEXIT01 and STOW the UEXIT01 exit in the EINE install library. The exit contains the following fields. Edit the fields as appropriate for your site.

   • Input fields

     +UEXIT01-ENDEVOR-USER

     Contains a copy of the CA Endevor SCM user ID. The logged on CA Endevor SCM user ID cannot be changed. If +UEXIT01-ENDEVOR-USER is changed in the exit, the modification is ignored.

   • Input/Output fields

     +UEXIT01-BATCH-JOBCARD

     Contains a copy of the four job card records read from the EINE System Profile file for the loggedon user. These job card records can be modified by the exit and if the return code is set to a 4, the user's System Profile record is updated with them and they are presented to the user in the Batch Job Submittal window.

   • Output fields

     +UEXIT01-RETURN-CODE

     Specifies the action to be taken by EINE upon returning to the main login process.

     +UEXIT01-MESSAGE

     Specifies up to four text message lines that display on the UEXIT01 Abort Logon screen when the Return Code is set to 12.

     UEXIT01 Return Codes

     Specifies the action that the exit will perform depending on the return code received. Valid return codes for this exit are listed next. Place the appropriate code in the +UEXIT01-RETURN-CODE Independent variable field before returning.

     0— No updates made; proceed with logon.

     4— Modifications made, update the job card records in the user's System Profile record, and proceed with logon.

     12— Error; abort user logon.

     Any other value is treated as a Return Code 0

4. (Optional) Modify the CA Endevor Integration for the Natural Environment termination exit (UEXIT99) to add alternate or additional site-specific exit procedures. The termination exit, UEXIT99, is invoked (by fetch) when a user exits a session. By default, this user-exit program stacks a return command to provide for the user to be returned to the library from which the session originated.

   Modify UEXIT99 by logging on to the EINELIB Natural library, update UEXIT99 to your site requirements, and issue a STOW command. Once the modifications are complete and the exit STOWed, the EINE Servers must be shutdown and restarted.

   Note: If you are upgrading from Version 15.0 or Release 15.1 and saved your current UEXIT99 to a temporary Natural library, you can use it as a model for updating the Version 16.0 UEXIT99.

Example: Initialization Exit UEXIT00 Variable EINE SYSTRAN SYSOBJH Setting

When the initialization exit, UEXIT00, variable +EINE-SYSTRAN-SYSOBJH is set to O, Natural objects are unloaded in the SYSOBJH Internal format. The internal format includes the line numbers in hexadecimal with the unloaded objects. This causes CA Endevor SCM to identify lines as changed when only the line number changed as a result of lines being inserted or delete and the line numbers in the Natural object are automatically resequenced by the Natural editor. In this example, only the line in bold font was actually changed, but all lines thereafter are marked with a percent sign (%) to indicate that these lines changed also.

   +0100      ??*  MAINTENANCE HISTORY:                                  
   +0100      ? *                                                        
   +0100      ?&*  DATE    WHO WHAT                                      
   +0100      ?-*  ------- --- ------------------------------------------
   +0100      ?ø*  15MAR88 RSC                                           
   +0100      ?Ø*  02MAY89 RSC CHANGED P6.5 FMTS TO P8.3                 
   +0100      ?°*  16JUN98 JCH MODIFY FOR 4 DIGIT YEAR                   
   +0100      ? *  14MAR01 JCH INCREASE NAT-PGMID TO 22 BYTES            
  %+0101      ??*  12AUG13 JAA INSERTING TEST COMMENT LINE ONLY                              
  %+0101      ??*********************************************************
  %+0101      ??*       
  %+0101      ? DEFINE DATA                   
  %+0101      ?&  GLOBAL USING HIST-GDA       
  %+0101      ?-END-DEFINE                    
  %+0101      ?ø*                                                                              

When the UEXIT00 variable +EINE-SYSTRAN-SYSOBJH is set to F, Natural objects are unloaded with the SYSOBJH Transfer option. The transfer option does not include line numbers with the unloaded objects. This results in only the lines of Natural code that actually changed being identified as changed by CA Endevor SCM. In this example, only the line in bold font was actually changed and it is the only line marked with a percent sign (%) to indicate the line changed.

   +0100      *S***  MAINTENANCE HISTORY:                              
   +0100      *S***                                                    
   +0100      *S***  DATE    WHO WHAT                                  
   +0100      *S***  ------- --- --------------------------------------
   +0100      *S***  15MAR88 RSC                                       
   +0100      *S***  02MAY89 RSC CHANGED P6.5 FMTS TO P8.3             
   +0100      *S***  18JUN98 JCH MODIFY FOR 4 DIGIT YEAR               
   +0100      *S***  14MAR01 JCH INCREASE NAT-PGMID TO 22 BYTES        
  %+0101      *S***  14AUG13 JAA ADDED THIS COMMENT LINE ONLY          
   +0100      *S*******************************************************
   +0100      *S***                                                    
   +0100      *S***  THIS VERSION READS ALL NATL RECORDS WITHIN A TIME 
   +0100      *S***  REJECTS THOSE NOT NEEDED, DOES A -SORT- TO GET THE
   +0100      *S***  RECORDS INTO PGM SEQUENCE, THEN SUMMARIZES THE REC
   +0100      *S***  EACH NATURAL PROGRAM.                             
   +0100      *S***