CONFIG BASIC statement

BASIC settings allow you specify values for basic characteristics of the Application Performance Analyzer installation. The following settings can be specified:
Note: Required parameters are listed first. The alphabetical order specified below is not the order of the parameters in the configuration file.
CDS
Required.

This setting indicates whether the common data store is used for source program mapping, and if so specifies the name given to the Application Performance Analyzer common data store file.

The syntax for the CDS keyword is CDS=(status,dsn) where
  • status = ENAbled | DISabled. Specify ENAbled to enable the common data store for source program mapping. Status must be ENAbled to allow source program mapping from the Application Performance Analyzer GUI.
  • dsn = The name of the common data store partitioned data set extended. dsn is required only when status=ENAbled. The recommended value for dsn is ‘.CDS’. When using this recommended value or any dsn value that begins with a period (‘.’), the value you specify for HLQ will be prefixed to the value you specify for dsn. In this case, the length of the value specified in dsn must be 44 characters, less the length of the value of HLQ. Otherwise, dsn must contain the fully qualified data set name. It can be up to 44 characters long. The Application Performance Analyzer started task automatically allocates the common data store file (as specified in the dsn) if one does not already exist.

For further information on the common data store for source program mapping, refer to Chapter 10 in the Application Performance Analyzer for z/OS User's Guide.

The following example enables the common data store with the file name of IBMAPA.CDS:
CDS=(ENA,’.CDS’)
HLQ=IBMAPA
The following example disables the common data store:
CDS=(DIS)

Default: none

CheckpointDSN
Required.
Specifies the name to be given to the Application Performance Analyzer checkpoint file. You have two options when specifying this value:
  • If CheckpointDSN begins with a period ('.') then the value that you specify for HLQ above will be prefixed to the value you specify in CheckpointDSN. In this case the length of the value specified in CheckpointDSN must be 44 characters less the length of the value of HLQ.
  • Otherwise, CheckpointDSN must contain the fully qualified data set name. It can be up to 44 characters long.

Default: None

HLQ
Required.
Specifies the high-level qualifier for data sets created by the Application Performance Analyzer started task as part of its normal operation. The value that you specify for HLQ must comply with the JCL rule for specifying a data set name. It can be no more than 17 characters long.
Note: If this Application Performance Analyzer instance is a member of a sysplex group, you must select a high-level qualifier that will allow Application Performance Analyzer to allocate all new data sets to volumes that are shared across the sysplex. These data sets include the checkpoint file, sample files, and optional log files. See SampleHLQ in CONFIG SAMPLE statement, and LogHLQ in CONFIG LOGFILE statement for descriptions of how to set a unique high-level qualifier for the sample files and log files.

Default: None.

STCID
Required.

This is the Application Performance Analyzer internal identifier, a four-character value that uniquely identifies the Application Performance Analyzer-started task. This may be, but does not have to be the same as the Application Performance Analyzer-started task procedure name.

Note: If you intend to run Application Performance Analyzer in a SYSPLEX group, you must never change the value of STCID once it has been set. The STCID forms part of the Application Performance Analyzer SYSPLEX group name. Application Performance Analyzer compares the group name recorded in each observation record, with the active Application Performance Analyzer group name to determine if the observation is local or remote to that instance of Application Performance Analyzer. Changing the STCID will cause observations once local to a Application Performance Analyzer instance to be treated as remote. Under rare conditions, this may potentially trigger a high volume of unnecessary XCF messages.
DeleteOnJCLError
Optional.

Specifies whether multiple-step requests that get a JCL error in one of the steps should delete all the sample files and entries for the remaining steps. Specify DeleteOnJCLError=Y to have the entries for steps with a JCL error automatically deleted.

Default: DeleteOnJCLError=N

