Other Acquire Parameters - syncsort_capacity_management - 12 - 12.40

Syncsort Capacity Management Installation Guide

Product type
Software
Portfolio
Integrate
Product family
Syncsort
Product
Syncsort Capacity Management
Version
12.40
Language
English
Product name
Syncsort Capacity Management
Title
Syncsort Capacity Management Installation Guide
Topic type
How Do I
Copyright
2023
First publish date
1985

All of these parameters are optional. Any defaults are shown underlined.

ACCTRACF=N | Y

 

By default Acquire will capture the first three fields of account data from job cards. If ACCTRACF=Y is specified, then instead of this, the RACF userid and group will be placed in the first two Capacity Database account fields for job detail records, and the first job account field will be placed in the third Capacity Database account field.

ALLTAPES

 

If this parameter is specified, then all active tape drives found in SMF type 74 subtype 1 records will have entries in the Acquire output file, even if their I/O rate is less than the value specified to the IORATE parameter (see above), but even so, tape drives with zero I/O rate are not reported.

CF= Y | N

 

By default Acquire will capture data about Coupling Facilities from SMF type 74 subtype 4 records. It will not do this if you provide a control card of CF=N.

CHP=Y | L | N

 

Control capture of channel path data. If N is specified, no channel path usage data will be written to the Acquire output file. If CHP=L is specified then information about channels will be recorded whether or not they are online. The default of CHP=Y will record data about all channels only if they are online. There will be no metrics available for channels that are offline, but you might want to see that they exist.

CICS=Y | N

 

If N is specified, no CICS data will be written to the Acquire output file, even if there are type 110 records in the input data. This will reduce the volume of data in the output files, and will have an effect on the resulting size of the Capacity Database. The data can still be used by Planner, with the restriction that you will not be able to redefine its workload components to represent individual CICS transaction types.

If Y is specified, then Acquire will expect to process SMF type 110 records in the //SMFDATA concatenation, or data from The Monitor for CICS (TMON/CICS). If TMON/CICS data is provided it must be made available under the //TMONCICS file in the JCL for this step.

CICSDICT=A | Y | N

 

Acquire has the ability to process CICS monitoring records from SMF type 110 subtype 1 records. Historically, in order to guarantee the successful decoding of these complex records, Acquire needed to have read a dictionary record prior to encountering the monitor data for a given SMFID/CICS system/CICS version combination. These records are only written by CICS at start up and can change if the CICS MCT (Monitoring Control Table) is modified, causing mapping to be incorrect if new dictionary records are not captured and presented to Acquire ahead of the transaction data.

Acquire no longer needs dictionary records for data from CICS TS v1.1 onwards.

CICSDICT=A, which is the default, instructs Acquire not to use of dictionary records even if they are present and only use the dynamic internal facility to decode the monitoring records.

If CICSDICT=Y is set this will make Acquire require a dictionary record to have been “seen” before processing monitoring records for a given SMFID/APPLID/CICS version. In this case, if no matching dictionary records are available, the numbers of CICS transactions recorded in the Capacity Database may be very low, or even zero. A message will be written each time no match could be found, and showing the number of transactions dropped as a result.

CICSDICT=N allows Acquire to accept and scan dictionary records, but not to fail if no match could be found. In this case, once the list of dictionary records has been exhausted it will use a dynamic internal facility to decode the monitoring records. Note that this facility is only available for data for versions of CICS/TS listed as supported in the Release Note. Older versions of CICS are not supported this way.

If you have any concerns about the use of CICSDICT=N or CICSDICT=A then you should capture dictionary records yourself and make them available for use. In this case you are responsible for providing updated dictionary records if the CICS MCT is changed to ensure correct mapping of data is maintained.

If you are processing only data from TMON/CICS you do not need dictionary records, and do not need to specify this control card.

If any fields that Acquire wants to use are marked as not present in a dictionary record, or are not present in monitoring records, the resulting metrics in the Capacity Database will all be set to zeros.

CICSOPTS=YYY | xyz

 

By default Acquire will summarize CICS activity in three ways: by transaction name, by terminal ID and by user ID. The CICSOPTS= control card allows the user to selectively suppress one or more of these summarizations. Specifying CICSOPTS= allows the user to reduce the elapsed and CPU time and I/O generated by Acquire and avoids storing data you may never use in the Capacity Database.

The three options are coded as either a “Y” or an “N”. All must be specified. The individual items have the following meanings:

x    Transaction summarization

y    Terminal summarization

