User Exits

Each user has unique change management requirements that may vary from time to time, or with different situations or special circumstances.

PAC accommodates the user's needs by providing user exit facilities. Control can be passed to user-written Natural programs (user exit routines) to override the change management procedure defaults established by PAC.

The following sections describe PAC user exits in detail. Refer to the General Defaults Maintenance document in the PAC Administration documentation for information about displaying and modifying PAC user exits.

This document covers the following topics:


User Exit Groups

PAC groups its user exits as follows:

Group Members Description
General 1, 2, 33, 40 PAC initialization, termination; node security check
Maintenance 4, 8, 13-17, 19 - 21, 25, 26, 30, 38 Custom maintenance of PAC entities
Migration 5-7, 9-12, 23, 27, 28, 31, 32 Customized migration events
Reporting 18, 22, 24 Customized access to versioned object information
Special Use 34, 36, 37 Customize object purges in origin status with Move option; customize view generation for Predict migration, direct commands
Scan Utility 35 Exits for the scan utility
Migration Utility MIGEX003 (3) Exits for the migration utilities, file security
Not assigned: 29, 33, 39, 41-48  

Overview of Exits

This sectioncovers the following topics:

General Group

Exit Description
PACEX001 PAC initialization: invoked during the initialization of PAC; allows the user to pass a 50-byte parameter area throughout the session.
PACEX002 PAC termination: invoked during the termination of PAC; any required processing may be done in this routine.
PACEX033 PAC Activity Authorisation Exit; used if PAC runs unter security.
PACEX040 Security check for non-Natural datasets and nodes. When using Entire System Server to access a remote node, this exit allows you to specify a different user ID and password and the password for protected PDSs.

Maintenance Group

Exit Description
PACEX004 PAC entity purge validation: invoked before the deletion of a PAC entity; allows the user to interrogate the entity to be deleted before processing by PAC.
PACEX008 Application status library validation: invoked during the creation of application status links for a particular application; allows the user to validate the specific libraries assigned to each specific application status link.
PACEX013 Migration event name/access validation: invoked whenever any migration event maintenance function is invoked; can be used to implement audits and security.
PACEX014 Status name/access validation: invoked whenever any status maintenance function is invoked; can be used to implement audits and security.
PACEX015 Application name/access validation: invoked whenever any application maintenance function is invoked; can be used to implement audits and security.
PACEX016 File translation table name/access validation: invoked whenever any FTT maintenance function is invoked; can be used to implement audits and security.
PACEX017 Application status link access validation: called whenever any migration paths function is invoked; can be used to implement audits and security.
PACEX019 Maintenance request name/access validation: invoked during the processing of a maintenance request subfunction. Because information can be passed to or from the exit, maintenance request information can be verified or derived from an external problem-tracking system.
PACEX020 Maintenance request processing validation: invoked for maintenance request processing whenever any maintenance request function is invoked; allows the user to implement audits and security.
PACEX021 Maintenance request name verification: invoked to validate the maintenance request name attribute whenever a migration event is added or modified; may be used to implement audits and security.
PACEX025 Migration event names: invoked when function code A (Add) or C (Copy) is selected from the Migration Event Maintenance menu; allows the user to implement automated migration event name generation/ verification routines.
PACEX026 Verification of object list selection for Archiving: invoked during the onset of the generation of an object list for an Archive unload event; allows the user to set up and/or verify the criteria for selecting the objects to be archived.
PACEX029 Test Production Emigration: PACEX029 is called at the application of an FTT to a module being emigrated to a test or production location: once for each reference to a file in the module to which the FTT is being applied.
PACEX030 Event authorization verification: invoked before and after authorization begins; may be used to implement any required audits or security.
PACEX038 Event authorization verification: invoked before and after authorization begins; may be used to implement any required audits or security. Will replace PACEX030.

Migration Group

Exit Description
PACEX005 Locking objects: invoked before locking an object for out-migrations only as well as when the 'from-status' is CONTROL. Non-zero response value will reject the object from locking and taking no further part in the migration. Is invoked once for every object that is to be locked.
PACEX006 Compilation Error Verification: invoked after the compile processing step of the event is completed when any compilation errors are detected. Normally, PAC would force the event to abnormally terminate; however, this exit may be used to prevent the termination.
PACEX007 Change control list validation: invoked during the check-out of objects to a development/ maintenance type status and check-in from a development/maintenance type status, although change control logs are created only for the maintenance status type. The user may accept or reject the request to process each object in the event object list.
PACEX009 Verification of duplicate objects for migration. When PAC determines that the object being checked in from development or maintenance has the same date-time stamp as the most recent version in CONTROL, the object is treated as a duplicate. Normally, PAC creates a new version of all objects except copy code and text. This exit allows you to override PAC's decision to create a new version.
PACEX010 Object list verification: invoked for each entry in the object list when PAC is validating the objects to be processed for a migration event. As each entry in the object list is passed to the exit, the PAC administrator has the option to disallow that entry.
PACEX011 Job validation: called when a job maintenance subfunction is invoked; allows the user to implement tracking and customized security.
PACEX012 Job submission verification: invoked during JCL submission; passes the first 10 lines of JCL so that the user can examine them and make any desired changes or substitutions prior to job submission.
PACEX023 Object verification for autoexpand. During the Expand option processing of a migration event, this user exit is called before a particular object is expanded. PAC passes the object and the Expand option to the exit to be verified. The user may change the Expand option for the particular object or suppress the expansion of the object.
PACEX027 Verification of user substitution parameters for jobs: called whenever a batch job with user substitution parameters is submitted from PAC. Because it may be called before and after the substitution parameters are specified, the exit may be used to specify the default parameters before the job is presented to the user or for verification after the user has modified the job.
PACEX028 Migration audit report message verification: invoked during migration event processing, usually when a message is being written to the audit report; may optionally be used to suppress the writing of an audit message to the audit report.
PACEX031 Pass CATALL parameters to PAC: invoked prior to the CATALL; used for compiling objects in PAC during migrations from development or maintenance.
PACEX032 Reject objects for object list: invoked for each object elected by PAC during object list selection from the object list editor; used to reject objects based on a moving nonzero value for the MSG-NO parameter (Natural Optimizer Compiler).

Reporting Group

Exit Description
PACEX002 Object versions 'used by list' reporting. When the Expand option of a migration event is in effect during the processing of a migration event, PAC audits and passes for verification each subordinate object for the object being processed. This facilitates the expansion of objects defined across applications; that is, STEPLIB applications.
PACEX018 Object version reporting: invoked whenever any versioned objects reporting function is invoked; can be used to implement audits and security.
PACEX024 Reporting user exit to obtain the before and after images of a migration list.

Special Use Group

Exit Description
PACEX034 Verification of PAC direct commands: allows you to process a string of characters before it is submitted to PAC as a direct command.
PACEX036 Object origin deletion: When the Move option is in effect for a batch work file migration, this exit provides the ability to generate CMSYNIN cards to be used with a batch Natural utility (SYSMAIN, MIGUNLD) for purging objects in the origin status.
PACEX037 Predict generation: an interface exit that may be used to suppress the generation of views during Predict migrations. Additionally, in the case of files linked to multiple databases, allows you to override the database ID for which the generation must be performed. PAC uses information from the generation defaults to determine which default database to use. This is only valid for files linked to multiple databases.

Scan Utility Group

Exit Description
PACEX035 The scan utility exit, User Exit PACEX035, is invoked with the SCANOBJ utility for every object to be scanned in PAC.

Migration Utility Group

Exit Description
MIGEX003 Security check for Natural or Predict files: invoked whenever PAC needs to access a Natural or Predict file to retrieve or store Natural or Predict objects; allows the user to establish the password and cipher code to be used when PAC accesses these files.

Common Data Area used by all Exits

PAC user exits are delivered in library SYSPACUS and serve as an example only on how the user exit is to be coded.

All PAC user exits use a standard Parameter Data Area PACEXPDA, and it is explained in the table below:

Parameter Format Data Area
ENTITY-TYPE A1 Applic, Event, Status, Job
ENTITY-NAME A32 Name of Entity.
ENTITY-IDENTIFIER A32 Secondary ident for Entity.
ENTITY-FUNCTION A2 Function requested
RESP P5 Response code to PAC.
MSG A78 Message corresponding to RESP.
USER-AREA A50 User data for all exits.

PACEX001 - PAC Initialization

This user exit is invoked during the initialization of PAC, and allows the user to set up a 50-byte parameter area to be passed throughout the session.

Control must be restored to PAC at the termination of the exit.

Possible Use

  • Pre-initialization logic;

  • Additional security;

  • Accounting, logging, or tracking statistics.

Parameter

Parameter Format Description
USER-AREA A50 Modifiable; area for user to use

PACEX002 - PAC Termination

This user exit is invoked during the termination of PAC. Any required processing may be done in this routine. The user area, if set up in PACEX001, will be made available for use in PACEX002. Because the user area is passed to PACEX002 using a stack, an INPUT statement is required to access it.

