Coding Site-Specific Security Options

2
ce17
2
How to Define ESI Diagnostics
  If the LATSIZE parameter is coded in the ESI Defaults macro (ESIDFLTS) in your Name Equates table, the parameter is ignored for processing, but appears in the trace. PTF SO00990 made LATSIZE obsolete.
The ESI Defaults macro (ESIDFLTS) lets you specify how you manage ESI diagnostics. You can use the ESIDFLTS macro to write a diagnostic trace, to improve performance, and to enable warning mode.  For more information about tracing and warning mode, see ESI Trace Facility and ESI Warning Mode. The security lookaside table (LAT) feature lets you reduce the number of calls to the SAF interface, which improves performance. The result of each resource access request to SAF is stored in the LAT. ESI checks the LAT first for authorization and if the resource access request is listed, ESI does not call SAF.
If your site uses the
CA Endevor SCM
for CA Roscoe Interface option, do not use the LAT feature in
CA Endevor SCM
for the CA Roscoe environment.
We recommend that you use the default settings in the sample ESIDFLTS macro included with your installation kit. You can define only one ESIDFLTS macro in the Name Equates table. List the ESIDFLTS macro first. The following excerpt from a sample Name Equates Table shows the ESIDFLTS macro with the LAT feature enabled:
    ESIDFLTS TITLE='BC1TNEQU',                                   HEADER=ALL,                                          LATSIZE=5,                                           WARN=NO
To turn on or off the LAT feature, code the ESIDFLTS entry according to the following syntax:
 ESIDFLTS TITLE='
string
'  LATSIZE=
n
The format of the ESIDFLTS macro is listed next:
  • DESC=
    Specifies the descriptor codes that are used with the Write to Operator (WTO) messages when the trace is written to the operator console. WTO is the default if DESC= is not specified.
  • HEADER=(
    ALL/NONE
    )
    Specifies whether to write the header information to the trace destination when opening the EN$TRESI DD. ALL (or YES) specifies that the header is written. NONE specifies that header information is not written.
  • LATSIZE=
    n
    Specifies the number of 4K pages that are used to store access entries in the LAT. There are approximately 35 entries per 4K page. We recommend a LATSIZE setting from 2 through 10. LATSIZE=0 (default) turns off LAT. The maximum LATSIZE value is 524,287, which we do not recommend. When the LAT is full, new security calls are issued to SAF. The LAT size is allocated in each address space. To determine if the LAT space gets full often and should be increased, check the ESI trace facility.
  • ROUTECDE=
    Specifies the routing codes that are used with the WTO message when trace information is written to the operator console. The default is WTO if ROUTECDE= is not specified.
  • TITLE=
    Specifies a character string that is defined in the Name Equates Table. The title is displayed in the trace header. The default TITLE is 'No Title Specified'. The string 'BC1TNEQU' is added to the specified string.
  • WARN=(
    YES/NO
    )
    Specifies warning mode for the table. Individual formats can override the WARN= setting.
How to Define SAF Authorization Levels
When ESI issues a RACROUTE request using ACTION_INITIATION at the Action Initiation security control point or PACKAGE_ACTIONS at the Package Actions security control point, it determines the SAF authorization level (attr=
auth
) by checking the FUNCEQU entry.
ENVIRONMENT_ACCESS, PRIMARY_OPTIONS, and CONCURRENT_ACT_PROC are always issued with a READ request and cannot be modified through the Name Equates table.
     FUNCEQU SAFAUTH=READ,                                    +         C1ACTNS=(ADD,ARCHIVE,DELETE,                          +         DISPLAY,ENVRNMGR,GENERATE,MOVE,                       +         PBACKOUT,PCAST,PCOMMIT,PCREATE,PDISPLAY,PDYNAMIC,     +         PEXECUTE,PLIST,PMODIFY,PREVIEW,PSHIP,                 +         PUTILITY,RETRIEVE,SIGNIN,SIGNOVR,UPDATE)            FUNCEQU SAFAUTH=ALTER,                                   +                C1ACTNS=(ALTER)         FUNCEQU TYPE=END
To change the mapping of access level to authorization values for ACTION_INITIATION or PACKAGE_ACTIONS, code the FUNCEQU entry according to the following syntax:
 FUNCEQU SAFAUTH=(
auth
),  C1ACTNS=(
c1access
,
c1access
,...,
c1access
)
  • auth
    The SAF authorization value that is equated with the access level (
    c1access
    ). Valid 
    auth
     values follow:
    • NONE
    • READ
    • UPDATE
    • CONTROL
    • ALTER
  • c1access
    The access level that is equated with the SAF authorization value (
    auth
    ). Valid 
    c1access
     levels are:
    • ADD
    • ALTER
    • ARCHIVE
    • DELETE
    • DISPLAY
    • ENVRNMGR
    • GENERATE
    • MOVE
    • PBACKOUT
    • PCAST
    • PCOMMIT
    • PCREATE
    • PDISPLAY
    • PDYNAMIC
    • PEXECUTE
    • PLIST
    • PMODIFY
    • PREVIEW
    • PUTILITY
    • PSHIP
    • RETRIEVE
    • SIGNIN
    • SIGNOVR
    • UPDATE
You can associate each c1access value with only one auth value. For example, you cannot associate the GENERATE c1access value to READ and CONTROL auth values.
If you code an 
auth
 value of NONE, a security check (a RACROUTE request) is not issued for the
 c1access
 functions it covers. Omitting C1ACTN from the definitions results in a default assignment of NONE. Use NONE when a security check is not desired. For example, the following code results in no security with DISPLAY and RETRIEVE.
 FUNCEQU SAFAUTH=(NONE),                                     X           C1ACTNS=(DISPLAY,RETRIEVE)
Map Authorization Values
CA ACF2 and CA Top Secret users should be aware that a secondary mapping of the RACROUTE authorization value to security product equivalents occurs in the SAF interface that is supplied with each security product.
SAF Value
RACF Values
CA ACF2 Value
CA Top Secret Value
Read
Read
Read
Read
Update
Update
Write
Update
Control
Control
Write
Control
Alter
Alter
Allocate
Control
If you specify a value other than READ, you may need to update the SAF authorization when a new release of your site security package alters mapping values.
The required access level is determined at the action initiation security control point. CA ACF2 and CA Top Secret downgrade the control authority to UPDATE or WRITE for non-VSAM data sets. Consider this point when you set up ESI security rules.
Securing Actions Using the FUNCEQUE Entry
The FUNCEQU example in Defining SAF Authorization Levels shows a single level authorization. This level means that all MENUAUTH/ACTIONS are defined in the FUNCEQU entry with a single SAF value or attribute level of READ. When a user requests an action, the pseudo data set is built and is passed to the site security package. The user authorization level is returned to ESI and the user can invoke the action for as long as the user has READ access to the pseudo data set.
You can also secure actions by modifying the FUNCEQU entry. Actions should be logically grouped and mapped to different SAF values or attribute levels. When the ACTION_ INITIATION or PACKAGE_ACTIONS security control point is encountered, the pseudo data set is built and passed to the site security package. The use authorization level is returned to ESI and is compared to the SAF value coded for the action. If the user authorization level is equal to or greater than the level defined in the SAFAUTH parameter, the action is allowed. Otherwise, the action is denied.
The following example is of a modified FUNCEQU entry with four authorization levels:
     FUNCEQU SAFAUTH=READ,                                                  X         C1ACTNS=(RETRIEVE,SIGNIN,PDISPLAY,PLIST)      FUNCEQU SAFAUTH=UPDATE,                                                X         C1ACTNS=(ADD,UPDATE,GENERATE)      FUNCEQU SAFAUTH=CONTROL,                                               X         C1ACTNS=(MOVE,SIGNOVR,ARCHIVE,DELETE)      FUNCEQU SAFAUTH=ALTER,                                                 X         C1ACTNS=(ENVRNMGR,ALTER,                                            X         PCREATE,PCAST,PREVIEW,PEXECUTE, PDYNAMIC,                           X         PBACKOUT,PCOMMIT,PSHIP,PUTILITY)      FUNCEQU TYPE=END
To initiate a MOVE, SIGNOUT OVERRIDE, ARCHIVE, or DELETE action, the user must have control authority to the pseudo data set. Because DISPLAY is not explicitly coded in a FUNCEQU entry and therefore defaults to SAFAUTH=NONE, all users are granted DISPLAY access provided they pass other appropriate security control points.
How to Define SAF Name Formats
ESI determines data set name formats by checking the NAMEQU entry in the Name Equates Table. The following excerpt from the sample Name Equates Table shows the NAMEQU entries that create the ENTITY=dsname value that is used by the RACROUTE request.
     NAMEQU ENVIRONMENT_ACCESS,                                      +         L1=('C1'),                                                   +         L2=('ENVIRON'),                                              +         L3=(ENVIRONMENT)      NAMEQU PRIMARY_OPTIONS,                                         +         L1=('C1'),                                                   +         L2=(ENVIRONMENT),                                            +         L3=('PMENU'),                                                +         L4=(MENUITEM)      NAMEQU FOREGROUND_OPTIONS,                                      +         L1=('C1'),                                                   +         L2=(ENVIRONMENT),                                            +         L3=('FORACTN'),                                              +         L4=(MENUITEM)      NAMEQU ACTION_INITIATION,                                       +         L1=('C1'),                                                   +         L2=(ENVIRONMENT),                                            +         L3=(SYSTEM),                                                 +         L4=(SUBSYSTEM)      NAMEQU ACTION_INITIATION,                                       +         L1=('C1'),                                                   +         L2=(MENUAUTH) ***********************************************************************         *        SAMPLE SYNTAX FOR EXPLICIT CONTROL OF INDIVIDUAL ACTIONS    *         *        NOTE: MAKE SURE YOUR SECURITY RULES MATCH OR ARE GENERIC     *         ***********************************************************************         *              L3=(MENUITEM)                                                    ***********************************************************************         *        SAMPLE SYNTAX FOR THE ALTERFLD KEYWORD FOR THE ALTER ACTION  *         ***********************************************************************      NAMEQU PACKAGE_ACTIONS,                                         +         L1=('C1'),                                                   +         L2=('PACKAGE'),                                              +         L3=(MENUITEM),                                               +         L4=(PKGSUBFC),                                               +         L5=(PKGID)     NAMEQU CONCURRENT_ACT_PROC,                                      +         CLASS='DATASET',                                             +         WARN=NO,                                                     +         LOG=NONE,                                                    +         L1=('C1'),                                                   +         L2=('CAP')                                                