z    User id summarization

Do not specify CICSOPTS=NNN as this is invalid; apart from that, any other combination is acceptable.

CICSRESP=N | I | Y

 

Acquire has the ability to write a file containing information about CICS transaction response times. To activate this facility, you need to do two things:
  • In the Acquire JCL, add a CICSRESP DD statement. This must specify a file to which the response time data can be written.

  • Specify the parameter CICSRESP=<x>. If CICSRESP=Y is provided a single set of statistics is written covering the entire period of the input data that has been selected. If CICSRESP=I is provided, then a set of statistics will be written for every output interval.

For more details, refer to CICS response time percentiles.

CICSRESPBUCK=(bucket1,bucket2,bucket3,…bucket25)

CICSRESPBUCK=<number>X<range>

 

You can control how Acquire writes data about CICS transaction response times by using this control card. The default is 40X0.1, meaning 40 buckets each of 0.1 seconds. To alter this, supply either a list of values or a range of values in one of the two supported formats. The format of this card must comply with these requirements:
  • There can be no more than 25 numbers provided in a list

  • There can be no more than 40 numbers in a range

  • In any number there can be no more than 4 digits before a decimal place

  • In any number there can be no more than 3 decimal places

  • A decimal place is always a “dot”, never a “comma”. Commas are used to separate items in a list

  • Each number in a list must be larger than the one before it

  • A list of numbers must be surrounded with parentheses

Example 1: CICSRESPBUCK=20X0.25

This will make Acquire generate 20 buckets of response times like this:

Bucket   Contents

1:  0 to <= 0.25s

2:  0.25 to <= 0.5s

20: 4.75 to <5.0s

21: Count of all transactions.

Example 2: CICSRESPBUCK=(1,2,5)

This will provide for just three response time buckets containing the count of transactions that took 1 second or less, those that took 2 seconds or less and those that took 5 seconds or less. A fourth bucket will hold the total number of transactions in the sample.

For example, here is a very small set of transaction data looks like this:

Name      Response time

TRN1      1.5 secs

TRN2      2.3 secs

TRN1      0.75 secs

TRN4      6.1 secs

TRN4      4.9 secs

With CICSRESPBUCK=(1,2,5) the output buckets would have these contents:

Bucket:

1

2

3

4

5

6

…etc

Value:

<1

<2

<5

Total

(blank)

(blank)

 

Count:

1

2

4

5

(blank)

(blank)

 

 

The CICSRESP output file record length is fixed at 404 bytes, and does not change if there are fewer than the default 40 buckets. Unused columns on the right of the record are set to blanks.

CICSRESPPUSH=N | Y

 

When generating CICS Response Time data you may choose to have Acquire generate FTP “put” and “rename” commands for the //CICSRESP file, if you also provide a control card of PUSHFTP=. The methd of “pushing” will be the same as for the PUSHFTP= specification.

CICSTIME=D | E | S

 

When processing CICS transactions you may choose one of three sources of date and time for storing them in the Capacity Database. The choices are:

  • D - the date and time of the SMF 110 record that contained the trans­action

  • E - the end date and time of the transaction

  • S - the start date and time of the transaction

Important notes!

  • If you specify CICSTIME=S or CICSTIME=E and a transaction is detected that started or ended before the beginning of the first RMF interval being processed, than that transaction’s details will be associated with that first interval.

  • If a transaction time is later than the last RMF interval being processed it will be written to the //WAREHSE file if this is available, or if not, it will be discarded.

COMPRESS=N | Y

 

This parameter allows you to tell Acquire to reduce the size of data written to the//ATHDATA file by removing spaces and unneeded zeros. The resulting file is still readable text but should be 30–50% of the original size for the expense of a small increase in CPU usage.

DASD= N | nnn

 

This parameter indicates the SMF record number of data created by Acquire/DASD. These records contain snapshots of disk space and/or SMS storage group occupancy. The default SMF record number from Acquire/DASD is 188 but the default here is DASD=N, meaning that data from Acquire/DASD will be ignored unless this parameter is set correctly. To further control what Acquire processed you can use the DASDOPT= and DASDSID= control cards as described below.

DASDOPT= YYY | abc

 

If data from Acquire/DASD is available, this parameter allows you to control exactly what is to be processed by Acquire. The default is YYY, each option may only be specified as Y or N and setting DASDOPT=NNN is invalid. The option meanings are as follows:

a    Process volume data (subtype 1 records)

b    Process SMS storage group data (subtype 2 records)

