Appendix A. iStrobe APIs
accepts an HTTP request to initiate a
measurement of an active z/OS process. You can use this feature with a performance monitor to start a
measurement when you notice performance problems on the mainframe and would like a deep-dive analysis.
Among the APIs:
iStrobe Configuration
To configure you need to specify Host Name or IP address, Port number, and
signature for each System you want to use with the APIs. The z/OS systems programmer who set up
and the HCI will have this information. Go to the Administration section and select Host Connections. You may configure as many HCIs as needed to connect to your
Release 5.2 and later installations. The connection for an individual measurement is specified in the Web Service request. Refer to the online help Manage HCIs page for more details about the individual fields.
Measurement API
This section provides information about the following topics:
Authentication via CES
Authentication is accomplished using a personal access token to associate
API requests with TSO credentials that have
authorization. To create a personal access token, select the menu button in the upper left corner and, go to Administration>Security. In the Security area, select Personal Access Tokens. The Personal Access Tokens page appears, from which you can create and manage personal access tokens.
The personal access token is stored in and is used to make requests to the host on behalf of the authorized user. HTTPS is recommended to ensure this token and all requests are encrypted.
API calls must include the header "Content-Type" with a value of "application/json", and the header "Authorization" with the value of your personal access token. For more information, see the Personal Access Tokens tab section under Security Settings in the BMC AMI Common Enterprise Services help.
Example Header for API Calls:
Web Service Request to iStrobe Server
The JSON expected by the Web Service is described in the following example. The requester will receive the return value formatted as JSON. See the following available request types.
URL Format of the Web Service Request to the Server
When the message for a request is sent to the Web Service, a response will be returned. If the request is successfully processed, the response will include the URL for the measurement report.
Example Web Service Request JSON Body Format
"reqType": "addActive",
"jobName": "AMIDWW0",
"system": "CW09",
"tags": "list of tags",
"profileName": "profile name to be created",
"emailto": "email.to.notify@example.com",
"duration": "minimum measurement time",
"samples": "number of samples",
"limit": "number of sample dataset to be created",
"finalAction": "quit|stop|continue",
"hlq": "MY.GROUP",
"tranid": "transaction id mask"
}
Descriptions of Elements
reqType
addActive. Adds a request for measurement of an active job.
addQueue. Adds a request for measurement of a job not yet running.
jobname
Required. Jobname to be measured.
system
Required. Host Connection name defined by the Host Connections configuration screen.
tags
Optional. Tags to be assigned to profile.
profileName
Optional. Name of the profile. The default is the jobname.
emailto
Optional. SMTP e-mail address to notify when the measurement is complete and the profile is ready to view. should be configured to use email notifications if this field is provided. should be configured to use email notifications if this field is provided.
duration
Optional. Estimated minimum measurement time in minutes. See the Strobe User Guide for details.
Acceptable values 1 to 1440.
samples
Optional. The target number of samples to take during the measurement session. See the Strobe User Guide for details.
Acceptable values 1000 to 150000.
limit
Optional. Suspends sampling when the target number of samples is reached. See the Strobe User Guide for details.
Acceptable values 1 to 99. Must be 1 when using “Final Action” of Continue. This will be interpreted then as NOLIMIT.
finalAction
Optional. Controls the measurement session when the final data set has been completed. Value can be one of the following: {QUIT | STOP | NOLIMIT}. NOLIMIT with limit =1 is used in place for “Continue”.
hlq
Optional. High Level Qualifier. DSNAME High level qualifier - Temporary data set prefix.
tranid
Optional. May occur up to 5 times. Used for transaction profiling, the tranids are transaction ID masks used to specify the transactions to be measured.
Length is limited to 4 characters. You can use a wildcard character (*) after a string of one or more characters in the Detail by Transaction field to measure transactions that meet the specified search criteria.
* For addQueue the additional elements are available:
step — Optional
program — Optional
stringData — Optional
Example of Returns: JSON Body Format
"messageList": {
"message": [
"STR6300I Input = ADD
AMIDWW0,STEP=*,GOMIN=1,SAMPLES=1000,LIMIT=(1,QUIT),RJCLFILE=(_YES_),INITBY=UR",
"STR6261I 0674 AMIDWW0 ACTIVE/RUNNING CW09 STEP=*/ATSOWPA.ATSOWPA CREATED=(11:58:39 10/26/2017)
GOMIN=1 SAMPLES=1000 LIMIT=(1,QUIT)",
"STR6261I EXPIRATION=(11/02/2017) INITBY=UR",
"STR6142I STROBE.AMIDWW0.S038D001 PRD942 0/0 OPEN",
"STR6200I Strobe measurement session initialized for job AMIDWW0 at 11:58:39 10/26/2017",
"STR6801I Strobe sample data set allocated volser=PRD942"
,"STR6800I DSN=STROBE.AMIDWW0.S038D001",
"STR5301I Strobe running",
"STR8746I STRBDSNA: Environment Active per User Request(NNNNN)",
"STR8749I STRBDSNA: DB2 IFI Trace requested: Accounting/Performance",
"STR6130I ADD operation completed",
],
},
"statusList": ""
}
If there is an error in the addActive request, the return code will be non-zero with an appropriate message.
SQLAF On Demand API
The SQLAF On Demand API executes the
for Db2 SQL Analysis Feature on the supplied SQL statement. The output will be a browser window with the analysis. There is no parsing of the statement to determine if it is syntactically correct.
Issue a post request:
lpar:
This is the LPAR where
is installed. Required to find an appropriate HCI connection to use.
sqlText:
This is the SQL text. Because of the length of the text, it is recommended that the URL be submitted using a POST operation.
ssid:
This is the Db2 subsystem ID (like DB09, not the location, like DB09CW09).
Alternative Measurement API
The Alternative Measurement API allows the user to initiate a measurement from . Unlike the Measurement API, the Alternate Measurement API allows the user to determine if the measurement parameters are correct in the user interface before it is submitted.
Issue a post request:
http://<server>:<port>/istrobe/jsp/measurement/preMeasurementCheck.jsp? jobname=<jobname>&system=<system>&profilename=<profilename>
jobname:
The name of the job to be measured.
system:
The LPAR where
is installed.
profilename:
The name of the profile to view in . It's assumed that the parameter values will be URL encoded as part of the request.