The user will be at ET status on entry into the routine. Control may optionally be returned to PAC at termination of this exit.

Possible Use

  • Additional security;

  • Accounting, logging, or tracking statistics;

  • "Post-PAC" processing.

Parameter

Parameter Format Description
USER-AREA A50 Modifiable; area for user to use; passed via STACK Data.

PACEX004 - PAC Entity Purge Validation

This user exit is invoked before a PAC entity is purged, and allows the user to interrogate the entity to be purged before processing by PAC. The purge request may optionally be disallowed.

The user will be at ET status on entry into the routine. Control must be restored to PAC at the termination of the exit.

Possible Use

This exit can be used to interrogate the entity to be purged before processing by PAC.

Parameters

Parameter Format Description
ENTITY-TYPE A1 Not modifiable; the output is one of the following entity types:
-A Application
E Migration event
F File translation table
J Job
L Application status link
M Maintenance request
S Status
T Migration Path
ENTITY-NAME A32 Not modifiable; the output is the entity name; for example, the name of the status, event, or application.
ENTITY-IDENTIFIER A32 Not modifiable; the output is a secondary name to identify the entity; for example, the status name of an application status link.
ENTITY-FUNCTION A2 Not modifiable; the output is the requested function: P Purge entity
RESP P5 Input; return code. A non-zero return code disallows the purge function for the entity currently being processed.
MSG A78 Input; user message to be displayed when disallowing the purge function for an entity.
USER-AREA A50 Modifiable; area for user to use.

PACEX005 - Locking Objects at Migration Time

This user exit is invoked before the locking of an object, under the following two conditions:

  • For out-migrations (migrations with the to-status either of type (D) or (M)).

  • For migrations whose from-status is of type (C) Control.

A non-zero response value will stop the object being locked by PAC and thus excluding the said object from the migration. The user exit is invoked once for every object that is to be locked. If the response value is set to zero (0), PAC will process the object in the normal way.

Possible Use

When migrating objects out of PAC, the exit allows the user the opportunity to stop certain objects being migrated. If an event had already been created and authorized but the user wanted to stop a certain object from being migrated, without having to modify the event in any way, then this could be achieved with the use of this exit.

Parameters

Parameter Format Description
APPL A32 Not modifiable; name of the application for the event FM-STAT A32 Not modifiable; origin status name.
TO-STAT A32 Not modifiable; destination status name.
FM-STAT-TYPE A1 Not modifiable; origin status type.
TO-STAT-TYPE A1 Not modifiable; destination status type.
EVENT A32 Not modifiable; name of the event being processed.
OBJ A32 Not modifiable; object name.
OBJ-TYPE A4 Not modifiable; object type
OBJ-VERS N4 Not modifiable; object version.
RESP P5 Modifiable; response code.

PACEX006 - Compilation Error Verification

This user exit is invoked after the compile processing step of the event is completed when any compilation errors are detected. Normally, PAC would force the event to abnormally terminate; however, this exit may be used to prevent the termination.

If the error number (ERROR-NUM) is set to a non-zero value, it will instruct PAC to terminate processing abnormally as usual. The batch condition code will be 48. The Backout or Recovery functions may be performed normally. If necessary, the next step in the job may invoke a batch job to back out the event. When processing is terminated due to compile errors, this information is written to the event audit report.

If the error number is set to zero (0), PAC will not terminate the event and processing will continue.

Any required processing may be done in the routine. The user will not be at ET status on entry into the routine.

Possible Use

When migrating objects into PAC from development or maintenance status types, the object list may be an arbitrary list of objects or it may be a "unit of work" comprising a specific set of objects. In the latter case, it may be important for the event to be terminated and subsequently backed out if any of the objects are not successfully compiled.

By issuing a TERMINATE nn statement in the exit, or by leaving the error number as a non-zero value, the user may terminate the compile step of the migration with a specific condition code so that the next step in the JCL/JCS will be executed only if that condition code was received from the compile step. This conditional step may then be a batch command to PAC to back out the event that just failed.

Parameters

Parameter Format Description
USER-AREA A50 Modifiable; area for user to use
EVENT-NAME A32 Not modifiable; name of the event being processed
APPLICATION A32 Not modifiable; name of the application for the event
FROM-STATUS A32 Not modifiable; origin status name
FROM-STATUS-CODE A1 Not modifiable; origin status type
TO-STATUS A32 Not modifiable; destination status name
TO-STATUS-CODE A1 Not modifiable; destination status type
COMPILED-OBJECTS P8 Not modifiable; total objects compiled
ERROR-OBJECTS P8 Not modifiable; total objects not compiled
ERROR-MSG A32 Modifiable; error message text
ERROR-NUM P5 Modifiable; error message number

PACEX007 - Change Control List Verification

This user exit is invoked during the check-out of objects to and the check-in from a development or maintenance status type. The user has the option to process the information or to reject the request.

Note:
Since PAC currently does not support message switching facilities, it is recommended that you integrate your own message switching facilities. For example, use Con-nect from User Exit 7 (PACEX007) in the check-out/check-in process of PAC so that all users are correctly informed about check-out/check-in activities.

The parameter list provided with this exit allows you to customize the check-in and check-out processing to your exact requirements.

As each object is being processed for maintenance, the user is given the opportunity to verify the information. A non-zero response will instruct PAC not to accept the specific object for processing.

Control must be restored to PAC after processing in the exit is completed.

Because PACEX007 processing can be complex, it is recommended that you keep the logic in this exit simple by using subprograms to perform specific functions, depending on the FUNCTION or OPTION TYPE parameters.

A detailed explanation of the parameters for PACEX007 is included later in this section.

Possible Use

The exit may be used to verify the check-out of objects as follows:

  • Validate the user and the object being checked out, and optionally disallow the check-out; that is, restrict access to the object.

  • Disallow the check-out for a particular object.

  • Obtain reports using information about an object being checked out.

  • Get a list of other users who also may have previously checked out the same object (concurrent maintenance).

  • Validate the user and the object being checked in and optionally disallow the check-in.

  • Perform message switching logic to inform users of the checking in or checking out of an object.

  • Ensure that all maintenance activities have an associated maintenance request.

  • Attach comments or instructions to an object being checked in or out.

  • Validate the library where the object is being checked in or out for a user.

Parameters

Parameter Format Description
FUNCTION A1 Not modifiable; the function may be one of the following: I check-in
O check-out
OPT-TYPE A1 Not modifiable; the option type may be one of the following: blank self (first time call) C closed
D duplicate
I check-in of object
N object not checked out
O check-out of object
ACC-TYPE A1 Not modifiable; the type of access may be one of the following: A access only
C check-out request cancelled
D development type event called
U update
APPLICATION A32 Not modifiable; name of the application for the object
EVENT A32 Not modifiable; name of the migration event
MAIN-REQ-ID A20 Not modifiable; maintenance request ID
FROM-STATUS A32 Not modifiable; origin status
FROM-STATUS-
TYPE
A1 Not modifiable; origin status type
TO-STATUS A32 Not modifiable; destination status
TO-STATUS-TYPE A1 Not modifiable; destination status type
OBJECT-ID A32 Not modifiable; object currently being processed
CHECKOUT-
VERNO
P5 Not modifiable; check-out version number
CHECKOUT-
USER
A8 Not modifiable; identity of user who checked out the object
CHECKOUT-
DATE
T Not modifiable; date and time the object was checked out
CHECKOUT-TID A8 Not modifiable; identity of terminal from which the object was checked out
CHECKIN-
VERNO
P5 Not modifiable; check-in version number for closed logs only
CHECKIN-USER A8 Not modifiable; identity of user who checked in the object
CHECKIN-DATE T Not modifiable; date and time the object was checked in
CHECKIN-TID A8 Not modifiable; identity of terminal from which the object was checked in
MNT-LIBRARY A8 Not modifiable; destination library
MNT-DBID N5 Not modifiable; destination DBnr
MNT-FNR N5 Not modifiable; destination Fnr
COMMENT-01 A60 Modifiable; comment area
COMMENT-02 A60 Modifiable; comment area
COMMENT-03 A60 Modifiable; comment area
WORK-AREA A100 Modifiable; area for user to use
AUD-MSG A72 Modifiable; text of message to audit report
RESP N4 Modifiable; response code

Explanation of Parameters

FUNCTION

When objects are migrated to a (destination) maintenance status type, change control logs containing check-out information are created for each object being migrated. For migrations with an (origin) maintenance status type, the change control log is updated with check-in information for each object checked in from maintenance. No change control logs are created for migrations to or from a development status type. The following options are valid:

I Check-in function being performed on object.
O Check-out function being performed on object.

OPT-TYPE

Option type specifies the following:

blank Indicates the first time the exit is called for a particular object. At this point, the user may reject the object check-out/check-in based on the name of the object or the user invoking the request. For check-in, the user may wait to decide whether to reject the object until the exit is invoked again with a subsequent call (the exit is invoked with the I option or the N option if the object was not checked out before the check-in request).
C Closed. Indicates that the object being checked in was previously checked out and then checked back in (which closed the check-out log).
D Duplicate object. Indicates that the object being checked out was already checked out to this library with a previous migration event. This could occur when the wrong version was checked out or the version being checked out needs to be refreshed. This situation does not occur with check-ins. It is the user's responsibility to resolve inconsistencies that may occur when multiple versions of the same object are maintained at the same time. Depending on timing and circumstances, programmers may implement the same change in different ways and PAC has no way do determine this.
I In. Indicates that the log information being passed to the exit is for the object currently being checked in. This occurs only on check-ins and gives all of the check-out information about this object. I differs from the (blank) option in that the check-out information is not made available to the user with the (blank) option.
N Never checked out. Indicates that an object now being checked in was never checked out of PAC (for example, a completely new object with no versions in PAC, or a version of a PAC object that was created in development but is being migrated into PAC through maintenance).
O Out. Always indicates that the object is checked out. This may be seen with check-ins or check-outs. Thus, with a check-out, the user is informed about other users who have checked out this same object (but perhaps a different version). For check-ins, the user is informed about the user who still has this same object (but perhaps a different version) checked out. This information is stored in the audit report of the migration event.

ACC-TYPE

Access type informs the user whether or not the object has been modified after a check-out.

U Update. When the object is checked out, PAC always sets the access type to U (update) and is retained as a U if the object checked out was changed.
A Access. If PAC notes at check-in that the object checked out was not modified, then the access type is set to A (access).
C Cancelled. Occurs when an object was checked out for maintenance, but the request is being cancelled. This is only possible when the user is performing a migration from a maintenance (M) status type to a retire (R) status type.
D Development. This special access type, which can be ignored, occurs when users are migrating objects out of PAC to a development (D) status type. It allows the user to control programming changes between development and maintenance. For example, it may be useful for development to know of changes to objects in a maintenance environment so that the same changes may be made to the objects in the development environment. Where development and maintenance are the same environment, the D option is irrelevant. Alternatively, development may be disallowed if the object is in maintenance.

APPLICATION

This parameter identifies the application to which the object belongs. In PAC, all activities on objects are always performed at the application level.

EVENT

This parameter is the migration event being used for the processing of objects. If event naming standards are defined, the event name may help to determine whether or not the checking in or checking out of an object is valid.

MAIN-REQ-ID

This parameter may be useful to relate a particular migration to a specific problem. All objects being checked in and out will be assigned to that particular maintenance request thus making tracking easier. For example, it may be useful to disallow check-in or check-out of an object unless there is an associated maintenance request.

Status Parameters

FROM-STATUS origin status of the migration; that is, where the objects are being migrated from.
FROM-STATUS-TYPE origin status type.
TO-STATUS destination status of the migration; that is, where the objects are being migrated to.
TO-STATUS-TYPE destination status type.

OBJECT-ID

This parameter identifies the object currently being processed by PAC.

Check-Out Parameters

CHECKOUT-VERNO object version number of the object being checked out.
CHECKOUT-USER user who is checking out the object.
CHECKOUT-DATE date and time the object is being checked out.
CHECKOUT-TID terminal where the object is being checked out.

Check-In Parameters

CHECKIN-VERNO object version number of the object being checked in.
CHECKIN-USER user who is checking in the object.
CHECKIN-DATE date and time the object is being checked in.
CHECKIN-TID terminal where the object is being checked in.

Maintenance Parameters

MNT-LIBRARY maintenance library location to which the object was checked out, or the maintenance library location from which the object is being checked in. For example, if the migration is from production to maintenance, then PAC does not provide the location of production; that is, the origin status.
MNT-DBID database number of the maintenance library.
MNT-FNR file number of the maintenance library.

COMMENT

This parameter identifies the comments passed to the exit. Comments may be modified by the user, for example, to pass messages, reminders, or instructions to someone reviewing change control logs. This information may be set up during the check-out and then used as verification of the object during check-in.

WORK-AREA

The WORK-AREA parameter is a 100-byte area that the user may use during the processing of the exit. The work area may be set up when the exit is invoked for the first time (OPT-TYPE blank) and then used each time the exit is invoked for that particular object. PAC does not clear the area until the next object is processed.

AUD-MSG

If this parameter is set to a non-blank value, PAC will write the value as a message to the audit report.

RESP

This parameter tells PAC what to do with the object being processed.

  • A zero response indicates that there are no problems and processing can continue.

  • A non-zero response instructs PAC to reject the object.

If updates are performed on user-defined files during exit processing, the End Transaction (ET) is performed by PAC. If the user wants to write information to the job listing or to the screen, then this should be done in the exit itself.

PACEX008 - Application Status Library Validation

This user exit is invoked during the creation of application status links for a particular application. The exit allows the user to validate the specific libraries assigned to each specific application status link.

If the error number (ERROR-NUM) is set to a non-zero value, it will instruct PAC to not accept the specific library being validated. No END/BACKOUT TRANSACTION statements should be issued.

Any required processing may be done in this routine. The user will not be at ET status on entry into the routine.

Possible Use

Possible uses for this exit are as follows:

  • Restrict the assignment of a library for use by a specific application;

  • Assign automatic definitions for the value of a library and/or file and/or database for an application when it is linked to a status;

  • Override the default settings of the library, database, and file number when an application is linked to a status.

Parameters

Parameter Format Description
FUNCTION A1 Not modifiable; type of request: A add
M modify
APPLICATION A32 Not modifiable; name of application
STATUS A32 Not modifiable; name of status
STATUS-TYPE A1 Not modifiable; type of status
LIBRARY A8 Modifiable; library for link
DBID N5 Modifiable; database location of library
FNR N5 Modifiable; file location of library
XREF-FLAG A1 Modifiable; XREF usage indicator
ERROR-NUM P5 Modifiable; response code
MSG A78 Modifiable; text of message to be given to user
USER-AREA A50 Modifiable; area for user to use
EXTERNAL-USER A253 Optional; Input/output
EXTERNAL-CODEPAGE A64 Optional; Input/output

PACEX009 - Duplicate Object Verification

This user exit is invoked when PAC finds a duplicate object. The duplication is determined by comparing the date-time stamp of the development version with the most recent PAC version of the object.

Normally, PAC ignores duplicate versions of text and copy code object types only. The reason for this is that, while the saved objects may be identical, the cataloged objects may be different. The difference is caused by the external objects (data areas, copy code, views, and rules) used by the compiled object. Since the cataloged and saved objects must always be in sync, a new version must be created. PAC does not check the status of an object's external objects; therefore, it must create a new version of all objects except copy code and text.

The user may override PAC's decision by setting RESP-CODE as follows:

  • If RESP-CODE is set to zero, PAC processes the duplicate object;

  • If RESP-CODE is set to a non-zero value, PAC ignores the duplicate object.

    The user is at the End Transaction (ET) status on entry to the routine. Control must be returned to PAC when the exit terminates.

The following is the table of corresponding values for object types used by PAC. The value passed by PAC is the short text.

Code Short Text Long Text
C Copycd Copycode
T Text Text
G Global Global
L Local Local
A Param Parameter
P Progrm Program
S Subrtn Subroutine
N Subpgm Subprogram
H Help Helproutine
M Map Map
Z Record Recording
Y XpertM Xpert Model

Possible Use

Possible uses for this exit are as follows:

  • Override PAC to ignore or not ignore the creation of a new version of a particular object;

  • Establish different rules of duplication for each application according to object naming conventions, or the type of origin status.

Parameters

Parameter Format Description
PAC-STATUS A1 Not modifiable; origin status type: D development
M maintenance
PAC-APPLICATION A32 Not modifiable; application for the migration
OBJECT A8 Not modifiable; object being processed
OBJ-TYPE A15 Not modifiable; object type
OBJECT-DATE T Not modifiable; save date of the object
RESP-CODE N4 Modifiable; response code

PACEX010 - Object List Verification

This user exit is invoked during object list processing whenever an entry is processed from the object list of the event. This user exit is valid for all migrations.

As each entry in the object list is passed to the exit, the user has the option to disallow that entry by moving a non-zero response code to the RESP-CODE field. An entry is allowed with a zero response code. Control must be restored to PAC at the termination of the exit.

Possible Use

PACEX010 is called during the actual reading of the object list before PAC processes each entry on the list; for example:

SUBRTN1,S,
HELP*,M,PRODUCTION 

This allows the user to verify the following:

  • Use of range notation;

  • Use of references (version or status); these may be disallowed or restricted;

  • Use of certain types of objects (perhaps for exclusion);

  • Use of itemized objects to ensure that standards are satisfied with naming conventions; that is, that *, <, and > have not been specified for range notations;

  • Use of other external subsystems;

  • Secure the definition of which objects belong to which applications.

Parameters