c    Process dataset group data (subtype 3 records)

DASDSID=O | R

 

This parameter allows you choose which SMF ID is to be associated with data from Acquire/DASD. If you have provided DCOLLECT data to Acquire/DASD by running I it single-shot mode, rather than have it generate it in cyclic-mode, you may be processing it on a different system (SID) to where it came from. Setting or defaulting DASDSID=O means the SMF ID of the originating system will be retained. Setting DASDSID=R means the SMF ID of the recording system (i.e., the one running Acquire/DASD) will be used.

DB2=N | Y

 

This parameter determines whether or not DB2 data is processed. For compability with previous versions of Acquire, the default is N. If set to Y then DB2 system-level data will be collected. Review the descriptions of DB2ACC control card to further refine what data is processed and set parameters as appropriate.

DB2ACC=NNNNN | abcde

 

This parameter provides a means to pre-aggregate DB2 accounting detail in Acquire. This means that instead of every possible combination of key fields, some can be filtered out, reducing the size of the data, the time needed to process data and transfer it to Syncsort Capacity Management, and the complexity of the Capacity Database.

The default is YYYY, and each option may only be specified as Y or N. The option meanings are as follows:

a      The DB2 connection name

b      The DB2 correlation ID

c      The DB2 plan name

d      The originating user ID

e      The end-user transaction name

If you set any of these options to “N” that field will be replaced with a value of “*” (asterisk).

Any combination of Y and N is valid for this option.

For compatibility purposes, DB2ACC=abcd will be treated as DB2ACC=abcdN

Note: DB2ACC=NNNNN is valid, and stops DB2 accounting data from being processed.
 

DB2ROUND=0 | 1 | 2 | 3

 

This parameter tells Acquire how to handle times for DB2 subsystem data.

0 subtract 5 seconds from the SMF date/time to ensure it falls into the correct RMF interval

1 floor the time to the minute (lose seconds and fractions)

2 floor the time unless the seconds value is 59 or more, then round it up

3 do nothing, pass them as-is

The default is 0.

DB2TIME=D | E | S

 

When processing DB2 accounting data you may choose one of three sources of date and time for storing them in the Capacity Database. The choices are:

D – the date and time of the SMF 101 record that contained the transaction

E – the end date and time of the piece of work

S – the start date and time of the piece of work

Important note:

If you specify DB2TIME=S or DB2TIME=E and a transaction is detected that started or ended before the beginning of the first RMF interval being processed, than that transaction’s details will be discarded.

If a transaction time is later than the last RMF interval being processed, it will be written to the //WAREHSE file if WHS=Y is in effect. If not, it will be discarded for this run.

DCONLY=N | Y

 

If DCONLY=Y is set it instructs Acquire to expect to process only SMF records from Acquire/DASD without any other SMF or RMF data. You must also set DASD=nnn to tell Acquire the actual record type to expect (see above).

DB2USEAI=N | Y

 

By default Acquire uses the original operator ID (field QWHCOPID) for DB2 accounting data. You can choose to use the authorized userid (field QWHCAID) if you set DB2USEAI=Y.

DD=Y | N

 

If N is specified, the output data will not contain information about which workload components used which I/O devices. This will reduce the size of the output files, and also the size of the resulting Capacity Database. If you want to build a Planner model, this DD data improves the accuracy of I/O allocation, but you can still build Planner models without this data.

If Y is specified, or this parameter is omitted, then the output dataset will contain information about the use of physical devices by each workload, as obtained from the DD Detail Extension segments in the SMF type 30 records. This helps to ensure that a Planner model describes the I/O use by workload as accurately as possible.

If Y is specified or left as the default and you specify WORKLOAD=NONE you will receive a warning telling you that DD=N has been forced as you have chosen not to produce Planner Workload data.

Warning! Using DD=Y for a COLLECT run can generate a huge number of records in the WORKxx files, and is should be avoided unless you intend to build a Planner model from this data. You should only use DD=Y with Acquire for a specific and fairly short time.

DEBUG=NNN...NNN

 

This control card is used to turn on specific module debugging within Acquire. This should only be done if requested by Precisely Support, as it can cause a very large number of not very friendly lines of information to be written to the //IPLIST file, and degrades performance.

If specified, the <string> value must comprise 48 “Y” or “N” characters. Each one turns on or off the debugging in a particular module.

Setting MSGLEVEL=<n>+ has the same effect as setting all values to “Y”; e.g.,

DEBUG=YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY

DEVDELAY=n.nn

 

Acquire utilizes type 70–78 SMF records created by either IBM’s RMF software, or BMC’s CMF software. CMF has been found to have an issue with PAV volumes that requires a fix, to be obtained from BMC. The fix ID is BQM0684. If this fix is not applied, then device delay values recorded by CMF are very high and can cause issues when trying to build Planner models in Syncsort Capacity Management.

Setting DEVDELAY= allows you to pick a fixed and arbitrary value for device delay in milliseconds until your CMF issue is fixed. Values can be from 0.00–9.99 inclusive.

DYNADSN=datasetnamestem[,NOINFO]

 

Note:  This parameter is mutually exclusive with the WHS= and the DYNAGDG= parameters. This control card allows Acquire to intelligently determine what datasets to process. datasetnamestem is assumed to be the name of a well-formed dataset name that contains a date and time or some other auto-collating string. If you supply this parameter you must ensure there is a //LASTGDG file in the JCL for Acquire into which it can store or read information about the last dataset it processed. By default Acquire will open and read each dataset it allocates and print information about the first two records. The first will normally be an SMF type 2 dump header and the second one should be the first real data record. The NOINFO option suppresses this action. If you specify DYNADSN= then normally you would not specify SDATE= and STIME= and Acquire will dynamically set them, based on data read from the //LASTGDG file. If you do specify them they will take precedence over this automatic setting. Read the topic The DYNAGDG= and DYNADSN= facilities for full details on how this should be used.

DYNAGDG=datasetnamestem[,NOINFO]

 

Note: This parameter is mutually exclusive with the WHS= and the DYNADSN= parameters. This control card allows Acquire to intelligently determine what datasets to process. datasetnamestem is assumed to be the name of a GDG; i.e., a GDG member name minus the last level of the name. If you supply this parameter you must ensure there is a //LASTGDG file in the JCL for Acquire into which it can store or read information about the last dataset it processed.

By default Acquire will open and read each dataset it allocates and print information about the first two records. The first will normally be an SMF type 2 dump header and the second one should be the first real data record. The NOINFO option suppresses this action.

If you specify DYNAGDG= then normally you would not specify SDATE= and STIME= and Acquire will dynamically set them, based on data read from the //LASTGDG file. If you do specify them they will take precedence over this automatic setting.

Read the topic The DYNAGDG= and DYNADSN= facilities for full details on how this should be used.

 

DYNALAST=<suffix>

 

If DYNAGDG= or DYNADSN= is specified this parameter can be used to prevent all of the entries returned by the catalog list from being allocated and processed. There is no default, meaning all matching the stem value for DYNAGDG= or DYNADSN= will be processed.

If DYNAGDG= is in effect specify the final level of the GDG name, e.g. G1034V00

If DYNADSN= is in effect specify the suffix of the well-formed dataset name.

DYNRETCT=n

 

When using DYNAGDG= and a dataset in the list is use, an error code of x'0210' is returned to Acquire. If DYNRETCT= and DYNRETWT= are both non-zero, Acquire will wait for DYNRETWT minutes then retry the dynamic allocation. It will attempt this DYNRETCT times, or until the allocation completes. If it runs out of retries Acquire will end with a return code of 8.

The value of DYNRETWC= can be from 0 to 9 and the default is 0.

DYNRETWT=n

 

When using DYNAGDG= and a dataset in the list is use, an error code of x'0210' is returned to Acquire. If DYNRETCT= and DYNRETWT= are both non-zero, Acquire will wait for DYNRETWT minutes then retry the dynamic allocation. It will attempt this DYNRETCT times, or until the allocation completes. If it runs out of retries Acquire will end with a return code of 8.

The value of DYNRETWT= can be from 0 to 9 and the default is 0.

EXCLUDECICS=(smfid,cicsapplid)

 

This parameter allows the user to exclude data from selected CICS regions from processing by Acquire. Up to 100 of these parameter cards may be provided.

Example: EXCLUDECICS=(MVS1,QACICS1)

EXCLUDEDB2=(smfid,db2subsystemname)

 

This parameter allows the user to exclude data from selected DB2 subsystems from processing by Acquire. Up to 100 of these parameter cards may be provided.

Example: EXCLUDEDB2=(ZTST,DSNK)

FAIL=R8 | R<number> | A<number>

 

This parameter allows the user to control how Acquire terminates if a failure condition is detected. The first part of the operand is R for a return code or A for a user abend. The second part of the operand is a number from 0 to 4095. For example, if you want Acquire to terminate with a user abend of 123, code FAIL=A123, or if you want a failure to have a return code of 16, code FAIL=R16.