ExpiryDays
Optional.
This setting indicates how Application Performance Analyzer is to manage the retention of completed observations. It accepts 3 variables using the syntax: ExpiryDays=(days,ExpiryProt,WARN=nnn) where
days = 0-9999
This specifies the number of days an observation is to be retained, before it is automatically deleted by Application Performance Analyzer. The user can override this value when entering an observation request by overtyping the Retain File for (days) field on the Job Information NEW panel. Specify 0 to retain the observation indefinitely. 0 is the default.
ExpiryProt = Y|N
This specifies whether the Retain File for (days) field on the Job Information NEW panel is protected or unprotected. Specify Y to protect the field from changes. Specify N to leave the field unprotected. N is the default.
nnn = 0-255.
This enables the expiry days warning feature and specifies the number of days prior to observation automatic deletion that Application Performance Analyzer is to start warning the user. When this feature is enabled, the request number in the observation list might be displayed in red, yellow or green based on the expiry date. It is displayed in red when an observation will be automatically deleted within 24 hours. It will be displayed in yellow when an observation will be automatically deleted within the number of days specified for WARN. It will be displayed in green when the observation will never be deleted. Users with administrator authority will see the colors for all users’ observations. All other users will see the colors for their own observations only. A value of 255 disables this feature. 255 is the default.
Examples:
  • ExpiryDays=20 (observation will be automatically deleted in 20 days, Retain File for (days) field is unprotected, expiry days warning is disabled)
  • ExpiryDays=(20,Y) (observation will be automatically deleted in 20 days, Retain File for (days) field is protected, expiry days warning is disabled)
  • ExpiryDays=(20,N,WARN=5) (observation will be automatically deleted in 20 days, Retain File for (days) field is unprotected, expiry days warning is enabled and user will be warned when 5 days are remaining before automatic deletion)

Default: ExpiryDays=(0,N,WARN=255) to indicate the observation file is to be retained indefinitely, the Retain File for (days) field is unprotected, and the expiry day warning feature is disabled.

MsgLevel
Optional.

Specifies the severity level of messages to be written to the log data sets. MsgLevel=I will write all messages, MsgLevel=W will write warning level and higher severity messages only. No SYSOUT data sets will be created for a sampling session with MsgLevel=W when only informational messages are produced.

Default: MsgLevel=I

SecureImportSys
Optional.

Specify Y (yes) to use the originating system name of imported sample files in Application Performance Analyzer security requests. Specify N (no) to use the local system name, which is the system into which the sample file is imported. This applies only when Security=External is specified. When Y, external security rules must be written to accommodate the use of the originating system name.

This keyword is applicable in cases where sample files are imported from an originating system with restricted access into a local system that has less restrictive access. If SecureImportSys=Y is not specified, users that are not authorized to view sample files on the originating system could potentially view the same sample file once imported into the local system.

Default: N

Example: System PROD allows only users USERA and USERB to view Application Performance Analyzer reports. System TEST allows all users to view all Application Performance Analyzer reports. To ensure that only USERA and USERB can view reports in TEST for sample files imported from PROD to TEST, the following must be specified in the TEST system:
  • On the CONFIG BASIC statement:
    SecureImportSys=Y
    Security=External 
  • In RACF:
    RDEFINE PROD.VIEW.* UACC(NONE)
    PERMIT PROD.VIEW.* ID(USERA) ACCESS(READ)
    PERMIT PROD.VIEW.* ID(USERB) ACCESS(READ)
Security
Optional. (But Security=External is highly recommended.)

Specifies whether this started task should use Application Performance Analyzer's internal security scheme or use an external product, such as RACF. Specify Security=External if you use an external security product. To use Application Performance Analyzer's internal security scheme, you can specify Security=Internal or allow the default. (Application Performance Analyzer defaults to internal security.) You can also specify Security=None to run without security.

Default: Internal.

Note: The Security=Internal option is supported for backwards compatibility, but is not recommended. Similarly, you can specify the keyword COMPAT along with Security=External for backwards compatibility with an early version of the external security feature. The list below explains the available security options:
Security=Internal
Specifies that no external security will be used. This option is not recommended, particularly in sysplex environments.
Security=External
Specifies that external security will be used. This is the recommended option. It fully supports sysplex environments.
Security=(External,Compat)
Specifies that external security will be used. This option is for Application Performance Analyzer, Version 1.1 with PTF UK07430 applied for APAR PK10866 only. Do not use this option if you have not applied PTF UK07430, or if you have applied subsequent PTFs. (For external security with subsequent PTFs, use Security=External.) In this mode, the first node of a resource name is the STCID instead of the system name. For improved performance, migrate to the Security=External option.
Security=None
Specifies that no security will be used. This option is useful in test environments, in which security is not required.
Default: Internal
SecurityClassName
Optional.