Parameter Format Description
APPLICATION A32 Not modifiable; application name
FM-STATUS A32 Not modifiable; origin status name
TO-STATUS A32 Not modifiable; destination status name
EVENT A32 Not modifiable; migration event name
OBJECT A32 Not modifiable; object name
OBJ-TYPE A15 Not modifiable; object type text
STAT-VER A37 Not modifiable; status/version reference
EXIT-AREA A20 Not modifiable
REDEFINE EXIT-AREA  
  LIBRARY A8 Not modifiable; library of the From/To status (see note below)
DBID N5 Not modifiable; DBnr of the From/To status
FNR N5 Not modifiable; Fnr of the From/To status
RESERVED A4 Not used
FROM-STAT A1 Not modifiable; From status type
TO-STAT A1 Not modifiable; To status type
RESP-CODE N4 Modifiable; response code
DYN-CODE-OPTION A1 Optional; Output only
"S" dynamic source code option is specified

Note:
LIBRARY will contain the value of the library for the application status link of either the origin or destination status. If the object is being migrated into PAC, then this will be the library of the development, maintenance, or incorporation status. If the object is being migrated out of PAC, then it will be the library of the destination status.

PACEX011 - Job Validation

This user exit is called when a job maintenance subfunction is invoked to perform updates or access jobs defined to PAC.

Possible Use

This exit can be used to implement tracing and customized audit security.

Parameters

Parameter Format Description
ENTITY-TYPE A1 Not modifiable; the type of entity:
"J" job
ENTITY-NAME A32 Not modifiable; name of the job being processed
ENTITY-IDENTIFIER A32 Not modifiable; name of new job when ENTITY-FUNCTION is "C" or "R"
ENTITY-FUNCTION A2 Not modifiable; requested function:
"A" add job
"C" copy job
"D" display job
"E" edit JCL
"M" modify job
"R" rename job
"S" select job
"U" submit a job
RESP P5 Modifiable; return code. A non-zero value disallows the requested function for the job currently being processed
MSG A78 Modifiable; user message to be displayed when disallowing the requested function for the job currently being processed
USER-AREA A50 Modifiable; area for user to use

PACEX012 - Job Submission Verification

This user exit is invoked during JCL submission, and provides the first 10 lines of JCL so that the user may examine them and make any desired changes prior to job submission.

If job processing is to be terminated, then a non-zero response must be returned to PAC.

Possible Use

This exit can be used to enforce site-specified standards for performing various substitutions (for example, with jobs cards, account information).

Parameters

Parameter Format Description
USER-AREA A50 Modifiable; area for user to use
EVENT-NAME A32 Not modifiable; name of the event. This name is available when submitting JCL with the migration event Submit function
JCL A72/1:10 Modifiable; I/O JCL cards to be examined and optionally modified
ERROR-MSG A78 Modifiable; user message to be displayed when disallowing the Submit function for the job currently being processed
ERROR-NUM P5 Modifiable; return code. A non-zero value disallows the Submit function for the job currently being processed

PACEX013 - Migration Event Validation

This user exit is invoked whenever any option on the Migration Event Maintenance subfunction is invoked.

Possible Use

This exit can be used to implement audits and security.

Parameters

Note:
The ENTITY-FUNCTION (R), refresh event, cannot be used as an input parameter but if this is set when the "refresh" command is used, then the exit will be invoked.

Parameter Format Description
ENTITY-TYPE A1 Not modifiable; type of entity
"E" migration event
ENTITY-NAME A32 Modifiable; migration event name
ENTITY-IDENTIFIER A32 Modifiable; new migration event name
ENTITY-FUNCTION A2 Not modifiable; requested function:
"A" add an event
"C" copy an event
"D" display an event
"M" modify an event
"R" refresh an event
"S" select an event
"U" submit an event
RESP P5 Modifiable; return code. A non-zero value disallows the requested function for the migration event currently being processed
MSG A78 Modifiable; user message to be displayed when disallowing the requested function for the migration event currently being processed
USER-AREA A50 Modifiable; area for user to use

PACEX014 - Status Validation

This user exit is invoked when any option on the Status Maintenance subfunction is invoked.

Possible Use

This exit can be used to implement audits and security.

Parameters

Parameter Format Description
ENTITY-TYPE A1 Not modifiable; type of entity
"S" status
ENTITY-NAME A32 Not modifiable; status name
ENTITY-IDENTIFIER A32 Not used
ENTITY-FUNCTION A2 Not modifiable; requested function:
"A" add a status definition
"D" display a status definition
"L" link status to applications
"M" modify status definition
"S" select status
RESP P5 Modifiable; return code. A non-zero value disallows the requested function for the status currently being processed
MSG A78 Modifiable; user message to be displayed when disallowing the requested function for the status currently being processed
USER-AREA A50 Modifiable; area for user to use

PACEX015 - Application Validation

This user exit is invoked when an Application Maintenance subfunction is invoked to perform updates or access applications defined to PAC.

Possible Use

This exit can be used to implement tracing and customized audits and security.

Parameters

Parameter Format Description
ENTITY-TYPE A1 Not modifiable; the type of entity:
"A" application
ENTITY-NAME A32 Not modifiable; the name of the application being processed
ENTITY-IDENTIFIER A32 Not modifiable; new application name when ENTITY-FUNCTION is C
ENTITY-FUNCTION A2 Not modifiable; the requested function:
"A" add application
"C" copy application
"D" display application
"L" link application to a status
"M" modify application
"S" select application
RESP P5 Modifiable; return code. A non-zero value disallows the requested function for the application currently being processed
MSG A78 Modifiable; user message to be displayed when disallowing the requested function for the application currently being processed
USER-AREA A50 Modifiable; area for user to use

PACEX016 - File Translation Table Validation

This user exit is invoked whenever any option on the FTT Maintenance subfunction is invoked.

Possible Use

This allows the user to implement audits and security.

Parameters

Parameter Format Description
ENTITY-TYPE A1 Not modifiable; the type of entity:
"F" file translation table
ENTITY-NAME A32 Not modifiable; FTT name
ENTITY-IDENTIFIER A32 Not modifiable; new FTT name when ENTITY-FUNCTION is C
ENTITY-FUNCTION A2 Not modifiable; the requested function:
"A" add FTT
"C" copy FTT
"D" display FTT
"M" modify FTT
"S" select FTT
RESP P5 Modifiable; return code. A non-zero value disallows the requested function for the FTT currently being processed
MSG A78 Modifiable; user message to be displayed when disallowing the requested function for the FTT currently being processed
USER-AREA A50 Modifiable; area for user to use

PACEX017 - Application Status Link Validation

This user exit is invoked whenever any option on the Migration Paths subfunction is invoked.

Possible Use

This exit can be used to implement audits and security.

Parameters

Parameter Format Description
APPLICATION A32 Not modifiable; the application name
FM-STATUS A32 Not modifiable; origin status name
TO-STATUS A32 Not modifiable; destination status name
FUNCTION A2 Not modifiable; the requested function:
"A" add migration path
"D" display migration path
"M" modify migration path
"S" select migration path
RESP P5 Modifiable; return code. A non-zero value disallows the requested function for the migration path currently being processed
MSG A78 Modifiable; user message to be displayed when disallowing the requested function for the migration path currently being processed
USER-AREA A50 Modifiable; area for user to use

PACEX018 - Object Version Reporting

This user exit is invoked whenever any option on the Versioned Objects Reporting subfunction is invoked.

Possible Use

This exit allows the user to implement audits and security. For example, access to certain objects belonging to certain applications may be restricted to specific users.

Parameters

Parameter Format Description
ENTITY-TYPE A1 Not modifiable; the type of entity:
"V" object version
ENTITY-NAME A32 Not modifiable; application name
ENTITY-IDENTIFIER A32 Not modifiable; object name
ENTITY-FUNCTION A2 Not modifiable; the requested function:
"D" display versioned object
"H" hardcopy versioned object
"S" select versioned object
"U" list versioned objects with no application status
"V" display versioned object history data
RESP P5 Modifiable; return code. A non-zero value disallows the requested function for the object version currently being processed
MSG A78 Modifiable; user message to be displayed when disallowing the requested function for the object version currently being processed
USER-AREA A50 Modifiable; area for user to use

PACEX019 - Maintenance Request Validation

This user exit is invoked whenever ENTER is pressed when using a Maintenance Request subfunction.

Possible Use

This exit can be used as follows:

  • To move objects in and out of PAC;

  • To automate modifications to the maintenance request;

  • To retrieve information from an external problem-tracking system;

  • To perform audits or any automated processing, especially with an external problem-tracking system.

Parameters