The default is to terminate with a return code of 8 to z/OS.

See also the IFGAPS=, WARN=, and USSFAIL= control cards.

HIS=Y | N

 

This parameter allows the user to choose if Acquire is to process data about Hardware Instrumentation Services (HIS) from SMF type 113 subtype 1 records.

HPAV=Y | N

 

This parameter allows the user to choose if Acquire is to process data about HiperPAV pools from SMF type 78 records.

IFGAPS=R0 | R<number> | A<number>

 

This parameter allows the user to control how Acquire terminates if gaps are detected in RMF intervals, that is, if the end date and time of one RMF interval is not the same as the start date and time of the next one.

The first part of the operand is R for a return code or A for a user abend. The second part of the operand is a number from 0 to 4095. The default is to set a return code of 0, unless some other condition changes that. For example, if you want Acquire to terminate with a user abend of 999, code IFGAPS=A999, or if you want to have a return code of 16, code IFGAPS=R16.

INTROUND=Y | N

 

This parameter allows the user to choose if Acquire is to round the SMF interval to a whole number of minutes, or leave it as the exact number of seconds. The default for compatibility reasons is the round to whole numbers of minutes. The consequence of having INTROUND=Y set is that in certain circumstances utilization calculations will be slightly inaccurate, and can cause total utilization of a processor to look as though it is exceeding 100% busy.

Setting INTROUND=N will return the exact interval length in seconds and remove the erroneous utilization calculations. See SMF intervals for more details on the effect on reporting of using this parameter.

In addition, if you want to capture job detail with JOBS=I or JOBS=J you must set INTROUND=N in order that job events are written correctly to RMF intervals. If you do not specify INTROUND with JOBS=I or =J then Acquire will force this option to be set to N.

IORATE=0 |n or IORATE=n.n or IORATE=n.nn

 

For a COLLECT run, the I/O Rate (in transfers per second) below which activity about non-paging disks and tape drives will be excluded. For example, if IORATE=1.5 , any non-paging disk or tape drive to which the average transfer rate over an interval was less than 1.5 I/O transfers per second will not appear in the Acquire output file. Paging disks always have their details written regardless of their I/O rate.

The value for IORATE must be in the range from 0 to 9.99

If this parameter is not specified, all disks and tape drives found in RMF type 74 records during the data capture interval will have entries in the Acquire output file, regardless of how low their I/O rate happens to be, including zero.

If MSGLEVEL=2 is in effect and IORATE= is greater than zero then message AZS942I will be written at the end of each output interval. This shows the total numbers of disks and tapes found in the input data and how many of each type were dropped from the output data because their I/O rate was lower than requested.

If you consider the numbers being dropped too high, reduce the IORATE= value - you can specify a value as low as 0.01 I/Os per second as a threshold.

JOBS=N | J | I

 

This parameter allows the user to choose if job detail is to be captured. The default is N, no. JOBS=J will capture information when a job, started task or TSO user session ends, using the SMF type 30 subtype 5 record. Many system tasks do not regularly end, so with this option you will not be able to see details for things like the CONSOLE address space, JES2, GRS, or other system facilities, or for longer running started tasks like CICS, HSM or DB2. The output from Acquire will be a little larger than with JOBS=N set.

JOBS=I will capture information about every running task at every expiry of an SMF interval, and when a task ends. This option will capture data about system addresses spaces, including those that are not full-function address spaces (but which cut SMF type 30 subtype 6 records). The down side of this collection option is that processing will take a little longer on the mainframe and the data generated by Acquire will be much larger than with JOBS=N or JOBS=J, as it will write a number of output records for every active task for every SMF interval.

Note that type 30 SMF records are still processed even if you set JOBS=N as they are used to create Planner Workload information (type 07xx records in the output file). If you are sure you do not want to create or process this data as well, set control cards of WORKLOAD=NONE and JOBS=N.

If you intend to capture job detail you must set the INTROUND= parameter to N to prevent Acquire from rounding up RMF interval times. If you do not set this, Acquire will force the option to be set to N and carry on

LPAR=Y | N

 

This parameter controls whether or not Acquire captures details of all logical partitions or not. The default is to capture all available data. Setting LPAR=N will capture only details of the LPAR the data for this z/OS system came from and the PHYSICAL LPAR. For customers with many partitions on a machine this option can help to cut down the speed at which the Capacity Database grows.