Each format (ENVIRONMENT_ACCESS through CONCURRENT_ACT_PROC) is defined only once within the Name Equates Table. (An optional second format is allowed for ACTION_INITIATION.)
Many installations have unique naming standards and index levels for data set names. ESI lets you customize data set names to conform to your site conventions. Additionally, you can establish your own security levels for any field.
These names only represent data set access rules. Physical data sets are not associated with these rules.
Change Names Generated at Security Control Points
To change the names that are generated at each security point, code the NAMEQU entry according to the following syntax:
 NAMEQU FORMAT,                                            X             Ln=(field1(begin,length),...fieldn(begin,length)), X             CLASS=classname,                                   X             LOG=(ASIS|NONE|NOFAIL|NOSTAT),                     X             WARN=(YES|NO)  NAMEQU TYPE=END
  • security call FORMAT
    The data set name format (ENVIRONMENT_ACCESS through CONCURRENT_ACT_PROC)
  • L
    n
    The index level of the data set name. Data set names are generated in the form of: L1.L2.L3.L4. The index levels generated are separated from other levels by a period (.). 
    n
     specifies a value from 1-10. The 
    fieldn
     values described next specify the index levels.
  • fieldn
     (begin, length)
    A literal or a CA Software Change Manager keyword which is placed into the specified index level. 
    Fieldn
     can be any literal of up to eight characters. Literals must be enclosed in single quotation marks. 
    (begin, length)
     is an optional parameter which allows you to specify a portion of a 
    CA Endevor SCM
     keyword. For more information about the 
    begin
     and 
    length
     parameters, see How to Specify a Substring of a Keyword.
  • classname
    The literal DATA SET or a user-defined resource class. DATA SET is the default if 
    classname
     is not coded. A 
    classname
     value other than DATASET may yield unpredictable results such as shortening the data set name. For more information, see How to Define a Class Other Than Data Set with RACF.
  • LOG=(ASIS| NONE| NOFAIL|NOSTAT)
    Specifies whether the security software at your site logs access attempts. The LOG parameter is used on the RACROUTE macro. SMF records written by site security as a result of the LOG parameter are in addition to, and separate from, 
    CA Endevor SCM
     written SMF records. The valid values are:
    • ASIS
      Records access attempts as specified by the operating system ADDSD and ALTDSD operator commands, or with the RDEFINE and RALTER commands for tape or DASD volumes (if the CLASS= parameter specifies something other than data set). ASIS gives the security package control over what is logged based on the profile AUDIT options, the user UAUDIT attribute, and SETROPTS LOGOPTIONS settings.
    • NONE
      Suppresses logging by site security package. Default.
      For example, use LOG=NONE if
      CA Endevor SCM
      is building a dynamic menu for a user. In this case, you want to perform security checks on each menu item. However, you do not want to write event failures for menu items that the user does not have security permission to access.
    • NOFAIL
      Records access attempts depending on authorization check results. Does not record an access attempt, if the authorization check fails. If the authorization check succeeds, the access attempt is recorded. When used with a site security AUDIT setting of FAILURES(READ), the site security does not log a successful authorization check
    • NOSTAT
      The access attempt is not recorded and resource statistics are not updated.
  • WARN= 
    (YES|NO)
    Specifies the local warning option. This parameter overrides the ESIDFLTS value. The YES option turns on warning mode for the resource name (the security control point). The NO option turns off warning mode. If 
    YES
     or 
    NO
     is not specified, the action defaults to the coding specified in the ESIDFLTS WARN option is not specified, the default value is
     WARN=NO
    . For more information, see ESI Warning Mode.
  • TYPE=END
    Indicates that the end of the name equates entries and can be specified separately or on the last NAMEQU FORMAT
    n
     entry.
How to Specify a Substring of a Keyword
You can specify a substring of a keyword, according to the following syntax:
Ln=(KEYWORD(B,L))
 
  • B
    The first character of the keyword (beginning column relative to one).
  • L
    The number of characters to extract from the keyword.
For example, to obtain a field value of FIN to represent a system that is named FINANCE, use the following code:
L1=(SYSTEM(1,3))
 
You can concatenate field values by specifying more than one field, each separated by a comma. For example, to obtain a field value of ENVIPROD to represent an environment that is named PRODUCTION, use the following code:
L2=('ENVI',ENVIRONMENT(1,4))
When data set names are generated, all trailing and embedded blanks are compressed. A value of '$' occurs in the index level of the name if the resulting index level is all blanks (that is, not available).
The following table lists the keywords and the formats for which the keywords are available.
Keyword
ENV
PRI
FOR
ACTS
PKG
CAP
ENVIRONMENT
X
X
X
X
 
 
ACTION
 
X
X
X
X
 
MENUITEM
 
X
X
X
X
 
MENUAUTH
 
X
X
X
X
 
SYSTEM
 
 
 
X
 
 
SUBSYSTEM
 
 
 
X
 
 
STAGEID
 
 
 
X
 
 
STAGENAME
 
 
 
X
 
 
STAGENO
 
 
 
X
 
 
TYPE
 
 
 
X
 
 
ELEMENT
 
 
 
X
 
 
ELM-10
 
 
 
X
 
 
CCID
 
 
 
X
 
 
PKGSUBFC
 
 
 
 
X
 
PKGID
 
 
 
 
X
 
PKGTYPE
 
 
 
 
X
 
PKGSTAT
 
 
 
 
X
 
PKGAPPGR
 
 
 
 
X
 
PKGBOE
 
 
 
 
X
 
PKGSHR
 
 
 
 
X
 
PKGPROM
 
 
 
 
X
 
The format names that are used in the table have been abbreviated as: ENVIRONMENT_ACCESS=ENV, PRIMARY_OPTIONS=PRI, FOREGROUND_OPTIONS=FOR, ACTION_INITIATION=ACTS, PACKAGE_ACTIONS=PKG and CONCURRENT_ACT_PROC=CAP.
A brief definition of each keyword follows:
  • ENVIRONMENT (1)
    The 
    CA Endevor SCM
     environment name
  • ACTION
    The 
    CA Endevor SCM
     access level for which a request is made. The ACTION keyword is interchangeable with the MENUAUTH keyword. The following values are valid for action: ADD, ALTER, ARCHIVE, DELETE, DISPLAY, ENVRNMGR, GENERATE, MOVE, PBACKOUT, PCAST, PCOMMIT, PCREATE, PDISPLAY, PEXECUTE, PLIST, PMODIFY, PREVIEW, PUTILITY, RETRIEVE, SIGNIN, SIGNOVR, UPDATE.
    For more information about how these access levels relate to the action being performed, see Default Authorization Value.
  • MENUITEM
    Allows individual line tailoring of the Primary Options menu, the Foreground Options menu, and the Package Actions menu.
    • When used with 
      PRIMARY_OPTIONS
       (Primary Options menu), the following values are valid: DISPLAY, FOREGRND, BATCH, PACKAGE, BATCHPKG, USER, ENVRMENT, LOAD, UNLOAD, RELOAD.  For more information about these values, see The Primary Options Security Control Point.
    • When used with 
      FOREGROUND_OPTIONS
       (Foreground Options menu), the following values are valid: DISPLAY, ADDUPDT, RETRIEVE, GENERATE, MOVE, DELETE, PRINT, SIGNIN. For more information about these values, see The Foreground Options Security Control Point.
    • When used with ACTION_INITIATION, the name of the action being performed. The following values are valid: ADD, ALTER, UPDATE, DISPLAY, RETRIEVE, GENERATE, MOVE, DELETE, PRINT, RESTORE, SIGNIN, TRANSFER LIST, ARCHIVE, VALIDATE.  For more information about these values, see The Action Initiation Security Control Point (Standard).
    • When used with 
      PACKAGE_ACTIONS
      , the following values are valid: BACKOUT, CAST, COMMIT, CREATE, DISPLAY, EXECUTE, MODIFY, REVIEW, UTILITY, DYNAMIC. For more information about these values, see The Package Action Security Control Point (Extension).
  • SYSTEM (1)
    The 
    CA Endevor SCM
     system name
  • SUBSYSTEM (1)
    The 
    CA Endevor SCM
     subsystem name
  • STAGEID (1)
    The 
    CA Endevor SCM
    1-character stage ID is taken from the STG1= and STG2= parameters in the C1DEFLTS TYPE=ENVIRONMENT section.
  • STAGENAME (8)
    The 
    CA Endevor SCM
    1-to 8-character stage name
    is taken from the STG1NME=and STG2NME= parameters in the C1DEFLTS TYPE=ENVIRONMENT section.
  • STAGENO (1)
    The 
    CA Endevor SCM
    1-character stage number. Valid values are 1 or 2.
  • TYPE (1)
    The 
    CA Endevor SCM
     element type
  • ELEMENT
    The first eight characters of the element name
  • ELEM-10
    The 10 characters of the element name
  • CCID
    The current change control identifier. A CCID can be up to 12 characters. If an SCL action statement for add, archive, delete, generate, move, restore, retrieve, transfer, or update specifies a CCID, that 
    ccid
     is used. If no CCID is specified, $ is substituted for the CCID field. If the action does not use a CCID (for example, display, signin, list, copy, or print), $ is substituted for the CCID field.
  • PKGSUBFC (2)
    The sub-menu function code in which the following values are valid:
    • ACTSUMM
    • ADD
    • APPROVE
    • APPROVER
    • BACKIN
    • BACKOUT
    • BUILD
    • CAST
    • COMMIT
    • CONFIRM
    • COPY
    • CORRINFO
    • DELETE
    • DENY
    • EABKO (Specifies Element Action Backout.)
    • EABKI (Specifies Element Action Backin.)
    • EDIT
    • EXECUTE
    • EXPORT
    • IMPORT
    • LIST
    • PACKAGE
    • REPORTS
    • RESET
    • SCL
    • STAGE
    • UPDATE
    • XMIT
  • PKGID (3)
    The 1-to-16-character user-defined package name
  • PKGTYPE (3, 4)
    Defines whether the package is emergency or standard:
    • STANDARD
    • EMERGENCY
  • PKGSTAT (3, 4)
    The package status:
    • IN-EDIT
    • IN-APPROVAL
    • DENIED
    • APPROVED
    • IN-EXECUTION
    • EXECUTED
    • EXEC-FAILED
    • COMMITTED
  • PKGAPPGR
    The approver group name
  • PKGBOE
    The backout-enabled status of the package (Y or N).
  • PKGSHR
    The share option that is associated with the package (Y or N).
  • PKGPROM
    Promotion package indicator (Y or N).