Parameter Format Description
REQUEST-ID A32 Not modifiable; the maintenance request ID
REQUEST-ID-2 A32 Not modifiable; the new maintenance request ID when the FUNCTION is C (copy)
FUNCTION A1 Not modifiable; the requested function:
"A" add request ID
"C" copy request ID
"D" display request ID
"L" list by request ID
"M" modify request ID
"S" select request ID
PROBLEM-SUBJECT A60 Modifiable; subject of the problem
PROBLEM-TYPE A8 Modifiable; type of the problem
PRIORITY N3 Modifiable; priority
STATUS A12 Modifiable; status defined to PAC using Table Maintenance in administrator functions
ACTION A12 Modifiable; action defined to PAC using Table Maintenance in administrator functions
CONTACT-NAME A32 Modifiable; name of the contact person who reported or is responsible for the maintenance request
CONTACT-TEL A20 Modifiable; telephone number of the contact person
ERROR-NUM P5 Input; return code. A non-zero code disallows the requested function for the maintenance request currently being processed.
MSG A78 Input; user message to be displayed when disallowing the requested function for the maintenance request currently being processed
USER-AREA A50 Modifiable; area for user to use as set up by the PAC initialization exit

PACEX020 - Maintenance Request Processing Validation

This user exit is invoked when a Maintenance Request subfunction is invoked.

Possible Use

This exit can be used to implement tracing, audits, and/or customized security.

Parameters

Parameter Format Description
ENTITY-TYPE A1 Not modifiable; the type of entity:
"M" maintenance request
ENTITY-NAME A32 Not modifiable; the name (ID) of the maintenance request being processed. The first 20 characters are valid.
ENTITY-IDENTIFIER A32 Not modifiable; the new maintenance request name (ID) when ENTITY-FUNCTION is C. The first 20 characters are valid.
ENTITY-FUNCTION A2 Not modifiable; the requested function:
"A" add request ID
"C" copy request ID
"D" display request ID
"L" list by request ID
"M" modify request ID
"S" select request ID
RESP P5 Input; return code. A non-zero code disallows the requested function for the maintenance request currently being processed.
MSG A78 Input; user message to be displayed when disallowing the requested function for the maintenance request currently being processed
USER-AREA A50 Modifiable; area for user to use

PACEX021 - Maintenance Request Name Verification

This user exit is invoked whenever any modification of the Maintenance Request name is performed during migration event maintenance.

Possible Use

This exit allows the user to implement audits and security. It can be used to ensure the specification of a maintenance request whenever a migration event is created.

Parameters

Parameter Format Description
MAINTENANCE-REQUEST A32 Modifiable; name (ID) of the maintenance request
EVENT A32 Input; name of the migration event
APPLICATION A32 Input; name of the event's application
ORIGIN-STATUS A32 Input; name or the event's origin (From) status
DESTINATION-STATUS A32 Input; name of the event's destination (To) status
RESP P5 Input; return code. A non-zero code disallows the requested function for the maintenance request currently being processed
MSG A78 Input; user message to be displayed when disallowing the requested function for the maintenance request currently being processed
USER-AREA A50 Modifiable; area for user to use

PACEX022 - Object Version Used-By-List Reporting

This user exit is invoked whenever subordinates (maps, data areas, or copy code) in use by another object(s) are migrated from development or maintenance status types.

For objects compiled with the steplib option, this user exit identifies the application to which the object belongs so that when the subordinate changes, you can obtain a complete list across all applications of all objects that use that subordinate.

Possible Use

With Natural, objects using subordinates need not be recompiled until the objects affected by the subordinate change; this user exit can be used to warn the user that this change has taken place.

It can be used as well to write the list of affected objects to a work file for use in the generation of a subsequent migration event, thus automating the change to all objects using a particular subordinate. The work file dataset created by this exit can be used as input to the Generate function that creates another migration event, or it can be used to create the object list for an existing event.

Alternatively, the exit may be used to write the list of affected objects to a print file so that reports can be created that satisfy user requirements.

Parameters

Parameter Format Description
EVENT A32 Input; name of the migration event
APPLICATION A32 Input; name of the object's application
ORIGIN-STATUS A32 Input; name of the event's origin status
DESTINATION-STATUS A32 Input; name of the event's destination status
OBJECT A32 Input; name of the object
TYPE A4 Input; object type
VERSION N4 Input; object version
USED-BY-OBJECT A32 Input; name of the used-by object; that is, the object that uses the OBJECT as a subordinate object
USED-BY-TYPE A4 Input; object type of the used-by object
USED-BY-VERSION N4 Input; object version of the used-by object
USED-BY-APPLICATION A32 Input; application of the used-by object
USER-AREA A50 Modifiable; area for user to use

PACEX023 - Object Verification for Autoexpand

This user exit is called before a particular object is expanded. PAC passes the object name, type, version, and the Expand option to the exit.

Possible Use

The user may change the expand option for the particular object by modifying the Expand option value; or suppress the expansion of the object by returning a non-zero value in the return code field.

Parameters

Parameter Format Description
EVENT A32 Input; name of the migration event
APPLICATION A32 Input; name of the application
ORIGIN-STATUS A32 Input; name of the origin status
DESTINATION-STATUS A32 Input; name of the destination status
OBJECT A32 Input; name of the object
TYPE A4 Input; object type as specified in the object list
VERSION N4 Input; object version
EXPAND-OPTION A1 Modifiable;
"C" subordinate objects (compile time)
"E" subordinate and referenced objects
"N" no expansion
"R" referenced objects (run time)
"U" used-by objects
RETURN-CODE P5 Modifiable;
"zero" expand object
"non-zero" do not expand
USER-AREA A50 Modifiable; area for user to use

PACEX024 - Object Participation in Migration Reporting

This user exit lets you obtain a list of objects which come up for an in-migration or out-migration as a result of the interpretation of the migration list. It also is able to list objects whose in-migration or out- migration is still attempted after the restrictions imposed on the migration by various switches, applymods, and user exits have been taken into account.

Possible Use

The exit may be used during both Natural and Predict migrations.

The exit does not let you prohibit the migration of selected objects.

The exit is not used at any retirement or archiving migration.

The fact that an object has been cleared for the migration does not necessarily imply that the object makes it into the destination of the migration. For example, the compiling, which is part of an in-migration from a development or maintenance status takes place after the clearing. Likewise, all PAA activities formally follow the clearing and cannot be monitored through this exit alone.

In some cases, during the course of an out-migration, a PAC object may acquire an object-status link even though it is not migrated: for example, a data area listed for out-migration with Applymod 8 off. Such objects are not reported as cleared for out-migration.

Parameters

All fields are used only to pass values to PACEX024. Any modifications of these values in PACEX024 or in modules it may call are ignored.

Parameter Format Description
FUNCTION A2 Not modifiable. The function may be one of the following:
IB = an object is being reported as selected for an in-migration as a result of the interpretation of a migration list entry.
IA = an object is being reported as cleared for an in-migration.
EB = an object is being reported as selected for a out-migration as a result of the interpretation of a migration list entry or because of its participation in the in-migration part of the transmigration of which the current emigration is the latter part.
EA = an object is being reported as cleared for a out-migration.
EVENT A32 Not modifiable. Name of the migration event.
APPLICATION A32 Not modifiable. Name of the Application.
ORIGIN-STATUS A32 Not modifiable. Name of the from-status.
ORIGIN-TYPE A1 Not modifiable. Is the one character code of the type of the origin status of the migration. The possible values of ORIGIN-TYPE are:
'C' for 'CONTROL
''D' for 'development',
'I' for 'incorporation',
'M' for 'maintenance',
'P' for 'production',
'T' for 'test'.
DESTINATION-STATUS A32 Not modifiable. Name of the to-status.
DESTINATION-TYPE A1 Not modifiable. Is the one character code of the type of the destination status of the migration. The possible values of DESTINATION-TYPE are the same as those of ORIGIN-TYPE except 'I'.
OBJECT A32 Not modifiable; Name of the object being reported.
TYPE A4 Not modifiable. Is the code of the type of the object being migrated
VERSION N4 Not modifiable. Is the version number of the object being migrated. If FUNCTION = 'IB', it is 0; if FUNCTION = 'IA', it carries the version number of the PAC object that will be created if the in-migration is completed.

PACEX025 - Migration Event Names

This user exit allows the user to implement the routines for generating and verifying event names. It is invoked when function code A (Add) or C (Copy) is selected from the Migration Event Maintenance menu before the event name (entered by the user) is verified by PAC.

Since this exit is called before validation of the migration event name, the user may optionally leave the Event or the New Event field blank.

Possible Use

This user exit allows the user to implement the routines for automatically generating and verifying event names. It may be used to perform audit or security functions on existing events or it may be used to restrict the creation of an event.

Parameters

Parameter Format Description
ENTITY-TYPE A1 Not modifiable; the type of entity
"E" migration event
ENTITY-NAME A32 Modifiable; name of the migration event.
ENTITY-IDENTIFIER A32 Modifiable; new name of the migration event when the ENTITY-FUNCTION is C
ENTITY-FUNCTION A2 Not modifiable; requested function:
"A" add an event
"C" copy an event
RESP P5 Modifiable; return code. A non-zero value disallows the requested function for the migration event currently being processed
MSG A78 Modifiable; user message to be displayed when disallowing the requested function for the migration event currently being processed
USER-AREA A50 Modifiable; area for user to use