MQ= N | Y

 

Choose if MQ Series system data is processed from type 115 SMF records

MQOPTS= YYYY | abcd

 

Choose what data from MQ Series is to be processed. Each of a b and c must be Y or N and all three must be present. MQOPTS=NNNN is not permitted.

a - process MQ Series system-level metrics

b - process buffer pool metrics

c - process Coupling Facility activity metrics

d - process Coupling Facility dataset activity metrics

MSGLEVEL=1 | 2 [+]

 

This parameter controls how verbose Acquire is in the IPLIST file. MSGLEVEL=1 will write the normal set and MSGLEVEL=2 will write an expanded set. Adding a + after the MSGLEVEL= value will turn on internal debugging for all modules in Acquire. It will cause a very large number of unfriendly lines of information to be written to the //IPLIST file, and also degrades performance. The DEBUG= control card provides a more targeted means of turning debugging information, but only do so if requested by Precisely.

OMVSJOBS=N | Y

 

This parameter controls whether Acquire collects information about jobs that run under the OMVS subsystem. The metrics for these jobs is the same set as for jobs that run under JES2 or JES3. For compatibility reasons the default is N. Setting OMVSJOBS=Y will generate larger Acquire output datasets and load more data into the Capacity Database.

PUSHFTP=N | Y | D | M | B | G

 

This parameter controls how USS files are named and if any FTP commands are to be generated. The default of N means no FTP commands are generated, and any USS files created will have their names matching the standard Syncsort Capacity Management naming convention detailed above. This implies that Control Center will be able to collect the data directly from the mainframe.

If PUSHFTP=Y is set, then any USS files will be written with the first character set to a “p” and the //PUSHFTP file will contain a series of “put” and “rename” commands to assist “pushing” the data to where Control Center will be able to find it. If data has been sent to //ATHDATA then a “put” and “rename” command for that will also be written; in this case the file name will be set to <YYYYMMDDhhmmss>_aszs<target>.0910 if only one system has been processed, or <YYYYMMDDhhmmss>_aszs MULTIZOS.0910 if more than one. This is a special name recognized by Control Center and will make it read the target numbers for data from within the file rather than pick a single one up from the file name.

PUSHFTP=M forces the creation of a MULTIZOS file even if there is only a single system’s data in the //ATHDATA output file.

PUSHFTP=D will result in a specialized form of the “put” command that uses the //DD: option of IBM’s FTP client to reference a DDNAME of ATHDATA. This option allows a user who has written the Acquire output to tape to use JCL to make sure the tape volume is not dismounted at the end of the Acquire step only to need mounting again by an FTP step.

PUSHFTP=B combines PUSHFTP=M and PUSHFTP=D.

PUSHFTP=G will prefix the output file with a “g” in anticipation of it being managed by the Control Center Gatekeeper facility.

See also the CICSRESPPUSH= control statement

The separate ACQPUSH utility provides more comprehensive controls to help automate the copying of data as detailed in the section Dealing with Acquire output files.

This parameter is mutually exclusive with PUSHUCOPY= unless PUSHUCOPY=N is set or defaulted.

PUSHUCOPY=N | Y | G

 

This parameter controls how commands are to be generated for use with the 'UCOPY' utility from Stonebranch Inc. The default of N means no FTP commands are generated. PUSHUCOPY=Y will generate a 'ucopy' command with a file name suitable for use with Control Center. PUSHUCOPY=G will do the same but prefix the file name with a 'g' to indicate it is to be subject to Syncsort Capacity Management gate-keeping. The -t operand makes ucopy transfer the data using a temporary file name then rename it when transfer is complete.

SEPDEC=,. | .,

 

This parameter allows the user to control the format of the numbers in messages that are printed by Acquire for z/OS. To print a number in European-style, use “SEPDEC=.,”. Here the “.” (period) is used as the thousands separator and the “,” (comma) is used as the decimal point character and the number will print as 123.456,78. The default is SEPDEC=,. so the number will print as 123,456.78. Only messages in the Acquire job log is affected by this setting and the data written by Acquire for Control Center is not affected. Debug messages are also not affected by this setting as these messages are intended only for use by Precisely Support.

SOURCE=S | D

 

This parameter allows the user to tell Acquire if the SMFDATA DDNAME points to SMF/RMF data or a databox created by ES/1. If you do this, you must ensure the ES/1 load library is concatenated to the Acquire load library so that the appropriate ES/1 modules can be located. This parameter is ignored if you are running Acquire through the ACQES1 single-pass utility.

