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.

DefaultSMSClass

Optional. Dynamically modifiable.

This setting is used to assign SMS class values to the data sets created by Application Performance Analyzer. DefaultSMSClass specifies the default SMS class values used when no other SMSClass keyword from any other customization section is provided, and is used to allocate the following data sets:

Checkpoint
Common Data Store (CDS)
Sample files
Export files
Log files
PDF and XML reports

The syntax for this setting is DefaultSMSClass=(mgmt,stg,data) where the positional parameters are:

mgmt = The management class name. It must be one to eight alphanumeric or national characters, as defined by the storage administrator at your installation.
stg = The storage class name. It must be one to eight alphanumeric or national characters, as defined by the storage administrator at your installation.
data = The data class name. It must be one to eight alphanumeric or national characters, as defined by the storage administrator at your installation.

DeleteOnJCLError

Optional. Dynamically modifiable.

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. Dynamically modifiable.

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-3660: 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. Dynamically modifiable.

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

RM

Optional.

This keyword enables or disables a Resource Manager in JES3 environments. Specify RM=(SAMP_JSTASK=ENABLED) to enable a Resource Manager to execute when the Job Step TCB stops. Specifically, the Resource Manager is defined to the Job Step TCBs of all sampled job steps. This setting affects batch jobs only, and is used only on the advice of IBM.

Default: DISABLED.

SampleDSUserLevelSecurity

Optional.

This keyword is used to enforce external security access at the user level. It is applicable when creating, updating, reading and deleting sample file data sets, and those data sets containing exported sample files. This would typically be used when the sample file data sets and exported sample file data sets are configured with the user ID as the high level qualifier, eliminating the requirement to give the Application Performance Analyzer started task full access to these data sets.

Enabling this feature (SampleDSUserLevelSecurity=Y) restricts the Application Performance Analyzer started task to accessing these data sets under the requestor's user ID. When enabled, the following operations are authorized under the requestor’s user ID:

New sample files created at the end of an observation session
New sample files created during an IMPORT operation
Sample files deleted by a user
Expired sample files automatically deleted by the Application Performance Analyzer started task
Exported sample files created as a result of an EXPORT operation
Exported sample files read (and optionally deleted) during an IMPORT operation
Sample files read when selected for reporting

Note: The value for SampleDSUserLevelSecurity must be the same for the Application Performance Analyzer Started Task and the Application Performance Analyzer Common Server Extension. For more information, refer to Configuring the Application Performance Analyzer PDTCC Extension in Chapter 6.

Default: N

SCRLevel

Optional.

The SCRLevel setting indicates how Application Performance Analyzer is to record usage for subcapacity reporting. By default, Application Performance Analyzer records usage only when it is processing a measurable activity. Alternatively, you can configure Application Performance Analyzer to record usage for the total time the started task is executing.

The following APA activities are considered measurable:

Starting the ISPF front end
Connecting the plug-in
Executing an observation
Printing a report via CAZPRINT
Executing a batch import via the CAZIMPRT interface

The syntax for the SCRLevel setting is SCRLevel=1|2, where:

SCRLevel=1 indicates that usage is recorded for subcapacity reporting when the started task is processing a measurable activity. If there is no measurable activity, Application Performance Analyzer does not record usage.

SCRLevel=2 indicates that usage is recorded for subcapacity reporting when the started task is executing. This value also records measured usage.

Note: If you have purchased Application Performance Analyzer as part of a solution pack, Application Performance Analyzer attributes its usage to the enabled solution pack, regardless of the value that is specified for SCRLevel.

Default: 1

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:

Must be between 1-8 characters, consisting of:
- A-Z
- 0-9
- #, @, $
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 of which this Application Performance Analyzer instance will be a member within a sysplex environment. All Application Performance Analyzer instances that will communicate with one another in a sysplex must code an identical SPXGroupName=apaspxgp. The value of apaspxgp can be a maximum of eight alphanumeric characters, must be unique to Application Performance Analyzer, and must not be the sysplex name of the system.

All Application Performance Analyzer instances with the same SPXGroupName=apaspxgp must run on different systems in the sysplex and participate in DASD sharing. This allows Application Performance Analyzer to allocate all new data sets to volumes that are shared across the systems in the sysplex. Because they share a common checkpoint file and Common Data Store (CDS), it is important that the HLQ, UNIT, CheckpointDSN, and CDS are also identical.

In summary, it is a good practice to define identical CONFIG BASIC statements for every Application Performance Analyzer instance participating in the same Application Performance Analyzer sysplex group, with the exception of the STCID, which might be unique.

Default: None.

SysoutClass

Optional.

Specifies a class for the SYSOUT data sets that Application Performance Analyzer dynamically allocates during its operation. SysoutClass is a one-character field that might contain the value of 0-9, A-Z, or *. The default value is an asterisk (*), which indicates that Application Performance Analyzer uses the default SYSOUT class. The default SYSOUT class is specified for the address space where it is executing.

When the default SYSOUT class that is assigned to the address space in which Application Performance Analyzer is executing is not suitable for Application Performance Analyzer output, you can use the SysoutClass setting to control how the output is assigned. For example, your z/OS installation might set the default SYSOUT class for printing this output, which might be unsuitable for Application Performance Analyzer output.

This setting applies to the following SYSOUTs that are created by Application Performance Analyzer:

COMMANDS
MAIN
LOGR
LOAD
GRHS
CDS
OIMS
XMCS
SRMS
CMDP
URSS
XRS
J9VM
REQ#nnnn
DATWnnnn
ESDEnnnn
HVXTnnnn
Various diagnostic outputs

Notes:

You can specify the SYSOUT class for the COMMANDS output in the Application Performance Analyzer startup JCL. The startup JCL specification overrides the SysoutClass assignment.
The SYSOUT class for the CONFIGSO output is not affected by the SysoutClass setting. However, you can specify the SYSOUT class for the CONFIGSO output in the Application Performance Analyzer startup JCL. If you do not specify the SYSOUT class for the CONFIGSO output in startup JCL, Application Performance Analyzer assigns CONFIGSO to the default class that is specified for the address space where it is executing.

Default: *

TZ

Optional

Specifies the TZ environment variable, which conforms to the POSIX standard. This must be coded if USS or Enterprise COBOL V5 programs are to be source mapped using DWARF debug format files. 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.