For the package symbolics, a value of '$' is substituted for the variable when the real value is not available to
CA Endevor SCM
. For example, before a CAST, the value for PKGAPPGR is a $.
(1) Up to eight characters in length.
(2) The value for PKGSUBFC always resolves to LIST when selecting an option from the package Foreground Options menu. These values are only available from the corresponding foreground panel. For example, PKGSUBFC is resolved to LIST when selecting option 3 from the package Foreground Options menu and CAST from the Cast panel.
(3) Each node in a data set name only allows a maximum of eight characters per value. PKGIDs can be up to 16 characters in length. Use substringing to limit the number of characters in the generated node, otherwise, security failures could result from what your security package may consider an invalid data set name. For example, coding pkgid(1,8) substitutes VERYLONG for pkgid VERYLONGPKGIDNAME.
(4) PKGSTAT and PKGTYPE values can be more than eight characters (z/OS only supports eight characters in a data set name node). By default, only the first eight characters of these fields are used (for example, IN-APPROVAL truncates to IN-APPRO, EMERGENCY truncates to EMERGENC). Follow these conventions when defining these profiles in your security package.
If the pseudo data set name is greater than 44 characters, it is automatically shortened.
Define a Class Other Than Data Set with RACF
The RACROUTE macro has a default value of DATASET for the CLASS parameter. Depending on the granularity of your site security rules, you could have many rules that belong in this category. Reduce the number of rules that are searched during authorization by creating an additional class category that is specific to ESI security rules. In this section, the resource class is named $ENDEVOR.
For the creation of resource classes, consult with your security administrator and, if necessary, IBM. The appropriate updates to your site IBM RACF class description table (CDT) depend on your site security software configuration. The configuration can be unrelated to
CA Endevor SCM
and therefore outside the scope of the product support team knowledge.
Follow these steps:
  1. Add the resource class name $ENDEVOR to the RACF class description table (CDT). 
    Use the following macro to create a class that is named $ENDEVOR.
     $ENDEVOR ICHERCDE  CLASS=$ENDEVOR,                                X            id=141,                                                 X            MAXLNTH=246,                                            X            FIRST=ALPHANUM,                                         X            OTHER=ANY,                                              X            POSIT=20,                                               X            RACLIST=ALLOWED,                                        X            DFTUACC=NONE,                                           X            OPER=NO  ICHRRCDE ICHERCDE      END /* //* //INSTL3  EXEC IPOSMPF, COND=(0,NE), //          CSI='MVSSMPF.GLOBAL.CSI' //SMPEIN  DD * SET BDY(GLOBAL). REJECT S(NRACCDT)BYPASS(APPLYCHECK). RECEIVE S(NRACCDT) SYSMODS. SET BDY(M220TAF).
    ESI supports resource names up to 246-bytes long. To use extended resource names, an installation-defined Class must be used. In addition, ensure that your site security package supports extended names.
  2. (This step is 
    not
     applicable for z/OS 1.6 and above). Add the entry in the following example to the RACF router table. The following processor executes these two steps.
    TAB16   ICHRFRTB   CLASS=$ENDEVOR,ACTION=RACF TABEND   ICHRFRTB   TYPE=END       END ICHRFR01 /*       //* //INSTL3 EXEC IPOSMPF,COND=(4,NE), //        CSI='MVSSMPF.GLOBAL.,CSI' //SMPEIN  DD *  SET BDY(GLOBAL)      B .  REJECT S(NRACRTT)      BYPASS(APPLYCHECK)  .  RECEIVE S(NRACRTT)      SSMODS .  SET DBY (M220TAF       .  APPLY S(NRACRTT)       REDO /* //SMPPTFIN DD       DSN=&&LOADSET.,DISP=(OLD,DELETE)
  3. Assemble the CDT and the router table and IPL the system.
  4. Activate the $ENDEVOR resource class using the RACF SETROPTS command. This step activates generic access checking for the resource class.
  5. Modify the Name Equates Table. The following sample shows the changes to make to the NAMEQU entries.
     NAMEQU ENVIRONMENT_ACCESS,                                           X         L1=('C1'),                                                    X         L2=('ENVIRON'),                                               X         L3=(ENVIRNOMENT),                                             X         
    CLASS='$ENDEVOR'
     NAMEQU PRIMARY_OPTIONS,                                              X         L1=('C1'),                                                    X         L2=('PMENU'),                                                 X         L3=(ENVIRONMENT),                                             X         L4=(MENUITEM),                                                X         
    CLASS='$ENDEVOR'
     NAMEQU FOREGROUND_OPTIONS,                                           X         L1=('C1'),                                                    X         L2=('FMENU'),                                                 X         L3=(ENVIRONMENT),                                             X         L4=(MENUITEM),                                                X         
    CLASS='$ENDEVOR'
     NAMEQU ACTION_INITIATION,                                            X         L1=('C1'),                                                    X         L2=(ENVIRONMENT),                                             X         L3=(SYSTEM),                                                  X         L4=(SUBSYSTEM),                                               X         L5=(MENUAUTH),                                                X         
    CLASS='$ENDEVOR'
     NAMEQU PACKAGE_ACTIONS,                                              X         L1=('C1'),                                                    X         L2=('PACKAGE'),                                               X         L3=(MENUITEM),                                                X         L4=(PKGSUBFC),                                                X         L5=(PKGID),         
    CLASS='$ENDEVOR'
    NAMEQU CONCURRENT_ACT_PROC,                                           X         L1=('C1'),                                                    X         L2=('CAP')                                                    X        
    CLASS='$ENDEVOR'
                                                   X 
Coordinating Access Levels, Menu Options, and Authorization Levels Using the RACROUTE Request
The RACROUTE request is derived from rules you define in the Name Equates Table. ENVIRONMENT_ACCESS through CONCURRENT_ACT_PROC coordinate access levels, menu options, and authorization levels with the site security packages (CA ACF2. CA Top Secret, RACF).
Formats are defined in the Name Equates Table, a portion of which is shown in the following example:
     NAMEQU ENVIRONMENT_ACCESS,                                 +         L1=('C1'),                                              +         L2=('ENVIRON'),                                         +         L3=(ENVIRONMENT)      NAMEQU PRIMARY_OPTIONS,                                    +         L1=('C1'),                                              +         L2=(ENVIRONMENT),                                       +         L3=('PMENU'),                                           +         L4=(MENUITEM)      NAMEQU FOREGROUND_OPTIONS,                                 +         L1=('C1'),                                              +         L2=(ENVIRONMENT),                                       +         L3=('FORACTN'),                                         +         L4=(MENUITEM)      NAMEQU ACTION_INITIATION,                                  +         L1=('C1'),                                              +         L2=(ENVIRONMENT),                                       +         L3=(SYSTEM),                                            +         L4=(SUBSYSTEM)      NAMEQU ACTION_INITIATION,                                  +         L1=('C1'),                                              +         L2=(MENUAUTH) ***********************************************************************         *        SAMPLE SYNTAX FOR EXPLICIT CONTROL OF INDIVIDUAL ACTIONS    *         *        NOTE: MAKE SURE YOUR SECURITY RULES MATCH OR ARE GENERIC     *         ***********************************************************************         *              L3=(MENUITEM)                                                    ***********************************************************************         *        SAMPLE SYNTAX FOR THE ALTERFLD KEYWORD FOR THE ALTER ACTION  *         ***********************************************************************         *              L4=(ALTERFLD)                                                    ***********************************************************************              NAMEQU PACKAGE_ACTIONS,                                    +         L1=('C1'),                                              +         L2=('PACKAGE'),                                         +         L3=(MENUITEM),                                          +         L4=(PKGSUBFC),                                          +         L5=(PKGID)      NAMEQU CONCURRENT_ACT_PROC,                                +         L1=('C1'),                                              +         L2=('CAP')                                              + 
Under each format entry, rules define parts of every RACROUTE request. The format defines how the pseudo data set is built. Variables in each rule appear without single quotes and literals appear within single quotes. The product substitutes the appropriate value for each variable.
  • Environments (
    ENVIRONMENT_ACCESS
    ):
     
    Restricts user access to environments. ENVIRONMENT_ACCESS calls are issued during 
    CA Endevor SCM
     initialization in foreground and batch.
  • Primary Options panel (PRIMARY_OPTIONS):
     
    The primary options panel is customized for each user who is based on the rules set up by the security administrator. Only options that the user can select are displayed on the Primary Options panel. PRIMARY_OPTIONS calls are issued before the Primary Options panel is displayed.
  • Foreground Options panel (FOREGROUND_OPTIONS):
     
    Only options that the user can select are displayed on the Foreground Options panel. FOREGROUND_OPTIONS calls are issued before the Foreground Options panel is displayed.
  • Action initiation (ACTION_INITIATION):
     
    Before an action, ESI requests a ruling to determine whether the user has the authorization for the action. ESI makes a pass for each defined ACTION_INITIATION format.
  • Action initiation (ACTION_INITIATION):
     
    The extension ACTION_INITIATION is an optional extension of the standard ACTION_INITIATION to allow for names longer than 44 bytes. This format is named only if the standard ACTION_INITIATION is successful.
  • Package actions (PACKAGE_ACTIONS):
    Before an action against a package, ESI requests a ruling to determine whether the user has the authorization for the action against the package.
  • Concurrent Action Processing (CONCURRENT_ACT_PROC):
     
    Before initiating (spawning) concurrent batch actions, ESI requests a ruling to determine whether the user has the authorization to use this facility. If the requestor does not have CAP access, an error message is issued and processing is terminated.
Environment Access Security Control Point
The Environment access security control point occurs at the following places:
  • During 
    CA Endevor SCM
     initialization, before display of the Environment Selection menu in the foreground and before processing of any actions in batch.
  • During LOAD utility operations to verify the user access to the desired inventory location.
  • During UNLOAD and RELOAD operations to reverify the user authority to backup and restore the desired inventory locations.
When the user changes environments in the foreground, the product looks up in the user accessible environments to see whether you have access to the environment. No ESI call is issued during this processing because it is unnecessary.
Use the Environment Selection menu to select an environment. Any other panel that displays the ENVIRONMENT field allows you to switch environments.
When the product starts under ISPF, ESI issues a RACROUTE request using ENVIRONMENT_ACCESS for each environment that is defined in the C1DEFLTS Table. Every authorized environment is then displayed on your Environment Selection menu.
Define rules for your site security package that is based on the ENVIRONMENT_ACCESS resource names. These rules determine which environments are accessible to the user and are displayed on the Environment Selection menu. You must have READ authority for each resource to gain access to the specified environment.
Example: ENVIRONMENT_ACCESS rules
This value becomes: C1.ENVIRON.
environment
, where 
environment
 is the name for which access is requested. If you have access to only one environment, the Environment Selection menu is not presented. If you do not have access to any environments, the product is not available.
 NAMEQU ENVIRONMENT_ACCESS,                                 X         L1=('C1'),                                          X         L2=('ENVIRON'),                                     X         L3=(ENVIRONMENT)
If you use environment mapping, you must also have access to all forward environments up the map.
The security administrator at a site with two environments (QA and PROD) wants to give a programmer access to both environments. To do so, define a data set access rule for the site security package that gives the programmer READ access to the data set names:
C1.ENVIRON.QA
  1. C1.ENVIRON.PROD
Primary Options Security Control Point
The Primary Options security control point occurs before building the Primary Options menu for the current environment in the foreground, after access is granted through the Environment Selection menu or during LOAD/UNLOAD/RELOAD.
Define rules for your site security package that is based on the PRIMARY_OPTIONS data set names to determine the options to be displayed on the user Primary Options menu. A user must have READ authority for each data set name to gain access to the specified primary option.
A sample of PRIMARY_OPTIONS rules is shown next:
 NAMEQU PRIMARY_OPTIONS,         L1=('C1'),         L3=('PMENU'),         L2=(ENVIRONMENT),         L4=(MENUITEM)
This value becomes: C1.
environment
.PMENU.
menuitem
  • environment
    The environment that you are trying to access
  • menuitem
    The corresponding Menu Item value.
Foreground Options Security Control Point
The Foreground Options security control point occurs before building the Foreground Options menu for the current environment in the foreground, after access is granted through the Primary Options menu.
Define rules for your site security package that is based on the FOREGROUND_OPTIONS data set names to determine the options to be displayed on the user Foreground Options menu. A user must have READ authority for each data set name to gain access to the specified foreground option.
The following sample is of FOREGROUND_OPTIONS rules:
 NAMEQU FOREGROUND_OPTIONS,         L1=('C1'),         L2=(ENVIRONMENT),         L3=('FORACTN'),         L4=(MENUITEM)
This value becomes: C1.
environment
.FORACTN.
menuitem
  • environment
    The environment that you are trying to access
  • menuitem
    The corresponding Menu Item value.
    The following lists the value and how the menu item is displayed:
    • DISPLAY
    • ADDUPDT (Item that is displayed as ADD/UPDATE)
    • RETRIEVE
    • GENERATE
    • MOVE
    • DELETE
    • PRINT
    • SIGNIN
This security point can only be reached if a PRIMARY_OPTIONS rule allows access to the Foreground Actions menu for the current environment.
FOREGROUND_OPTIONS rules do not apply to batch operations.
Example
The security administrator at a site with an environment named QA wants to give a programmer access to the ADD/UPDATE, RETRIEVE, PRINT, and SIGNIN options. To do so, define a data set access rule for the site security package (RACF, CA ACF2, and CA Top Secret) that gives the programmer READ access to the data sets:
  • C1.QA.FORACTN.ADDUPDT
  • C1.QA.FORACTN.RETRIEVE
  • C1.QA.FORACTN.PRINT
  • C1.QA.FORACTN.SIGNIN
Action Initiation Security Control Point (Standard)
The Action Initiation security control point occurs:
  • Before performing a product action.
  • Before a cast operation during package processing, for each action in a package, if the PKGCSEC flag is set to 
    Y
    .
  • Before an inspect operation during package processing, for each action in a package, if the PKGISEC flag is set to 
    Y
    .
  • During package verification processing.
Define rules for the site security package that is based on the ACTION_INITIATION data set names. These rules determine the 
CA Endevor SCM
 actions that the user can perform. A user must have the proper level of authority to each data set name (based on action) to gain access to the specified 
CA Endevor SCM
 action. 
Write rules to secure the source and target locations for ACTION_INITIATION.
Sample ACTION_INITIATION rules:
 NAMEQU ACTION_INITIATION,         L1=('C1'),         L2=(ENVIRONMENT),         L3=(SYSTEM),         L4=(SUBSYSTEM)
This value becomes: C1.
environment.system.subsystem
  • environment
    The environment that you are trying to access
  • system
    The system that you are trying to access
  • subsystem
    The subsystem that you are trying to access
Action Initiation Security Control Point (Extension)
The extension ACTION_INITIATION is an optional extension of the standard ACTION_INITIATION that can allow for names longer than the class attribute allows. Access to both ACTION_INITIATIONs is required. Write rules to secure the source and target locations for them.
This entity is only named if ACTION_INITIATION has RC=0.
Sample extension ACTION_INITIATION rules:
 NAMEQU ACTION_INITIATION,         L1=('C1'),         L2=(MENUAUTH)
This value becomes: C1.
menuauth
Where 
menuauth
 is the access level that is required for the requested action.
Example
This example demonstrates how the ACTION_INITIATIONs rules work together. Assume that you are a security administrator. Define data set access rules for your site security package. You have an environment that is named QA. You want to give a programmer access to a system named FINANCE and a subsystem named ACTSPAY. Additionally, limit the actions that the programmer can perform in the subsystem ACTSPAY to RETRIEVE and DISPLAY. To accomplish this task, write both ACTION_INITIATIONs rules. These rules grant the programmer READ access to these pseudo data sets:
  • C1.QA.FINANCE.ACTSPAY (ACTION_INITIATION)
  • C1.RETRIEVE (ACTION_INITIATION)
Default Authorization Value
The 
authorization
 value for each RACROUTE request is translated in the following table. The table reflects the delivered sample BC1TNEQU table that is described in the Name Equates Table.
If no FUNCEQU macro entry is specified for an action, it defaults to SAFAUTH=NONE, meaning that there will be no security call for this action.
When you determine the authorization access for a user, check the "Access level required" column to ensure that you are not incorrectly giving users access to activities.
To Perform this Activity
Access Level Required
SAF Authorization Level
Add
Add
READ
Update
Update
READ
Retrieve
Retrieve
READ
Generate (Stage 1 or Entry stage)
Generate
READ
Generate (Stage 2 nonentry
Move
READ
Move (from Stage 1 or Entry Stage) (1)
Move
READ
Move (from Stage 2 nonentry) (1)
Move
READ
Move (to Stage 1 or Entry Stage)
Add
READ
Move (to Stage 2 nonentry)
Move
READ
Display from selection list
Display
READ
Browse
Retrieve
READ
Delete (Stage 1 or Entry Stage)
Delete
READ
Delete (Stage 2 nonentry)
Move
READ
Signin
Signin
READ
Print
Display
READ
Transfer (to Stage 1 or Entry Stage)
Add/Update
READ
Transfer (to Stage 2 nonentry)
Move
READ
Transfer (from Stage 1 or Entry Stage with Delete)
Delete
READ
Transfer (from Stage 2 nonentry with Delete)
Move
READ
Transfer (from Stage 1 or Entry Stage without Delete)
Retrieve
READ
Transfer (from Stage 2 nonentry without Delete)
Retrieve
READ
Alter
Alter
ALTER
Archive
Archive
READ
Restore to Stage 1 or Entry Stage
Add
READ
Restore to Stage 2 nonentry
Move
READ
Copy
None
READ
List
Display
READ
Signout Override (2)
Signovr
READ
Validate
Display
READ
Actions against any elements of type processor (3)
Envrnmgr
READ
(1) If in-house security is designed to expect the move action to issue a security call at the target location, do a security check at the target location during the move processing. To do so, activate ENHOPT SEC_MOVE_TARGET=ON in the ENCOPTB
(2) Signout override is always the second call in an action. The first call is the specific action involved - Add or Delete, for example - and, if necessary, the call for signout overrid is performed.
(3) When performing actions against type processors, two calls are issued. The first call checks whether the user can perform the specific action that is involved, such as Add or Delete. If the user can perform that action, the second call is issued for access level ENVRNMGR to see if the user also has permission to work with type processors.
Package Actions Security Control Point
The Package Actions security control point occurs before performing a package action.
Define rules for the site security package that is based on the PACKAGE_ACTIONS data set names. These rules determine the 
CA Endevor SCM
 actions the user can perform. You must have the proper level of authority to each data set name (based on action) to gain access to the specified 
CA Endevor SCM
 action.
Write rules to secure the source and target locations for PACKAGE_ACTIONS.
The following are sample PACKAGE_ACTIONS rules:
 NAMEQU PACKAGE_ACTIONS,         L1=('C1'),         L2=('PACKAGE'),         L3=(MENUITEM),         L4=(PKGSUBFC),         L5=(PKGID)
This becomes: C1.PACKAGE.
menuitem.pkgsubfc.pkgid
  • menuitem
    Allows individual line tailoring of the Primary Options menu. 
    • BACKOUT
    • CAST
    • COMMIT
    • CREATE
    • DISPLAY
    • EXECUTE
    • MODIFY
    • REVIEW
    • SHIP
    • UTILITY
  • Pkgsubfc
    The submenu function code or action (for example, CREATE allows you to build, import, export).
    • ACTSUMM
    • ADD
    • APPROVE
    • APPROVER
    • BACKIN
    • BACKOUT
    • BUILD
    • CAST
    • COMMIT
    • CONFIRM
    • COPY
    • CORRINFO
    • DELETE
    • DENY
    • EABKO
      Specifies Element Action Backout.
    • EABKI
      Specifies Element Action Backin.
    • EDIT
    • EXECUTE
    • EXPORT
    • IMPORT
    • LIST
    • PACKAGE
    • REPORTS
    • RESET
    • SCL
    • STAGE
    • UPDATE
    • XMIT
    The value for 
    pkgsubfc
     resolves to LIST when selecting an option from the package Foreground Options menu. These values are only available from the corresponding foreground panel. For example, menuitem is resolved to LIST when selecting option 3 from the package Foreground Options menu and CAST from the Cast panel.
  • pkgid
    The user-defined package name
The NAMEQU macro supports the FORMAT=PACKAGE_ACTION entry with the new symbolics required to build the model name. The format of the model name is variable, but can include the following specific package symbolics:
  • PKGSHR
    The share option that is associated with the package:
    • Y
    • N
  • PKGPROM
    Promotion package indicator:
    • Y
    • N
  • PKGBOE
    The backout-enabled status of the package:
    • Y
    • N
  • PKGAPPGR
    Approver group name
  • PKGSTAT
    The package status:
    • IN-EDIT
    • IN-APPROVAL
    • DENIED
    • APPROVED
    • IN-EXECUTION
    • EXEC-FAILED
    • EXECUTED
    • COMMITTED
    Status names can be more than eight characters long (z/OS only supports eight characters in a data set name node). Use substringing to limit the number of characters in the generated node. By default, the value is the first eight characters of the status name (for example, IN-APPROVAL shortens to IN-APPRO).
  • PKGTYPE
    Defines whether the package is emergency or standard:
    • STANDARD
    • EMERGENCY
    Each node in a data set name only allows a maximum of eight characters per value; therefore, values greater than eight characters are truncated to eight characters (for example, EMERGENC).
PACKAGE_ACTIONS ESI Calls
The following table displays some of the rules that are built for this sample. The pseudo data set names varies depending on how your PACKAGE_ACTIONS NAMEQU is configured. No security exists for the Notes subfunction.
Menuitem/ Subfunction
FUNCEQU Name
Sample Pseudo Data Set Security Rule
C1.PACKAGE.
menuitem.pkgsubfc.pkgid
BACKOUT
Backout
Display
Backin
PLIST
PBACKOUT
PDISPLAY
PBACKOUT
C1.PACKAGE.DISPLAY.LIST.PKG001
C1.PACKAGE.BACKOUT.BACKOUT.PKG001
C1.PACKAGE.DISPLAY.BACKOUT.PKG001
C1.PACKAGE.BACKOUT.BACKIN.PKG001
CAST
Cast
SCL
PLIST
PCAST
PDISPLAY
C1.PACKAGE.DISPLAY.LIST.PKG001
C1.PACKAGE.CAST.CAST.PKG001
C1.PACKAGE.DISPLAY.SCL.PKG001
Concurrent Action Processing Security Control Point
The Concurrent Action Processing Security Control Point occurs before the dispatch of the first element action that is eligible for concurrent processing. This point only occurs if the user has requested Concurrent Action Processing.
If concurrent action processing is requested for a batch job, a batch package execution or for an API execution, the ESI issues a RACROUTE request using CONCURRENT_ACT_PROC to determine if the user has access to this facility.
Define a rule for your site security package that is based on the CONCURRENT_ACT_PROC data set name. This rule determines if the concurrent action processing facility is accessible to the user. A user must have READ authority for the data set name to be able to request CAP processing.
Example: CONCURRENT_ACT_PROC rule
A sample concurrent action processing rule is shown next:
NAMEQU CONCURRENT_ACT_PROC,          X                  L1=('C1'),          X                  L2=('CAP')
This rule becomes: C1.CAP
How to Enable ESI
This section explains how to enable ESI, which is supplied on the installation tape. Perform this procedure after the product is installed and verified.
  1. Prepare your security worksheet.
  2. Define rules for your site security package.
  3. Customize the Name Equates Table (Formats ENVIRONMENT_ACCESS through CONCURRENT_ACT_PROC).
  4. Assemble and link-edit the Name Equates Table (BC1TNEQU).
  5. Assemble and link the Defaults Table (C1DEFLTS).
  6. Test ESI security using warning mode.
How to Prepare Your ESI Security Worksheet
To begin planning your ESI security strategy, gather information about all the users and applications for which you are responsible. Determine how users and applications relate to each other and how detailed you want your security strategy to be.
We recommend using an ESI worksheet to help you define and categorize the various levels of access that is required by anyone that is involved in application development. After you complete your ESI worksheet, begin defining access levels.
Keep an updated version of your ESI worksheet available for reference purposes. If you change your Names Equates table or your site security package rules, update your ESI worksheetl. Use the worksheet to:
  • Associate authorization levels with personnel or departments.
  • List activities to include for selected departments in Stages 1 and 2 of each environment.
  • Review when updating or revising your security rules.
How to Define Security Rules for Your Site
The following section contains sample procedures that describe the steps to determine security rules for your site. The procedures describe steps for defining the following security rules:
  • Site environment rules
  • Primary Options panel rules
  • Foreground action rules
  • Action initiation rules
  • Package action rules
  • Concurrent action processing rule
Blank worksheets for defining security rules are provided in Security Worksheets.
Define Security Rules for Your Site Environments
Follow these steps:
  1. Plan a diagram of the flow for your site environments and label each box with the name of your environments.
    The following example shows a site where parallel development occurs between environments DEV1 and DEV2.
    Security v17
    Security v17
     
  2. Plan a table that lists your environments in the far left column and the users at your site along the top row. In the following example, an X indicates that a user has security access.
    Envr
    Appl Pgmr
    Appl Mgr
    Other Depts
    QA
    Prod Ctl
    Tech Supp
    Audit
    Admin
    DEV1
    X
    X
     
     
     
    X
     
    X
    DEV2
    X
    X
     
     
     
    X
     
    X
    PROD
    X
    X
    X
    X
    X
    X
    X
    X
  3. Determine the format for your environment security rules. To generate a pseudo data set name in the format 'C1'.'ENVIRON'.
    environment
    , set up the NAMEQU entry in the Name Equates Table using this format:
    NAMEQU ENVIRONMENT_ACCESS,  L1=('C1'),  L2=('ENVIRON'),  L3=(environment)
  4. Determine the pseudo data set names that are based on the format that is described in Step 3 and the environments that are entered in Step 2.
Env
AP
AM
OD
QA
PC
TS
AU
AD
Data Set Names
DEV1
X
X
 
 
 
X
 
X
C1.ENVIRON.DEV1
DEV2
X
X
 
 
 
X
 
X
C1.ENVIRON.DEV2
PROD
X
X
X
X
X
X
X
X
C1.ENVIRON.PROD
User access to data sets in indicated with an X. You must have read access to the data sets to have environment access.
User Abbreviations
These abbreviations are used in the security table's column heading to describe the users:
  • AD - Administration
  • AM - Application Management
  • AP - Application Programming
  • AU - Audit
  • OD - Other Departments
  • PC - Production Control
  • QA - Quality Assurance
  • TS - Technical Support
Define Security Rules for the Primary Options Panel
Follow these steps:
  1. Plan a table that lists the Primary Options panel menu items in the far left column and the users at your site along the top row. In the following example, an X indicates that a user has access to a menu item.
    Menu Item
    AP
    AM
    OD
    QA
    PC
    TS
    AU
    AD
    DISPLAY
    X
    X
    X
    X
    X
    X
     
    X
    FOREGROUND
    X
    X
     
     
     
    X
     
    X
    BATCH
    X
    X
     
     
     
    X
     
    X
    PACKAGE
     
     
     
    X
    X
    X
     
    X
    USERMENU
     
     
     
    X
    X
    X
     
    X
    ENVIRONMENT
     
     
     
     
     
    X
     
    X
    LOAD (Batch action only)
     
     
     
     
     
     
     
    X
    UNLOAD (Batch action only)
     
     
     
     
     
     
     
    X
    RELOAD (Batch action only)
     
     
     
     
     
     
     
    X
    BATCH PACKAGE
    X
    X
     
    X
    X
    X
     
    X
  2. Determine the format for your Primary Options panel security rules. To generate a pseudo data set name in the format
     
    'C1'.environment.'PMENU'.
    menuitem
    , set up the NAMEQU entry in the Name Equates Table using this format:
    NAMEQU PRIMARY_OPTIONS,  L1=('C1'),  L2=(environment),  L3=('PMENU'),  L4=(menuitem)
  3. Determine the pseudo data set names based on the format described in Step 2 and the menu items indicated with an X in Step 1.
Menu Item
AP
AM
OD
QA
Data Set Names
DISPLAY
X
X
X
X
C1.DEV1.PMENU.DISPLAY
FOREGRND
X
X
 
 
C1.DEV1.PMENU.FOREGRND
BATCH
X
X
 
 
C1.DEV1.PMENU.BATCH
PACKAGE
X
X
 
 
C1.DEV1.PMENU.PACKAGE
USER
X
X
 
X
C1.DEV1.PMENU.USER
ENVRMENT
 
 
 
 
C1.DEV1.PMENU.ENVRMENT
LOAD (Batch action only)
 
 
 
 
C1.DEV1.PMENU.LOAD
UNLOAD (Batch action only)
 
 
 
 
C1.DEV1.PMENU.UNLOAD
RELOAD (Batch action only)
 
 
 
 
C1.DEV1.PMENU.RELOAD
BATCH PACKAGE
X
X
 
X
C1.DEV1.PMENU.BATCHPKG
Menu Item
PC
TS
AU
AD
Data Set Names
DISPLAY
X
X
 
X
C1.DEV1.PMENU.DISPLAY
FOREGRND
 
X
 
X
C1.DEV1.PMENU.FOREGRND
BATCH
 
X
 
X
C1.DEV1.PMENU.BATCH
PACKAGE
X
X
 
X
C1.DEV1.PMENU.PACKAGE
USER
X
X
 
X
C1.DEV1.PMENU.USER
ENVRMENT
 
X
 
X
C1.DEV1.PMENU.ENVRMENT
LOAD (Batch action only)
 
 
 
X
C1.DEV1.PMENU.LOAD
UNLOAD (Batch action only)
 
 
 
X
C1.DEV1.PMENU.UNLOAD
RELOAD (Batch action only)
 
 
 
X
C1.DEV1.PMENU.RELOAD
BATCH PACKAGE
X
X
 
X
C1.DEV1.PMENU.BATCHPKG
User access to data sets is indicated with an X in the previous example. You must have access to the data sets to have access to the Primary Options Panel actions.
Define Security Rules for Your Foreground Options Panel
Follow these steps:
  1. Plan a table that lists the Foreground Options panel menu items in the far left column and the users at your site along the top row. In the following example, an X indicates that a user has access to a menu item.
    Menu Item
    AP
    AM
    OD
    QA
    PC
    TS
    AU
    AD
    DISPLAY
    X
    X
    X
    X
    X
    X
     
    X
    ADD/UPDATE
     
     
     
     
     
     
     
    X
    RETRIEVE
    X
    X
     
     
     
    X
     
    X
    GENERATE
     
     
     
     
     
     
     
    X
    MOVE
     
     
     
     
     
     
     
    X
    DELETE
    X
     
     
    X
    X
    X
     
    X
    SIGNIN
    X
     
     
    X
    X
    X
     
    X
    PRINT
    X
     
     
    X
    X
    X
     
    X
  2. Determine the format for your Foreground Options panel security rules. To generate a pseudo data set name in the format 'C1'.
    environment.
    'FORACTN'.
    menuitem
    , set up the NAMEQU entry in the Name Equates Table using this format:
    NAMEQU FOREGROUND_OPTIONS,  L1=('C1'),  L2=(environment),  L3=('FORACTN'),  L4=(menuitem)
  3. Determine the pseudo data set names that are based on the format that is described in Step 2 and the menu items that are indicated with an X in Step 1.
Menu Item
AP
AM
OD
QA
Data Set Names
DISPLAY
X
X
X
X
C1.DEV1.FORACTN.DISPLAY
ADD/UPDATE
 
 
 
 
C1.DEV1.FORACTN.ADDUPT
RETRIEVE
X
X
 
 
C1.DEV1.FORACTN.RETRIEVE
GENERATE
 
 
 
 
C1.DEV1.FORACTN.GENERATE
MOVE
 
 
 
 
C1.DEV1.FORACTN.MOVE
DELETE
 
 
 
 
C1.DEV1.FORACTN.DELETE
SIGNIN
X
X
 
X
C1.DEV1.FORACTN.SIGNIN
PRINT
X
X
 
X
 
Menu Item
PC
TS
AU
AD
Data Set Names
DISPLAY
X
X
 
X
C1.DEV1.FORACTN.DISPLAY
ADD/UPDATE
 
 
 
X
C1.DEV1.FORACTN.ADDUPT
RETRIEVE
 
X
 
X
C1.DEV1.FORACTN.RETRIEVE
GENERATE
 
 
 
X
C1.DEV1.FORACTN.GENERATE
MOVE
 
 
 
X
C1.DEV1.FORACTN.MOVE
DELETE
X
X
 
X
C1.DEV1.FORACTN.DELETE
SIGNIN
X
X
 
X
C1.DEV1.FORACTN.SIGNIN
PRINT
X
X
 
X
C1.DEV1.FORACTN.PRINT
User access to data sets is indicated with an X in the previous table. You must have READ access to the data sets to access to the Foreground Options panel actions.
Define Security Rules for Action Initiations
Follow these steps:
  1. Design a table that lists the action initiation items in the far left column and the users at your site along the top row. In the following example, an X indicates that a user has access to the action.
    Action
    AP
    AM
    OD
    QA
    PC
    TS
    AU
    AD
    DISPLAY
    X
    X
    X
    X
    X
    X
     
    X
    ADD
    X
    X
     
     
     
    X
     
    X
    UPDATE
    X
    X
     
     
     
    X
     
    X
    RETRIEVE
    X
    X
    X
     
     
    X
     
    X
    GENERATE
    X
    X
     
     
     
    X
     
    X
    MOVE
     
     
     
    X
    X
    X
     
    X
    DELETE
     
     
     
    X
    X
    X
     
    X
    SIGNIN
    X
    X
    X
     
     
    X
     
    X
    SIGNOUT/
    OVERRIDE
     
    X
     
     
     
    X
     
    X
    ARCHIVE
     
     
     
     
     
    X
     
    X
    ALTER
     
     
     
     
     
     
     
    X
    RESTORE
     
     
     
     
     
    X
     
    X
    PROCESSORS
     
     
     
    X
    X
     
     
    X
  2. Determine the format for your action initiation security rules. To generate a pseudo data set name in the format
     
    'C1'.environment.system.subsystem.menuauth, set up the NAMEQU entry in the Name Equates Table using this format:
    NAMEQU ACTION_INITIATION,         L1=('C1'),         L2=(environment),         L3=(system),         L4=(subsystem),         L5=(menuauth)
    For a table showing the default authorization value for each RACROUTE request, see The Default Authorization Value. In addition, ensure that you are not giving users access to activities that you do not want them to access.
  3. Determine the pseudo data set names that are based on the format that is described in Step 2 and the actions that are indicated with an X in Step 1.
Action
AP
AM
OD
QA
PC
TS
AU
AD
Data Set Names
DISPLAY
X
X
X
X
X
X
 
X
C1.DEV1.FINANCE.*.DISPLAY
ADD
X
X
 
 
 
X
 
X
C1.DEV1.FINANCE.*.ADD
UPDATE
X
X
 
 
 
X
 
X
C1.DEV1.FINANCE.*.UPDATE
RETRIEVE
X
X
X
 
 
X
 
X
C1.DEV1.FINANCE.*.RETRIEVE
GENERATE
X
X
 
 
 
X
 
X
C1.DEV1.FINANCE.*.GENERATE
MOVE
 
 
 
X
X
X
 
X
C1.DEV1.FINANCE.*.MOVE
DELETE
X
X
 
X
X
X
 
X
C1.DEV1.FINANCE.*.DELETE
SIGNIN
X
X
X
 
 
X
 
 
C1.DEV1.FINANCE.*.SIGNIN
SIGNOUT/
OVERRIDE
 
X
 
X
 
X
 
X
C1.DEV1.FINANCE.*.SIGNOVR
ARCHIVE
 
 
 
 
 
X
 
X
C1.DEV1.FINANCE.*.ARCHIVE
ALTER
 
 
 
 
 
 
 
X
C1.DEV1.FINANCE.*.ALTER
PROCESSORS
 
 
 
 
 
X
 
X
C1.DEV1.FINANCE.*.ENVRNMGR
Your access to data sets is indicated with an X. You must have READ access to the data sets to access actions. For a description of column headings, see User Abbreviations.
Define Security Rules for Your Package Actions Panel
Follow these steps:
  1. Plan a table that lists the Package Actions panel menu items in the far left column and the users at your site along the top row. In the following example, an X indicates that a user has access to a menu item.
    Menu Item
    AP
    AM
    OD
    QA
    PC
    TS
    AU
    AD
    DISPLAY
    X
    X
    X
    X
    X
    X
     
    X
    CREATE
     
     
     
     
     
     
     
    X
    MODIFY
    X
    X
     
     
     
    X
     
    X
    CAST
     
     
     
     
     
     
     
    X
    REVIEW
     
     
     
     
     
     
     
    X
    EXECUTE
    X
     
     
    X
    X
    X
     
    X
    BACKOUT
    X
     
     
    X
    X
    X
     
    X
    COMMIT
    X
     
     
    X
    X
    X
     
    X
    UTILITY
    X
     
     
    X
    X
    X
     
    X
    SHIP
     
     
     
     
     
     
     
    X
  2. Determine the format for your Package Actions panel security rules. To generate a pseudo data set name in the format 'C1'.'PACKAGE'.
    menuitem.pkgsubfc.pkgid
    , set up the NAMEQU entry in the Name Equates Table using this format:
     NAMEQU PACKAGE_ACTIONS,         L1=('C1'),         L2=('PACKAGE'),         L3=(menuitem),         L4=(pkgsubfc),         L5=(pkgid)
  3. Determine the pseudo data set names that are based on the format that is described in Step 2 and the menu items that are indicated with an X in Step 1.
Menu Item
AP
AM
OD
QA
PC
TS
AU
AD
Data Set Names
DISPLAY
X
X
X
X
X
X
 
X
C1.PACKAGE.DISPLAY.APPROVER.PKG001
CREATE
 
 
 
 
 
 
 
X
C1.PACKAGE.CREATE.BUILD.PKG001
MODIFY
X
X
 
 
 
X
 
X
C1.PACKAGE.MODIFY.IMPORT.PKG001
CAST
 
 
 
 
 
 
 
X
C1.PACKAGE.CAST.CAST.PKG001
REVIEW
 
 
 
 
 
 
 
X
C1.PACKAGE.REVIEW.DENY.PKG001
EXECUTE
 
 
 
 
X
X
 
X
C1.PACKAGE.EXECUTE.EXECUTE.PKG001
BACKOUT
X
X
 
X
X
X
 
X
C1.PACKAGE.BACKOUT.BACKOUT.PKG001
COMMIT
X
X
 
X
X
X
 
X
C1.PACKAGE.COMMIT.COMMIT.PKG001
UTILITY
 
 
 
X
X
X
 
X
C1.PACKAGE.UTILITY.EXPORT.PKG001
SHIP
 
 
 
X
X
X
 
X
C1.PACKAGE.PSHIP.PSHIP.PKG001
Your access to data sets is indicated with an X. You must have READ access to the data sets to access the Package Actions panel. For a description of column headings, see User Abbreviations.
Define a Security Rule for Concurrent Action Processing
You can restrict who can use the concurrent action processing facility at your site.
Follow these steps:
  1. Determine which departments or users should have access to Concurrent Action Processing.
  2. Determine the format for your Concurrent Action Processing security rule. To generate a pseudo data set name in the format 'C1.CAP', set up the NAMEQU entry in the Name Equates Table using this format:
    NAMEQU CONCURRENT_ACT_PROC,                       X                  L1=('C1'),                       X                  L2=('CAP')
Site Security Package Rules
Before you use ESI, write rules to correspond to Formats ENVIRONMENT_ACCESS through CONCURRENT_ACT_PROC. Customize these formats to conform to your site security conventions to alter the names that are generated at each control point, or to change the authority level and class.
ESI lets you map 
CA Endevor SCM
 entities to your site security package. Different security packages such as CA ACF2, CA Top Secret, RACF have different approaches to implementing security. Understand the approach used by your site security package before attempting to map 
CA Endevor SCM
 entities to your site security package.
All site security packages (CA ACF2, CA Top Secret, RACF) deny access if security rules are not defined.
We recommend that you consider the following guidelines when writing security rules:
  • Confirm that your security rules conform to your existing site naming conventions.
  • Define action authorities that are based on pseudo data set rules rather than SAF authorities.
  • Simplify rule definitions by omitting unnecessary format levels.
  • Avoid inadvertently creating physical data sets when working with pseudo data sets.
  • Do ONE of the following tasks:
    • Use separate naming conventions for physical data sets and pseudo data sets.
    • Define a different security class for pseudo data sets. See Defining a Class Other Than Data Set with RACF for more information.
  • If the authorization values in the SAF interface are customized, check and modify the product authorization mapping (the FUNCEQU entries).
Develop ESI Profiles
After you complete your ESI worksheet, use the pseudo data set names that you created for the ESI worksheets to develop generic profiles. Determine whether you can combine any profiles before you submit the profiles to your site security administrator.
For example, if you have three environments (DEV1, DEV2 and PROD) with three systems (FINANCE, PAYROLL, and HUMNRCS) and you determine from the Action Initiation worksheet that QA has the authority to move elements for all three systems within the DEV1 and DEV2 environments. Assume that you originally coded the profiles as shown next:
  • C1.DEV1.FINANCE.*.MOVE
  • C1.DEV1.PAYROLL.*.MOVE
  • C1.DEV1.HUMNRCS.*.MOVE
  • C1.DEV2.FINANCE.*.MOVE
  • C1.DEV2.PAYROLL.*.MOVE
  • C1.DEV2.HUMNRCS.*.MOVE
Only the second and third qualifiers are different. The second qualifier must be specified because it defines the environment. The PROD environment is not included for QA access. The third qualifier, however, includes all systems so that you can make it generic with a wildcard character as shown in the following table:
These three profiles
Becomes one of these two profiles
C1.DEV1.FINANCE.*.MOVE
C1.DEV1.PAYROLL.*.MOVE
C1.DEV1.HUMNRCS.*.MOVE
C1.DEV1.*.*.MOVE
or
C1.DEV.-.-.MOVE
C1.DEV2.FINANCE.*.MOVE
C1.DEV2.PAYROLL.*.MOVE
C1.DEV2.HUMNRCS.*.MOVE
C1.DEV2.*.*.MOVE
or
C1.DEV2.-.-.MOVE
Identify User IDs that Require Access to ESI Rules and Profiles
After you complete your ESI worksheet, supply the TSO IDs that are required to access the ESI rules/profiles that you created. Whenever possible, identify logical groups of IDs as shown in the following example:
all QA1* Ids
Create NAMEQU Entries for the Name Equates Table
Use the ENVIRONMENT_ACCESS through CONCURRENT_ACT_PROC (extension ACTION_INITIATION is optional) layouts you developed for the ESI worksheets to create NAMEQU entries for the Name Equates Table. Edit member BC1TNEQU of your iprfx.iqual.CSIQSRC installation library and modify the entries to reflect your choices for each of the formats.
The following format
Is derived from
ENVIRONMENT_ACCESS
The Environment Worksheet (Part 3)
PRIMARY_OPTIONS
The Primary Options Worksheet (Part 2)
FOREGROUND_OPTIONS
The Foreground Options Worksheet (Part 2)
ACTION_INITIATION
The Action Initiation Worksheet (Part2)
ACTION_INITIATION
(extension is optional)
The Action Initiation Worksheet (Part2)
PACKAGE_ACTIONS
The Package Actions Worksheet
How to Assemble and Link the Name Equates Table
After you determine the ESIDFLTS, FUNCEQU, and NAMEQU entries for your Name Equates Table, complete the following four tasks:
  1. Define the rules to your site security package.
  2. Modify the BC1TNEQU member in your iprfx.iqual.CSIQSRC.
  3. Assemble and link the modified table, using an SMP/E USERMOD. Alternatively, edit the sample JCL BC1JTABL, located in iprfx.iqual.CSIQJCL, and use it to assemble and link source module BC1TNEQU outside of SMP/E.
  4. Refresh the LINKLIST if the library is in the LINKLIST.
Define Rules for Your Site Security Package
Ensure that security rules are defined to your site security package. You can define security rules before enabling ESI.
If you enable ESI without defining security rules, all access is denied.
Assemble and Link the Modified Table
If your authorized library is in the LINKLIST, perform an LLA REFRESH. The name on the ESIDFLTS entry label and the member name on the SYSLMOD DD statement match.
At runtime, ESI dynamically loads the newly created Name Equates Table from an authorized library (LINKLIST or STEPLIB) to determine the RACROUTE request values to use.
Perform an LLA REFRESH if your authorized library is in the LINKLIST. The JCL that assembles and links the Name Equates Table and source code can be found in the member BC1NEQU. The table name has been modified to NEWTNEQU. The name on the ESIDFLTS entry label and the member name on the SYSLMOD DD statement match.
At runtime, ESI dynamically loads the newly created Name Equates Table from an authorized library (LINKLIST or STEPLIB) to determine the RACROUTE request values to use.
Activate ESI Using the C1DEFLTS Table
The C1DEFLTS table establishes the site, environment, and stage definitions for your installation. This table is an assembler macro that defines parameters specific to the entire site and to each environment and stage at the site. Use the following fields in the C1DEFLTS table to activate ESI:
  • ACCSTBL
    Contains the name of the Name Equates table. The default value for this field is BC1TNEQU.
  • ESSI
    Validates your purchase of ESI and indicates if you want to use ESI security or native mode security. The default value for the ESSI parameter is N. This value indicates that you did not purchase ESI and that you are using native mode security. To indicate that you want to use ESI security, enter a 'Y' or 'N' in the ESSI field in the C1DEFLTS Table.
  • PKGSEC
    • APPROVER
      Indicates that standard approver security should be used (preRelease 3.8).
    • ESI
      Indicates that the ESI interface is used, with the exception of review processing which still requires the approver group (internal or external).
    • MIGRATE
      Allows both methods to be performed, with the Approver method having priority over the ESI method. Use this method if you're migrating to the ESI method.
You can have external approver groups and package security through ESI.
  • APPROVER
    Restricts package action through approver groups whether it is internal or external to the product.
  • ESI
    Controls package actions with external security packages CA ACF2, CA Top Secret, and RACF using the ESI interface.
  • MIGRATE
    Package actions are controlled by approver groups, ESI security, or both.
These options are different in the following ways:
  • PKGSEC=APPROVER lets you restrict package actions through approver groups. 
  • If PKGSEC=ESI in the C1DEFLTS table, all package actions, including APPROVAL invoke ESI. To approve a package, the user must be a member of the approver group whether it is an internal or external group. If you are a member of the approver group, an ESI call is made to check if you are authorized to perform the REVIEW action. You can perform the action if you are authorized, otherwise the action is denied.
    If No approval groups are related to an inventory location, the package is automatically approved. QUORUM must be set to one or more.
  • PKGSEC=MIGRATE - Once a package is created, cast, and approved the rules for ESI are invoked. The first security call after the package is approved, is a call to the approver group. If you are a member of the approver group, the package action is allowed. If you are not a member of the approver group, an ESI call is made to see if you are authorized to perform the action. If you are authorized, the action is granted. If you are not authorized, the action is denied.
Internal, external approver groups, or both are required for approval processing. If no approval groups are related to an inventory group, the package is automatically approved. QUORUM must be set to one or more.
Modify the Name Equates Table Name
You can change the name of the Name Equates Table by changing the value in the ACCSTBL field. You must have also assembled and linked the Name Equates Table with an identical CSECT name and load module name. For example, if ACCSTBL=NEWTNEQU is coded in the C1DEFLTS Table, the load module that is named NEWTNEQU is assumed to be the name for the Name Equates Table and the CSECT within the load module must have the same name. The Name Equates Table contains a field that is set at assembly time with the name of the CSECT. This format prevents a user from copying and renaming an invalid Name Equates table to gain unauthorized access.
Do not enable ESSI or enter a table name (ESSI and ACCSTBL) until you are ready to test ESI.
In the following C1DEFLTS Table, the ACCSTBL field is set to a Name Equates Table name of NEWTNEQU. PKGSEC is set to a value of ESI. The ESSI enabled flag is set to a value of 'Y'.
C1DEFLTS TYPE=MAIN,         ACCSTBL=NEWTNEQU,   ACCESS SECURITY TABLE               *         APRVFLG=N,          APPROVAL PROCESSING (Y/N)           *         ESSI=Y,             ESI ENABLED                         *         PKGCSEC=Y,          PACKAGE CAST SECURITY               *         PKGISEC=Y,          PACKAGE INSPECT SECURITY            *         PKGSEC=ESI,         USE EXTERNAL SECURITY               *         RACFUID=,           ALTERNATE ID USERID                 *
The first portion of the C1DEFLTS Table (TYPE=MAIN) should be set up once.
Test ESI Security and Monitor Warnings
After you install and enable 
CA Endevor SCM
 ESI, verify that ESI has been activated to monitor the security violations issued by the product.
Verify ESI Activation
To ensure that ESI is enabled, display your site information. If a 
Y
 appears in the ESI field, ESI is enabled. The Access Table field contains the name of the Name Equates Table and the PKGSEC field is set to 
Y
.
Monitor Security Violations 
You can monitor security violations using ESI warning mode or the CONRPT40 and CONRPT41 reports. Warning mode violations are recorded in the ESI warning report. 
The CONRPT40 and CONRPT41 reports record attempts by users to perform unauthorized actions.
ESI Warning Mode
ESI Warning Mode lets you test your security implementation without denying users access to 
CA Endevor SCM
 objects. If access rules are not coded, 
CA Endevor SCM
 ordinarily denies access. When using Warning Mode, access to resources is allowed even if your site security package (CA ACF2, CA Top Secret, RACF) indicates that access should be denied. Use ESI Warning Mode 
before
 writing security rules or as an initial test for your security rules.
When your security system identifies a security exception and ESI Warning Mode is enabled, a System Management Facility (SMF) instance records the event. You can then use the ESI Exception Warning report to format and print the ESI warning SMF records in a convenient and easy-to-read report.
SMF records are always written to the SMF data sets (SYS1.MANx). Additionally, you can send records to a sequential data set by allocating a data set to the DDname EN$SMESI. This step automatically writes the SMF records to the SMF data set and the sequential data set.
The ESI Exception Warning report summarizes the SMF records written to the SMF and the sequential data sets. The report data is summarized by entity name, entity format type, entity class, user ID, event date, and time. The original return codes and reason codes are listed with a summary report including each entity name and all the exceptions that are associated with the entity. The Exception Warning report also includes information about each Name Equates Table encountered.
The following JCL example shows how to execute an Exception Warning report:
//ESIWREPT EXEC PRM=NDVRC1,PARM='ENRASW00',REGION=4096K //STEPLIB DD  DISP=SHR,DSN=iprfx.iqual.loadlib //EN$SMESI DD  DISP=SHR,DSN=SMF.data.set //EN$SMRPT DD  SYSOUT=*,DCB=(LRECL=133,BLKSIZE=6118,RECFM=FBA)
In this example, the program NDVRC1 invokes the exception report ENRASW00. EN$SMESI identifies the input SMF records and EN$SMRPT identifies the output data set.
ESI Defaults (ESIDFLTS) Macro
This macro lets you specify how you manage ESI diagnostics. You can use the ESIDFLTS macro to write a diagnostic trace to improve performance and enable warning mode.
Enable ESI Warning Mode
To enable ESI warning mode, specify WARN=YES in the Name Equates Table. The keyword is specified on the ESIDFLTS or NAMEQU entries. The ESIDFLTS value affects the entire table. The NAMEQU value only affects the entry for which it is specified and overrides the ESIDFLTS value.
ESI Trace Facility
This facility helps you to determine if security is functioning as desired at your site. When the Trace Facility is activated, every security call to ESI writes a trace record. The Trace DDname determines where the data is sent. Use the Trace Facility to perform the following tasks:
  • Ensure that the format of the entity name is correct.
  • Review the results of a SAF request (a return code or a reason code).
Ensure the Correct Format of the Pseudo Data Set Name
Examine a trace record to determine if the format of the entity name is correct. The following sample trace record shows a highlighted pseudo data set name (Entity=C1.ENVIRON.PROD).
 ENCS001I:  Using BC1TNEQU table entitled 'CA ENDEVOR NAMEQU Table 4.0'  ENCS001I:  The table was assembled on 07/18/00 at 12.09  ENCS001I:  ESI defaults:  ENCS001I:  ESIDFLTS DESC=(6),                                                      +  ENCS001I:     ROUTCDE=(11),                                                        +  ENCS001I:     WARN=YES,                                                            +  ENCS001I:     HEADER=YES,                                                          +  ENCS001I:     LATSIZE=10,                                                          +  ENCS001I:     TITLE='CA ENDEVOR NAMEQU Table 4.0'  ENCS001I:  Function authorization equates:  ENCS001I:  FUNCEQU SAFAUTH=NONE,                                                   +    ENCS001I:     C1ACTNS=(PRINT,SIGNIN)  ENCS001I:  FUNCEQU SAFAUTH=CONTROL,                                                +  ENCS001I:     C1ACTNS=(ARCHIVE,DELETE,DISPLAY,MOVE,RETRIEVE,SIGNOVR),              +  ENCS001I:  FUNCEQU SAFAUTH=UPDATE,                                                 +  ENCS001I:     C1ACTNS=(ADD,GENERATE,UPDATE)  ENCS001I:  FUNCEQU SAFAUTH=ALTER,                                                  +  ENCS001I:     C1ACTNS=(ENVRNMGR)  ENCS001I:  Format definitions:  ENCS001I:  NAMEQU ENVIRONMENT_ACCESS,                                              +  ENCS001I:     CLASS='$ENDEVOR',                                                    +  ENCS001I:     WARN=NO,                                                             +  ENCS001I:     LOG=NONE,                                                            +  ENCS001I:     L1=('CA ENDEVOR'),                                                   +  ENCS001I:     L2=('CLASS=$ENDEVOR')                                                +  ENCS001I:     L3=('ENVIRONMENT_ACCESS_TEST'),                                      +  ENCS001I:     L4=('ENVIRONMENT=',ENVIRONMENT)  ENCS101I Format=0001 Pass=0000 Auth=READ ACEE=00000000  ENCS101I Class=$ENDEVOR Log=NONE  ENCS101I Scale=0....+....1....+....2....+....3....+....4....+....5....+....6  ENCS101I Entity=CA ENDEVOR.CLASS=$ENDEVOR.ENVIRONMENT_ACCESS_TEST.ENVIRONMENT=D            ....+....7....+....8....+....9....+....0....+....1....+....2          EV  ENCS101I User DA2DM47 access is denied  from SAF  ENCS101I RACROUTE RC=0008 RACHECK RC=0008 REASON=0000  ENCS101I Format=0001 Pass=0000 Auth=READ ACEE=00000000  ENCS101I Class=$ENDEVOR Log=NONE  ENCS101I Scale=0....+....1....+....2....+....3....+....4....+....5....+....6  ENCS101I Entity=CA ENDEVOR.CLASS=$ENDEVOR.ENVIRONMENT_ACCESS_TEST.ENVIRONMENT=B          ....+....7....+....8....+....9....+....0....+....1....+....2          ST  ENCS101I User DA2DM47 access is allowed from SAF
Review RACROUTE Request Return Codes
Examine a trace record to review RACROUTE request return codes. The previous sample trace record includes highlighted RACROUTE return codes (RACROUTE(0000) RACHECK(0000) REASON(0000)).
Trace Record Format
This record has the following format:
FORMAT=
n
PASS=
n
AUTH=
n
ACEE=
n
CLASS=DATASET ENTITY=(Ln...) USER=
userid
ACCESS=(ALLOWED/DISALLOWED) FROM=(SAF/LAT) in WARN mode RACROUTE RC=
n
RACHECK RC=
n
REASON RC=
n
  • Format=
    n
    Specifies the NAMEQU format, where:
  • FORMAT1 is ENVIRONMENT_ACCESS
    • FORMAT2 is PRIMARY_OPTIONS
    • FORMAT3 is FOREGROUND_OPTIONS
    • FORMAT4 and FORMAT5 are ACTION_INITIATION
    • FORMAT6 is PACKAGE_ACTIONS
    • FORMAT7 is CONCURRENT_ACT_PROC
  • PASS=
    n
    0 or 1.
  • AUTH=
    auth1
    Specifies the requested authorization value as defined by the FUNCEQU macro: 'NONE' 'READ' 'UPDT' (UPDATE) 'CNTL' (CONTROL) 'ALTR' (ALTER)
  • ACEE=
    n
    For TSO environments, this value is usually 0. For ROSCOE environments, this value is the virtual storage address of the ACEE passed to the SAF interface.
  • CLASS=
    class name
    Specifies the resource name security class. The default is class name.
  • ENTITY=
    entity name
    Specifies the pseudo data set name that is passed to SAF.
  • USER=
    userid
    Specifies a user ID for verification.
  • ACCESS=(ALLOWED/DISALLOWED)
    Specifies whether access to the entity is allowed or disallowed.
  • FROM=(SAF|LAT)
    in WARN mode
  • Displayed only when running in warning mode. Specifies that a user is allowed access because warning mode is turned on.
  • RACROUTE RC=
    n
    Specifies the return code from the RACROUTE request: 0 = Permit request, nonzero = Fail request
  • RACHECK RC=
    n
    Specifies the return code from the RACHECK request (internal to RACROUTE).
  • REASON=
    n
    Specifies the reason code from the RACHECK.
For CA ACF2 and CA Top Secret users, the AUTH value is alternately mapped to the appropriate value.
Use the Trace Facility
To use the ESITRACE command or DD statement, enable 
CA Endevor SCM
 ESI and have access to the product CLIST Library. If you do not have access to the CLIST Library, use the TSO ALLOCATE command.
For more information about using the TSO ALLOCATE command, see TSO ALLOCATE Command Tasks.
ESITRACE Command in Foreground Mode
The ESITRACE simplifies Trace Facility use as shown in this syntax:
   ?? TERMINAL ?? ????? CONSOLE????? DATASET? ¤ ?????????????????????????????? ¤ ? . ????????                                ?        ?? SHR ??         ?                                ??????????? OLD ????????????                                ?        ?? NEW ??         ?                                ?        ?? MOD ??         ?                                ?        ?? KEEP ??        ?                                         ??????????? CAT ????????????                                ?      ??? (ESI.TRACE) ??? ?                                ?? DSN????(
dataset name
)????
Use the following ESITRACE parameters to activate and deactivate the ESI Trace Facility in foreground mode.
  • Start
    Allocates the trace data set which activates the Trace Facility. START is the default.
  • Stop
    Deallocates the trace data set which deactivates the Trace Facility.
    • TERMINAL
      Directs the trace output to your terminal. TERMINAL is the default.
    • CONSOLE
      Directs the trace output to the operator console.
    • DATASET
      Allocates the trace output to the data set identified by the DSN parameter:
    • SHR
      Allocates the trace data set with share status. SHR is the default.
    • OLD
      Allocates the trace data set exclusively.
    • NEW
      Allocates the trace data set with the name specified in the DSN parameter.
    • MOD
      Writes new trace records at the end of the trace data set (EN$TRESI).
    • KEEP
      Keeps the trace data set when deallocated. KEEP is the default.
    • CAT
      Catalogs the trace data set (EN$TRESI) when deallocated.
    • DSN
       (data set name)
      Identifies the name of the trace data set and is ignored for CONSOLE or TERMINAL allocations. The DSN follows the rules for TSO data set names.
    • ESI.TRACE
      Default name of the trace data set.
    • dataset name
      User specified trace data set name
How to Run ESI Trace
You can write trace records to a terminal, the operator console, or to data sets as shown in the following examples:
Example 1: Use the following CLIST parameter to start the Trace Facility and send all trace records to your terminal by default:
    %ESITRACE START 
Example 2: Use the following CLIST parameter to start the Trace Facility and write trace records to the operator console:
    %ESITRACE CONSOLE START 
Example 3: Use the following CLIST parameter to start the Trace Facility and write all trace records to the data set named userid.ESI.TRACE:
    %ESITRACE DATASET DSN (ESI.TRACE) NEW CAT   
If you enter commands from an ISPF screen, preface the ESITRACE command with 'TSO'.
Deactivate the Trace Facility
After you confirm that ESI is configured properly, deactive the trace facility by using the following CLIST parameter:
%ESITRACE STOP
TSO ALLOCATE Command Tasks
The following table shows how you can use the TSO ALLOCATE and FREE commands to enable and disable the ESITRACE facility:
Task
TSO ALLOCATE/FREE Command
Start the Trace Facility
ALLOC DD (EN$TRESI)
DA(MY.ESI.DATASET) NEW CAT SPACE (11)
CYLINDERS LRECL(133) BLKSIZE(6118)
RECFM(FBA) UNIT(SYSDA) VOL(TSO001)
Allocate a data set to your terminal
ALLOC DD (EN$TRESI) DA(*) SHR
Allocate an existing data set and append records
ALLOC DD (EN$TRESI)
DA(MY.ESI.TRACE.DATASET) MOD
Write trace data to the operator console
ALLOC DD (EN$TRESI) DUMMY SHR
Stop the Trace Facility
FREE DD (EN$TRESI)
If you allocate the ESI trace using the TSO ALLOCATE command or ISPF panels, use the following DCB parameters:
  • BLKSIZE (multiples of 133)
  • LRECL (133)
  • RECFM (FBA)
Activate ESI Trace in Batch Mode
Activate the ESI Trace facility for batch processing by including the following DD statement in your execution JCL:
//EN$TRESI DD SYSOUT=*
Write trace information to a data set by putting the following DD statement in your execution JCL:
//EN$TRESI DD DSN=data.set.name,DISP=SHR
Where DCB attributes match the ones noted in the previous code.