TIMEADJUST=N | [+/-]hh:m

 

Specifies a time zone for all data. The default is N, and all times will be kept as they appear locally in each z/OS system that is processed.

If set to a time, valid hours are from 00 to 12 inclusive and minute values may be 00, 30 or 45. TIMEADJUST=+00:00 or TIMEADJUST=-00:00 is equivalent to making times their UTC equivalent.

TOLEXPFAIL=N | Y

 

If CICS or DB2 SMF records are compressed, they will be expanded by Acquire using the standard z/OS CSRCESRV macro. If this fails with a return code x'10' it indicates (in IBM’s words):

Not all the data was expanded because the input data was not compressed by the data compression service. Check to see if all the input values were correct. Ensure that the input data was compressed by the appropriate data compression service and that the appropriate data expansion service was invoked. If the problem persists, record the return code and supply it to the appropriate IBM support personnel.

The data may be complete, but it is not possible programmatically to tell. By default, Acquire will abend U0911. If you want to have Acquire process the data after expansion returns this error, you can set TOLEXPFAIL=Y.

USSCOMP=Y | N

 

By default files written to USS will be compressed. USSCOMP=Y will result in a file that has been processed by the standard “compress” utility of z/OS UNIX. The file name will be changed to reflect this, for example from:

20140315000000_aszs00010023.0930

- to -

20140315000000_ezzs00010023.0930

Control Center will recognize that it contains EBCDIC data (the “e”) instead of the usual ASCII data (the “a”) and is a compressed file (the first “z”).

 

Using USSCOMP=Y can result in file sizes up to 10 times smaller than the uncompressed data for a modest increase in CPU time. File names will be altered from _az to ez and must be transferred to Control Center in binary mode. The alternative of USSCOMP=N will leave the data uncompressed and the file name.

USSFAIL=R0 | R<number> | A<number>

 

This parameter allows the user to control how Acquire deals with a problem writing USS data. The first part of the operand is R for a return code or A for a user abend. The second part of the operand is a number from 0 to 4095. For example, if you want Acquire to terminate with a user abend of 123, code USSFAIL=A123, or if you want a failure to have a return code of 16, code USSFAIL=R16.

Note that if you code USSONLY= and there is a problem writing to the USS location, Acquire will abend with a code U0911. Only if you are writing to both the //ATHDATA file and to USS will the USSFAIL= control card have any effect.

For compatibility with older versions of Acquire, the default is to set a zero return code regardless of any problem. This will result in an error message printed on the //IPLIST file, but will still set a return code of zero on completion of Acquire, providing no other errors or warnings occur.

See also the FAIL= and WARN= control cards.

USSONLY=N | Y

 

If USSONLY=Y is provided indicates that data is ONLY to be written to UNIX System Services (USS) using the path name in USSPATH= and not to the //ATHDATA file.

If the writing data to USS encounters a fatal error, Acquire will log the fact and continue writing only to the //ATHDATA file. If USSONLY=Y is in effect then Acquire will abend as it will have nowhere else to write to.

USSPATH=usspathname

 

If provided indicates that data is to be written to UNIX System Services (USS) using the given path name. Care must be taken to ensure that a USS directory or path exists with this name, and it must be entered using the exactly the same characters - USS directory and file names are case-sensitive so for example /SYNCSORT CAPACITY MANAGEMENT CORE, /Syncsort Capacity Management Core, and /syncsort capacity management core are three different path names.

WARN=R4 | R<number> | A<number>

 

This parameter allows the user to control how Acquire terminates if a warning condition is detected. The first part of the operand is R for a return code or A for a user abend. The second part of the operand is a number from 0 to 4095. For example, if you want Acquire to terminate with a user abend of 123, code WARN=A123, or if you want a failure to have a return code of 16, code WARN=R16.

The default is to terminate with a return code of 4 to z/OS.

See also the FAIL= and USSFAIL= control cards.

WAS=N | Y

 

Choose if Websphere Application Server data from type 120 SMF records will be used.

WASOPTS=YYY | abc

 

Choose what Websphere Application Server data is processed. WASOPTS=NNN is not permitted.

a – process WAS system-level metrics (120 subtype 3)

b – process J2EE application metrics (120 subtype 6)

c – process web application metrics (120 subtype 8)

WEIGHTPCT=N | Y

This parameter controls how LPAR weights by CPU type are processed. The default is to write out the weight directly as reported by RMF. WEIGHTPCT=Y will make Acquire calculate the percentage share of each CPU type, across all partitions.