Specifies an alternate class name will be used instead of FACILITY. This keyword is only used when Security=External is also specified; otherwise it is ignored. This is mandatory when SecurityHLQ is specified.

Default: FACILITY

Rules for class name:
  1. Must be between 1-8 characters, consisting of:
    • A-Z
    • 0-9
    • #, @, $
  2. Must contain at least one character from the following:
    • 0-9, #, @, $

If SecurityClassName is coded as FACILITY or allowed to default, then parameter SecurityHLQ may not be used. The FACILITY class is limited to 39 characters for the access rule that can be exceeded if SecurityHLQ is used. An alternative class is XFACILIT, a predefined class in RACF that allows up to 246 characters.

SecurityHLQ
Optional.

Specifies an optional qualifier for security profiles to be placed in front of the sysplex system name when a SecurityClassName has been specified other than FACILITY. This can be a maximum of 17 characters and must follow the rules established for the class in the Class Descriptor Table (CDT). The contents of this field are not checked during startup. This HLQ can be used in a sysplex environment to provide common access rules for all images in the sysplex.

If specified, it will be concatenated in front of the sysplex system name during security checks.

When SecuirtyHLQ is specified, SecurityClassName must also be specified, and it must not be FACILITY. See SecurityClassName for more details.

Default: None.

SecuritySuppMsg
Optional.

This option causes Application Performance Analyzer to either suppress or display messages issued as a result of RACROUTE calls made by Application Performance Analyzer. If not suppressed, messages will be displayed by RACROUTE via WTO.

Default: Y to suppress these messages.

SPXGroupName
Optional.

Specifies the Application Performance Analyzer sysplex group that this Application Performance Analyzer instance will be a member of. It can be a maximum of eight alphanumeric characters. All Application Performance Analyzer instances that will communicate with each other must code an identical SPXGroupName=sysplexname.

Note: The value specified for SPXGroupName must be unique and not currently used by any other subsystems in the sysplex. Do not use the system's sysplex name for this value.

The Application Performance Analyzer instances in an Application Performance Analyzer sysplex group must be from different MVS™ systems. All Application Performance Analyzer instances defined in the same Application Performance Analyzer sysplex group must share a common checkpoint file; therefore, it is important that the HLQ, UNIT, and CheckpointDSN are identical.

In summary, the CONFIG BASIC statement for every Application Performance Analyzer instance defined in the same Application Performance Analyzer sysplex group must be coded identically, with the exception of the STCID, which might be unique.

Default: None.

TZ
Optional (only required for USS source mapping).
Specifies the TZ environment variable, which conforms to the POSIX standard. This must be coded if USS programs are to be source mapped using debug files in ELF/DWARF format. Otherwise, it is not required. Details on the format and content of a TZ environment variable can be found at:
http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html
TZ="EST5EDT,M3.2.0/02:00,M11.1.0/02:00"
UNIT
Optional.
Specifies the unit name to be used when allocating all new data sets of the following type:
  • Application Performance Analyzer checkpoint file
  • Application Performance Analyzer log data set
  • Application Performance Analyzer sample files

Default: SYSDA

Unit can be either a device type such as 3390, or an esoteric such as SYSDA. A mount status of STORAGE or PUBLIC is nonspecific and does not require a VOLSER. (This release of Application Performance Analyzer does not allow a VOLSER to be specified.)

On a non-SMS-managed system, you must ensure that the UNIT name you specified contains one or more volumes mounted as either STORAGE or PUBLIC. If there are not such volumes mounted, then Application Performance Analyzer will be unable to allocate critical files and will terminate.

On an SMS-managed system, SMS will ignore the unit parameter. To ensure SMS control over all data sets allocated by Application Performance Analyzer, specify an HLQ value that is recognized and managed by SMS.