PACEX026 - Object List Selection for Archiving

This user exit interface provides criteria for selecting objects to be archived. The selected objects are added to the object list of an existing migration event. Only the selection criteria for archiving objects for a particular application are identified. User routine UMENARCH verifies the actual objects selected.

The exit is invoked using the ARCEVENT or Generate Archive List functions.

Note:
If an event is used, it must be an existing event; it must have a migration path Control to Archive; it must be in a pending or validated state; and its object list will be deleted.

Possible Use

This exist may be used to set up or override the archive selection criteria parameter values.

Parameters

Parameter Format Description
FUNC A1 Not modifiable; indicates when to select objects to be archived:
"A" after the exit is invoked
"B" before the exit is invoked
REDEFINE-OPTS A8 Options for archive processing
  1. DEF-TYPE A1 Modifiable; when FUNC is B (before), PAC can use either:
"A" the archive selection criteria defaults from the application
"U" the parameter defaults passed by the user exit
2. SHOW-MAP A1 Modifiable; show map for input (Y) or get parameters from exit (N):
"Y" show an input map to use when overriding parameter values passed by the exit
"N" do not show an input map
3. ARCEVENT A1 Modifiable; A = invoked by Archive; R = invoked by Retire Event
TO-STATUS A1 Modifiable; A = Archive; R = Retire
APPLICATION A32 Name of application to be processed
EVENT A32 Name of migration event to be used if the object list must be created
MIN-VERSION P2 Number of valid versions to be exempted from archiving; number begins with most recent; default is 3; minimum of three objects must remain.
RETENT-DAYS P3 Age of object, in days,before it can be selected for Archiving/Retiring; Zero (0) indicates no data checking
STATUS-CHECK A1 Modifiable; used in conjunction with STATUS-LIST when an object in a status is selected:
"Y" the default; ignore the selection of an object for archiving in a STATUS-LIST status
"N" archive the selected object
STATUS-LIST A6 Modifiable; if STATUS-CHECK is Y, this parameter contains the list of status types in which an object selected for archiving is ignored. The default list is as follows:
"P" production (any object in a production status is ignored)
"M" maintenance
"T" test
"A" Archive; that is, objects not yet purged
RESP-CODE N4 Not used

PACEX027 - User Substitution Parameter Verification

This user exit is called whenever a batch job with user substitution parameters is submitted from PAC.

Possible Use

PAC jobs may contain substitution parameters. This exit may be called before and after the substitution parameters are specified; thus the exit may be used to specify the default substitution parameters. These parameters will then be displayed to the user according to normal job substitution functionality; the user may then change them. Once the user has made the substitutions, the parameters may once again be passed to the exit for validation.

The user may need to perform additional processing (such as additional database calls or input parameters) within this exit to derive the values for the substitution parameters.

Parameters

Parameter Format Description
FUNC A1 Not modifiable; select objects to be archived before (B) or after (A) the exit is invoked
SUBS-CHAR A1 Not modifiable; JCL substitution character
SUBS-PARM A32/1:10 Not modifiable; names of substitution variables
SUBS-VALU A32/1:10 Modifiable; values of substitution variables
SUB1 P3 Input; parameter in error
USER-AREA A50 Modifiable; area for user to use
RESP P5 Input; error code
MSG A78 Input; error message

PACEX028 - Audit Report Message Verification

This user exit is invoked during migration event processing, usually when a message is being written to the audit report. This exit returns a non-zero response so that the user may optionally suppress the writing of an audit message to the audit report.

Any required processing may be performed in this routine; however, because the user may not be at ET status, control must always be returned to PAC to complete any internal processing.

Note:
The user should not write to the Natural work source area. That is, do not use the DEFINE PRINTER OUTPUT 'SOURCE' option.

Possible Use

In most cases, the messages written by the migration process invoke PACEX028 before they are written either to the audit report or to the printer. This allows the user to perform the following:

  • Instruct PAC to suppress the writing of the message to the audit report;

  • Print for the migration message, including headings;

  • Write additional messages to the report listing (not the actual audit report);

  • Change a message before it is written to the audit report;

  • Check for errors (E), cautions (C), and warnings (W); and optionally write these to an exception report, for example, CMPRT01;

  • Change the attributes of the message (for example, color, format).

Parameters

Parameter Format Description
EVENT-NAME A32 Not modifiable; migration event name
APPLICATION A32 Not modifiable; application name
FROM-STATUS A32 Not modifiable; origin status name
FROM-STATUS-CODE A1 Not modifiable; origin status type
FROM-LIBRARY A8 Not modifiable; origin status library name
FROM-DBID N5 Not modifiable; origin status library database number
FROM-FNR N5 Not modifiable; origin status library file number
TO-STATUS A32 Not modifiable; destination status name
TO-STATUS-CODE A1 Not modifiable; destination status type
TO-LIBRARY A8 Not modifiable; destination status library name
TO-DBID N5 Not modifiable; destination status library database number
TO-FNR N5 Not modifiable; destination status library file number
PRINT-IT A1 Modifiable; N Suppress = Print
ERROR-MSG A78 Not modifiable; error message text
ERROR-NUM P5 Modifiable; error message number

How to Use PACEX028

When the exit is invoked, do the following to suppress the message:

  1. Perform any special validation (for example, batch versus online processing, application, migration path).

  2. Set the response code ERROR-NUM to a non-zero value.

  3. Override the message, replace the contents of the ERROR-MSG field.

The format of all PAC error messages is as follows:

PACnnnn: (t) message-text

where:

nnnn is the message number
(t) is the message type:
E (errors)
C (caution)
W (warning)
A (audit)
I (information)
message-text is the actual message

Note:
Users should not write to the Natural work source area; that is, do not use the DEFINE PRINTER OUTPUT 'SOURCE' option.

The user may or may not be at ET status and no ET or BT should be issued from the exit; PAC does this.

Creating an Exception Report

An exception report for all errors can be created as follows:

FORMAT  (2)  LS=80 PS=0
IF ERROR-MSG = MASK (.........'(E)'    /* Is this an error message?
OR ERROR-MSG = MASK (.........'(C)'  /* Is this a caution message?
       WRITE (2) ERROR-MSG               /* Yes, write exception report to CMPRT02
END-IF

Color-Coded Reports

With color terminals, messages can be color-coded for reports of online migrations. For example:

Message Type Color

Audit messages Turquoise
Warnings Highlighted turquoise
Cautions Highlighted yellow
Errors Highlighted red

Alternatively, dynamic variables can be used for color-coding the message. For example:

.
.
.
REDEFINE ERROR-MSG
  MSG-PREFIX  (A8)
   MSG-DYN1  (A1)
  MSG-TYPE  (A3)
   MSG-DYN2  (A1)
.
.
.
MOVE '|' TO MSG-DYN1
MOVE '¬' TO MSG-DYN2
DECIDE ON FIRST VALUE OF MSG-TYPE
  VALUE '(A)' PRINT ERR-MSG  (CD=TU DY=|TU¬)
  VALUE '(W)' PRINT ERR-MSG  (CD=TU DY=|TUI¬)
  VALUE '(C)' PRINT ERR-MSG  (CD=TU DY=|YEII¬)
  VALUE '(E)' PRINT ERR-MSG  (CD=TU DY=|REI¬)
  ANY              MOVE 4 TO ERR-NUM       /*suppress message in PAC
  NONE            PRINT ERR-MSG  (CD=BL DY=|BLI¬)

Note:
The PAC audit report stores only the first 72 bytes of any message.

PACEX029 - Test Production Emigration

PACEX029 (if switched on) is called at the application of an FTT to a module being emigrated to a test or production location: once for each reference to a file in the module to which the FTT is being applied. FTTs are applied to modules migrated to production deployments by PAA, not by PAC. Therefore the switch which determines whether PACEX029 is to be called at an emigration to production is in the relevant FPAA, not in the ACF: it is the switch of PAA user exit 6.

The name of the subprogram to be called is still PACEX029, and it is the steplib chain of SYSPAA that determines which libraries and in what order are to be searched for the subprogram. PACEX029 is not called for modules which have no references to ADABAS files. PACEX029 is called regardless of whether the reference to a file is within the scope of any entry of the FTT being applied.

PACEX029 is called only once for each reference even if the reference is within the scope of several entries of the FTT and all of them are applied; in the latter case the values of NEW-DBNR and NEW-FNR are the net resulting ones. Only the values of MSG and RESP can be usefully modified by PACEX029.

If RESP is set at 0, then the processing will continue as it would with the user exit off. If RESP is set at 1, then 'PAC7382: (I) ' or 'PAA0087: (I) ' will be displayed or printed followed by [MSG], and the processing will continue. If RESP is set at anything else, then a message like that produced when RESP EQ 1 will be displayed or printed, and the processing will terminate, in batch with RC=055.

If an emigration to test is terminated with PACEX029, then the user should reckon with some migrating objects having been copied to the destination location(s) with the FTT applied and some not having been copied there - previous versions, if any, surviving.

For a workfile migration these two classes of objects will account for all migrating objects, the object that has caused the termination not having been copied. For a non-workfile migration the object that has caused the termination will be an only exception: it will have been copied untranslated.

A PACEX029-terminated emigration to test, whether UNDOne or RELEASEd, will leave the test location(s) with an inconsistent set of modules. Therefore users are advised not to immediately unlock PACEX029-terminated events to test.

Parameters

Name Format I/O
FTT A32 in
OBJECT A32 in
OBJ-LIBRARY A8 in
OBJ-DBNR N5 in
OBJ-FNR N5 in
OLD-DBNR N5 in
OLD-FNR N5 in
NEW-DBNR N5 in
NEW-FNR N5 in
MSG A72 out
RESP N4 out

How to Use PACEX029

Start of instruction setTo obtain a state functionally equivalent to the pre-emigration state:

  1. Create an event from the test status to RETIRE.

  2. Use GENLIST L, (N,N) to create its migration list.

  3. Create an event from CONTROL to the test status.

  4. Use GENLIST L, (H,Y) to create its migration list

  5. RELEASE the locked emigration event.

  6. Authorise and submit the just created retirement event.

Tip:
If the original, PACEX029-terminated event was a COPY (not MOVE) from a maintenance status, and applymod 8 or 19 was off, then it may be necessary to drop some entries from the migartion list of the retirement event; this should be done at the validation of the retirement event in response to messages complaining of the absence of objects in the origin status.

Start of instruction setTo keep in the test location(s):

To keep in the test location(s) the objects already copied there and successfully translated and to resume the emigration from the object that has caused the termination (presumably, after having corrected the FTT or assigned a different one):

  1. Create an event from the test status to RETIRE.

  2. Use GENLIST L, (N,N) to create its migration list.

  3. Delete the part of the list from, and including, the entry referring to the object that has caused the termination to the end of the list.

  4. Create an event from CONTROL to the test status.

  5. Use GENLIST L, (O,Y) to create its migration list.

  6. Delete the part of the list from its beginning to, but excluding, the entry referring to the object that has caused the termination.

  7. RELEASE the locked emigration event.

  8. Authorise and submit the just created retirement event.

Tip:
If the original, PACEX029-terminated event was a COPY (not MOVE) from a maintenance status, and applymod 8 or 19 was off, then it may be necessary to drop some entries from the migartion list of the retirement event; this should be done at the validation of the retirement event in response to messages complaining of the absence of objects in the origin status.

Tip:
If an emigration to production is terminated with PACEX029, then the user should reckon with all migrating objects having been copied (invisible) to the destination location(s) with the FTT(s) applied to some and not applied to the others. The object which has caused the termination will not have been translated. The PAA job will be Pending and its objects Scheduled; the previous versions of the objects, if any, will remain in place. The job will be fit only for purging. A PACEX029-terminated emigration to production should be UNDOne rather than RELEASEd; this, together with the purging of the PAA job, will return the system to almost the pre-emigration state (apart from some historical object - status links). Users are advised against trying to retire from production objects whose emigration has been terminated with PACEX029, especially if the PAA job has already been purged. There is no method of completing a PACEX029-terminated emigration to production without re-emigrating the objects successfully copied to and translated in the destination location(s).

Note:
Of the PACEX029-generated messages only 7382s will make it into the audit report and only if the emigration is not a workfile one.

PACEX030 - Event Authorization Verification

This user exit allows the user to implement additional controls for event authorization before it is actually authorized. The exit is invoked before and after authorization begins. Any required processing may be performed in this routine. The user will be at End Transaction (ET) status on entry into the routine.

Switch for Authorization: Alignment events (from CONTROL to CONTROL) and events of migrations from neighbour statuses to CONTROL provide a new tripositional switch - Catalogue - to be set at authorisation time. The field COPY-MOVE-INCLUDE is designated for double purposes. PACEX038 is PACEX030 enhanced.

Possible Use

  • Automatic override of parameters for certain authorizations;

  • Additional audit of the security checking for authorizations;

  • Set up of parameters not previously defined in the migration path.

Parameters

Parameter Format Description
FUNCTION A1 Input; indicates when the exit is to be invoked:
"A" after authorization begins
"B" before authorization begins
EVENT A32 Input; event name
APPLICATION A32 Input; event's application name
FROM-STATUS A32 Input; event's origin status name
TO-STATUS A32 Input; event's destination status name
JOB A32 Modifiable; job name for batch processing
EXPAND-OPT A1 Modifiable; Expand option:
"C" subordinate objects (compile time)
"E" subordinate and referenced objects
"N" no expansion
"R" referenced objects (run time)
"U" used-by objects
EXPAND-STATUS A1 Modifiable; name of the status to be used as the reference of expanded objects
BATCH-ONLINE A1 Modifiable;
"B" run the migration event in batch
"O" run the migration event online
COPY-MOVE A1 Modifiable;
"C" copy objects
"I" include objects
"M" move objects
WORKFILE-USAGE A1 Modifiable;
"Y" use work file
"N" do not use work file
APPLYMODS A50 Modifiable; applymod default settings (A/D/Y/N) are still enforced
SCHED-DATE T Modifiable; date/time the migration event is scheduled to run
TRANSLATION-TABLE A32 Modifiable; name of the file translation table to be used for the migration event
MSG-NO P5 Modifiable; error message number
MSG A78 Modifiable; error message text
USER-AREA A50 Modifiable; area for user to use

PACEX031 - Passing CATALL Parameters to PAC

This exit is invoked prior to CATALL during the migration of objects from development or maintenance. It allows you to pass CATALL parameters to PAC for use during the compile.

If "NOREN" is specified, the following CATALL will not renumber the lines of the sources which it compiles; it will renumber them if "NOREN" is not specified. If "NOSCROLL" is specified, the following CATALL will not scroll the list of compiled objects which it produces; it will scroll the list if "NOSCROLL" is not specified.

Parameter Format Description
APPLICATION A32 Input; name of the application
FROM-STATUS A32 Input; event's origin status name.
TO-STATUS A32 Input; event's destination status name.
PARM A50 Modifiable; "U" or "NOREN" or "NOSCROLL" or "NOREN,NOSROU"

PACEX032 - Rejecting Objects for Object List

This exist is invoked for each object selected by PAC during the selection of objects for the Object List from the Object List Editor. It is used to reject objects based on a moving non-zero value for the MSG-NO parameter (Natural Optimizer Compiler).

Parameter Format Description
EVENT A32 Input; the name of the event.
APPL A32 Input; the application of the event.
FM-STAT A32 Input; the origin of the event.
TO-STAT A32 Input; the destination of the event.
OBJ A8 Input; the name of the object.
OBJ-TYPE A4 Input; the type of the object.
OBJ-VERS N4 Input; the object's version number if the object resides in CONTROL compartment, 0 otherwise.
DATASET A54 Input; the name of the PDS from which the foreign object would be immigrated or deleted. Blank if the object is not foreign or the origin of the event is not of type incorporation, development, test, or maintenance or the event does not involve migration and is not of the type "retirement".
RESP P5 Modifiable; if not equal to 0, the object is rejected.
#URL A253 Filled only if FM-STAT type is External.
Optional; URL of the node/file
#NODE L Filled only if FM-STAT type is External.
Optional; true if the URL is a node

PACEX033 - Activity Authorisation Exit

This exit is a subprogramm that is used if PAC runs under security. To work under security, one has to set the Protection field within the System Defaults to 'Y'es, keeping the FSEC DBnr at 0 and the Fnr fields on the same defaults, by switching on the user exit 33.

PACEX033 will then be called whenever PAC has to ascertain that the user has the appropriate permissions for the activity he is trying to start. It will also be repeatedly called at the building time of lists whose entries refer to entities each of which may be differently accessible to the user.

Note:
A sample PACEX033 and a parameter data area, PACEXA33, are provided in SYSPACUS.

Parameter Format Description
USERID A8 User ID for which permissions are sought.
ACF-DBNR N5 Numbers of the ACF containing the entities for which permissions are sought.
ACF-FNR N5 Numbers of the ACF containing the entities for which permissions are sought.
KIND A1 Possible values are:

A: if application permissions are sought
J: if JCL text permissions are sought
T: if FTT permissions are sought

NAME A32 Contains the name of the application, JCL text or FTT.
QUEST L Contains TRUE in those cases when the elements which correspond to the permissions are sought. Here is the table of the various permissions which can be granted or denied for each (user,application), (user,JCL text), (user,FTT) pair.
Quest Application JCL Text FTT
0 reading reading reading
1 adding adding adding
2 modifying modifying modifying
3 deleting deleting deleting
4 event adding submitting  
5 event modifying    
6 event submitting    
7 event deleting    
QUEST (0:7)  
QUESTA A1 (0:7)  
QUEST    
QUESTB B1 (0:7)  
PERM L (0:7)  
PERM    
PERMA A1 (0:7)  
PERM    
PERMB B1 (0:7)  
MSG A72  
RESP N4  

PACEX034 - Direct Command User Exit

This exist is passed by the command line in chunks of alphanumeric 32 blocks.This exit is called before the validation of the command line. Any mocifications to the commands will be validated.

Possible Use

PACEX0034 can be used to pass site-specific syntax to PAC, for example ADD EVENT my be entered as CREATE LIST.

Parameter Format Description
COMMAND A32/36 Each command as entered.
MSG A78 Message.
RESP P5 Response code.

PACEX035 - SCANOBJ Utility

The scan utility exit, User Exit PACEX035, is invoked with the SCANOBJ utility for every object to be scanned in PAC.

Because SCANOBJ makes use of windows for online processing, caution should be used when issuing WRITE, PRINT, DISPLAY, or INPUT statements from within the user exit.

Possible Use

PACEX035 allows the user to perform security checking for each request and then for each object at the time the SCANOBJ utility is invoked.

Parameters

Parameter Format Description
FUNC A1 Not modifiable;
"I" the initial call for allowing a specific scan request
"S" the scan call for a specific object being called
APPLIC A32 Not modifiable; application name
OBJECT A8 Not modifiable; Natural object name
STATUS A32 Not modifiable; status name (set up by user). If empty, control will be used.
VERSION N4 Not modifiable; object version number
OBJ-TYPE A15 Not modifiable; object type
RESP N4 Input. Response code. If set not equal to 0, the object will be skipped for FUNC "S", and the whole Scan request will be stopped for FUNC "I".

PACEX036 - Object Origin Deletion

This user exit is used in a migration to synchronize objects in the origin status with PAC by creating the input data to be used for the deletion of objects at the origin status.

During the processing of the event, the objects in the origin status may be on another CPU or database and inaccessible to PAC. To synchronize the objects in the origin status with PAC, a job may be run at the location of the origin status.

This routine creates the input data to be used for the deletion at the origin status. The input data may be used as input to either SYSMAIN or NATUNLD. This exit is only invoked when the FROM-STATUS of the event is of type (T), and the TO-STATUS us either of type P, M or D .

Parameters

Parameter Format Description
REQUEST A1 Modifiable; F: first (initial) call; N: normal call; L: last call
OBJECT-LIB A8 Modifiable; name of the library in which the object resides
OBJECT-NAME A32 Modifiable; name of the object (only if N - i.e., "Normal")
OBJECT-TYPE A4 Modifiable; object type code (only if N - i.e., "Normal")
OBJECT-VER P5 Modifiable; version of the object (only if N - i.e., "Normal")
OBJECT-STATUS A32 Modifiable; origin status of the object
USER-AREA A50 Modifiable; area for user to use
PAC-ERR P5 Not modifiable; error message number

Example

SYSMAIN DELETE,STOWED,object-name IN LIBRARY object-library

PACEX037 - Predict Generation

This interface exit restricts the generation of DDMs/views or rules during Predict migrations and optionally verifies the database ID for files linked to multiple databases.

When each DDM/view to be generated is passed to this exit, the user may set the RESP code to a non-zero value to suppress the generation, and/or place a message in the MSG parameter for PAC to write into the audit report.

Additionally, in the case of files linked to multiple databases, the user may override the database ID for which the generation must be performed. PAC uses information from the generation defaults to determine which default database to use. This is only valid for files linked to multiple databases.

  • If the Specification DB-ID is set to N, the database ID is not used.

  • If the Specification DB-ID is set to Y and the database ID is set to blank, the Predict generation results in an error.

The user will be at End of Transaction (ET) status on entry into the routine. Control should be returned to PAC at termination of the routine.

Parameters

Parameter Format Description
FUNC A1 Not modifiable
OBJECT A32 Not modifiable; name of a view or rule
DATABASE-ID A32 Modifiable
OBJ-TYPE A15 Not modifiable; name of the object type
MSG A78 Modifiable; error message text
RESP N4 Modifiable; return doe number. If set to not equal to 0, the DDM will not be generated.

PACEX038 - Event Authorization Verification

This user exit allows you to implement additional controls for event authorization before it is actually authorized. The event is invoked before and after authorization begins. Any required processing may be performed in this routine. The user will be at End Transaction (ET) status on entry into the routine.

PACEX038 is first called "before first validation". FUNCTION = 'B' at this call. The subsequent activity will be of one of four kinds, the kind depending on the value PACEX038 puts into MSG-NO.

  • If MSG-NO is set at 0, then the PACEX038 specified values of the in/out fields replace the corresponding values of the event record fields and the authorisation continues as usual.

  • If MSG-NO is set at 1, then the PACEX038 specified values of the in/out fields replace the corresponding values of the event record fields and the authorisation continues without the Migration Event Authorisation screen being displayed and without confirmation being required.

  • If MSG-NO is set at 2, then the PACEX038 specified values of the in/out fields replace the corresponding values of the event record fields and the authorisation continues with the Migration Event Authorisation screen being displayed protected and with confirmation being required.

  • If MSG-NO is set at anything else, then the authorisation is aborted. At batch authorisation the four kinds are reduced to two: MSG-NO = 0 OR 1 OR 2 or not.

If confirmation is required but does not happen, then the authorisation is aborted.

If the authorisation has not been aborted, then PACEX038 may then be called an indefinite number of times online and once in batch "after first validation". FUNCTION = 'A' at this call. If PACEX038 puts 0 into MSG-NO at this call, then the authorisation will be finished.

If PACEX038 puts anything else into MSG-NO at this call online, then the Migration Event Authorisation screen will be displayed with confirmation being required.

If PACEX038 puts anything else into MSG-NO at this call in batch, then the authorisation is aborted. At PACEX038 "after" calls PAC disregards the values PACEX038 puts into the parameter fields other than MSG-NO. The "after" calls of PACEX038 will recur online as long as the user keeps confirming and PACEX038 keeps MSG-NO at non-0.

Switch for Authorization: Alignment events (from CONTROL to CONTROL) and events of migrations from neighbour statuses to CONTROL provide a new tripositional switch - Catalogue - to be set at authorisation time. The field COPY-MOVE-INCLUDE is designated for double purposes. PACEX038 is PACEX030 enhanced.

Possible Use

  • Automatic override of parameters for certain authorizations;

  • Additional audit of the security checking for authorizations;

  • Set up of parameters not previously defined in the migration path.

Parameters

Parameter Format Description
FUNCTION A1 in
EVENT A32 in
APPLICATION A32 in
STATUS-FM A32 in
STATUS-TO A32 in
BATCH-ONLINE A1 in / out
WORKFILE-USE A1 in / out
COPY-MOVE-INCLUDE A1 in / out
REPLACE A1 in / out
JOB A32 in / out
EXP-OPTION A1 in / out
EXP-STATUS A32 in / out
APPLYMODS A50 in / out
SCHED-TIME T in / out
FTT A32 in / out
MSG-NO P5 out
MSG A78 out
USER-AREA A64 in / out

PACEX040 - Remote Node and Dataset Security Check

PACEX040 is called whenever the current user does not have logon access to the requested Entire System Server node. It allows you to specify a different user ID and/or password and the password for protected PDSs.

Using PACEX040, you can

  • change the value of a USERID field and

  • specify the value of a PASSWORD field.

The authorization of the resulting pair to access the node is checked by PAC.

Parameter Format Description
FUNCTION A1 Input; constant "N".
NODE N3 Input; the number of the node being accessed.
DATA-SET-NAME A54 Input; the name of the dataset being accessed.
USERID A8 Input/modifiable; the current value of *INIT-USER. The ID to be used at the authorization check.
PASSWORD A8 Modifiable; the password for node access

MIGEX003 - File Security Check

Function

This exit is invoked whenever PAC needs to access a Natural or Predict file to retrieve or store Natural or Predict objects. This allows the user to establish the password and cipher code to be used when PAC accesses these files.

Remarks

Although this exit is defined as User Exit PACEX003, it is not invoked with this name; instead, exit MIGEX003 is invoked. This is because PAC comprises three subsystems loaded into libraries SYSPAC, SYSPAA and SYSTEM; and, in order to minimize the amount of maintenance, all three subsystems use exit MIGEX003 to obtain the password and cipher information needed to access the Natural/Predict system file.

Normally, when using Natural, passwords and cipher codes may be specified through the Natural parameter modules (for example, FNAT, FUSER, FDIC, NTFILE, SYSCIP, SYSPSW); however, depending on the user's security definition, this may not be adequate. MIGEX003 allows the user to provide the relevant password or cipher definitions for any and every file accessed by PAC. PAC passes the DBnr and Fnr of the file to be accessed so that the exit may return the corresponding password and cipher.

When the database and/or file number to be accessed by PAC must be translated to another database and/or file number, the exit may be used to perform the translation.

Parameters

Parameter Format Description
DBID N5 Modifiable; database ID number
FNR N5 Modifiable; file ID number
PSWD A8 Modifiable; password
CIPH A8 Modifiable; cipher