Example configuration on an 8-way processor:

  W E I G H T PERCENT by WEIGHT    

Partition

CP

zAAP

CP

zAAP

Number of CPs : PHYSICAL %

PROD1

40

120

67

80

6 : 75

TEST1

20

30

33

20

1 : 12.5

Total

60

150

100

100

 

PROD1’s share of the machine by CP engine is 40 / (40+20) = 0.67 or 67%. TEST1’s share is 20 / (40+20) = 0.33 or 33%

PROD1’s share of the machine by zAAP engines is 120 / (120 + 30) = 0.8 or 80% TEST1’s share of the machine by zAAP engines is 30 / (120 + 30) = 0.2 or 20%

With WEIGHTPCT=Y in effect you can create a user-defined metric to calculate the MIPS share of a partition based on the weight by using expressions like:

Share CP MIPS = [Configuration MIPS] * [CP Share] / 100

Share zAAP MIPS = [Configuration zAAP MIPS] * [zAAP Share] / 100

 

 

Be aware that the actual percentage of the power available to a partition will depend on the number of logical processors defined and the total physical number on the machine, which you can calculate with an expression like:

Max CP MIPS = [Configuration MIPS] * [Number of CPs] / [Configu­ration number of CPs]

You must assign enough logical processors to a partition to allow it to reach the share percentage based on the weight value. Using the example above, this machine has 8 processors. The PROD1 system has access to 6 of them, giving a maximum physical share of 6/8 or 75%, more than the 67% from its share of the weights.

In contrast the TEST1 system has only 1 logical processor assigned to it. Because of this it can never obtain more than 1/8 = 12.5% of the machine’s capacity. The weight-based share of 20 - which means it should be allowed to use 33% of the CP resources, would never be achievable. To reach this, it would need to have at least 3 logical processors, which would give it a maximum share of 3/8 or 37.5%.

WHS=N | Y | R

 

The DYNAGDG= feature may be better for you if you want to continuously and more intelligently collect data with Acquire.

Note: This parameter is mutually exclusive with the DYNAGDG= parameter.
 

This parameter controls the reading and writing of data to and from the warehouse file (DDNAME //WAREHSE). The warehouse is used to store extracted data for jobs, CICS or DB2 transactions that belong to an RMF interval that is not present in the input data. For example if an input SMF dataset has the last 15 minute RMF interval ending at 00:00:00, but data actually runs to 00:00:06, then there are potentially 6 seconds of time when job data or transaction data cannot be associated with the potential next RMF interval that will end at 00:15:00 in the “next” days data. In previous versions of Acquire this data was simply lost. With the warehouse facility the data is held over, anticipating that the next run of Acquire will be presented with data for the end of that RMF interval.

A file of //WAREHSE DD DSN=…. must be present in the JCL to use this facility. The file attributes are RECFM=VB and LRECL=4096. The file does not need any initalization.

WHS=N will instruct Acquire to ignore the WAREHSE file even if present in the JCL and is the default.

WHS=Y is the default and will use the warehouse file, first to attempt to read any pending data, and then store any remainder data once all data that can be processed has been written to the //ATHDATA file.

WHS=R will instruct Acquire to reset the WAREHSE file, so no records will be read, but any remainder records will still be written away for the next run.

Messages are written to the//IPLIST file indicating how many records were read or written to the warehouse. See Collecting continuous data for more information on this feature.

WORKLOAD=SERVICE | REPORT | NONE

 

This parameter is only relevant if you intend to build a Planner model from the captured data.

If SERVICE is specified, or this parameter is omitted, the Workload Components (for a Planner model) in the output file are based on Workload Manager Service Classes.

Since every unit of work running under Workload Manager has to execute in a Service Class, specifying (or defaulting) this parameter results in every work unit being accounted for in the Planner model. This is helpful, and makes modeling easier.

If REPORT is specified, the Workload Components are based on Report Classes. Normally, you should only specify this parameter if you are sure that every unit of work that runs on your system is assigned to a report class. Otherwise, the Planner model will not account for all the work that was running during the period of data capture, and you will have to make manual adjustments to the Planner model.

If NONE is specified no Planner Workload Component data is written by Acquire. If DD=Y is also specified or defaulted to, you will receive a warning and it will be reset to DD=N.

Important! If you specify WORKLOAD=NONE you will not be able to create z/OS Planner models for the data from systems that you have processed this way.