Sample codes written in Python are provided as reference information for calling and using BCM Web API requests. All of the provided sample codes work with the Python standard library. Operation of the sample codes was verified in a Python 3.10.8 environment.
The following table lists and describes the sample codes.
File name of the sample code |
Description |
---|---|
bcmapi.py |
A common function module that is called from other scripts. This script sends and receives BCM Web API requests and z/OSMF REST API requests. Put it in the same directory as the calling script. The calling script runs import bcmapi to import the common function module before calling the functions in the common function module. To prevent the error that occurs when the server certificate used for SSL communication is a self-signed certificate, the sample code skips the server certificate verification processing by specifying ssl.CERT_NONE in sslcontext.verify_mode when issuing a request. For greater security, change the code to use a different self-signed certificate or a certificate signed by a certificate authority If the IZUG846W error occurs when a request is issued, refer to "Enabling cross-origin resource sharing (CORS) for REST services" in the IBM manual z/OS Management Facility Programming Guide and allow cross-site z/OSMF REST API requests from z/OSMF. If a control code is included in operands or CLIPARMS specified as an argument of the bcmreq function that runs BCM Web API requests, the operation ends with an error. The bcmreq function performs escape sequence processing for operands and CLIPARMS records, so if double quotation marks or forward slashes are included, specify them as they are. However, if a backslash is included, specify two consecutive backslashes. |
bcmapi_test.py |
A script for starting, stopping, and checking the environment of the BCM Web API server. This script performs the following processing:
|
bcmapi_remote.py |
A script for establishing an environment for the Remote DKC Control function. This script performs the following processing:
|
bcmapi_scan.py |
A script for obtaining volume information. This script performs the following processing:
|
bcmapi_cgdef.py |
A script for defining a copy group. This script performs the following processing:
|
bcmapi_cgmake.py |
A script for creating a copy group. This script performs the following processing:
|
How to run sample codes
- Run Configuring environment settings for the BCM Web API to allow BCM Web API to run on the host.
-
Install Python.
-
Of the following sample codes, put the one you want to run, in the same directory as bcmapi.py.
-
bcmapi_test.py
-
bcmapi_remote.py
-
bcmapi_scan.py
-
bcmapi_cgdef.py
-
bcmapi_cgmake.py
-
To perform user authentication by using a client certificate instead of a user ID and password, perform the following procedure.
-
Generate a client certificate on z/OS, where the BCM Web API server will be run, and then export the client certificate.
For information on how to generate and export client certificates, see the description Use client and server certificates from the same CA in the IBM manual z/OS Management Facility Configuration Guide. For the ID operand of the RACDCERT command, specify the user ID of the user who will use the BCM Web API.
Transfer the dataset in which the exported client certificate is saved to the client where the sample code will be run.
Convert the PKCS12 client certificate that was sent to the client into a PEM certificate and private key.
- Example of generating, exporting, and transferring a client certificate
-
1. Generate a client certificate on z/OS, where the BCM Web API server will be run. RACDCERT ID(USERID) GENCERT SUBJECTSDN(CN('User-USERID') O('Your-Company') C('US')) WITHLABEL('Certificate-for-USERID') SIGNWITH(CERTAUTH LABEL('zOSMFCA')) 2. Export the generated client certificate to a DER-encoded PKCS12 dataset. RACDCERT ID(USERID) EXPORT(LABEL('Certificate-for-USERID')) DSN('CLIENT.CERT.USERID.P12') FORMAT(PKCS12DER) PASSWORD('password') 3. Transfer the dataset containing the exported client certificate to the client in binary format. ftp zOSMFhostName Name: USERID Password: Password-for-USERID binary get 'CLIENT.CERT.USERID.P12' clientcert.p12 quit 4. Use the openssl command to convert the transferred PKCS12 client certificate (clientcert.p12) into a PEM client certificate (client.crt) and private key (client.key). openssl pkcs12 -in clientcert.p12 -out client.crt -clcerts -nokeys openssl pkcs12 -in clientcert.p12 -out client.key -nocerts -nodes 5. Specify the file names of the client certificate and private key in the zosmf section of the configuration file (bcmapi.ini) to be created in the next step. [zosmf] hostaddr = 0.0.0.0 cert = client.crt key = client.key
-
-
Refer to the following example of a configuration file, and create the configuration file "bcmapi.ini" according to your environment. Put the file in the same directory as the sample code you want to run.
Specify the configuration file following the structure of INI files supported by the configparser class. For information on the structure of INI files, see documentation on the Python configparser class.
- Configuration file example (when user authentication is to be performed by using a user ID and password)
-
# This is configuration file for BCM WebAPI sample code. # Change the following parameters according to the environment. [zosmf] # IP address of z/OSMF server hostaddr = 0.0.0.0 # z/OS userid of user with access to z/OSMF and BCM CLI userid = USERID [startTsoPrm] # Query parameters value of POST /zosmf/tsoApp/tso proc = IKJACCNT rsize = 50000 acct = DEFAULT [bcmapi] # If You want to output responsebody, change False to True. verbose = False #clist = YKAPIPRC
Section name
Variable name
Variable description
Default value when omitted
zosmf
hostaddr
Specifies the IP address of the z/OSMF server.
This variable cannot be omitted.
userid
Specifies the user ID of the z/OS user who will run the BCM Web API when user authentication is to be performed by using a user ID and password.
This variable cannot be omitted if cert is omitted.
cert
Specifies the file name of the client certificate (PEM format) for the z/OS user who will run the BCM Web API when user authentication is to be performed by using a client certificate. If this variable is specified, the value of userid is ignored.
User authentication is performed by using a user ID and password.
key
Specifies the file name of the private key (PEM format) corresponding to the client certificate for the z/OS user who will run the BCM Web API when user authentication is to be performed by using a client certificate.
The private key is assumed to be included in the file specified for cert.
startTsoPrm
proc
Specifies the logon procedure name of the TSO/E address space to be started by the BCM Web API server.
IKJACCNT
rsize
Specifies the region size of the TSO/E address space to be started by the BCM Web API server.
50000
acct
Specifies the account number of the TSO/E address space to be started by the BCM Web API server.
DEFAULT
bcmapi
verbose
True: Outputs the content of the request and response.
False: Does not output the content of the request or response.
False
clist
Specifies the member name of the CLIST that starts the BCM Web API server.
YKAPIPRC
For each of the variables in the startTsoPrm section, if the HTTP method is POST, specify the logon parameter of the TSO/E address space to be specified in the request line.
If the name of the configuration file has been changed from "bcmapi.ini", specify confpath="file-name" in the argument (enclosed in ()) of the sample code (respBody = bcmapi.start_tso()) that calls the BCM Web API server startup variable start_tso defined in bcmapi.py.
-
For the variables after # Change the following parameters according to the environment. in the sample code, change their values according to your environment. The following table lists the variables whose values need to be changed.
File name of the sample code
Variable name
Description of the variable
bcmapi_remote.py
routeListID
Specifies the ID of the route list to be created.
YKDEFRMT_cliparms
Specifies the array of records to be specified for the CLIPARMS key value for requests whose cliname key value is YKDEFRMT.
bcmapi_scan.py
YKBTSCAN_cliparms
Specifies the array of records to be specified for the CLIPARMS key value for requests whose cliname key value is YKBTSCAN.
bcmapi_cgdef.py
copyGroupID
Specifies the ID of the copy group to be created.
csvPrefix
Specifies the dataset prefix of the CSV file that defines the copy pairs to be added to the created copy group.
YKDEFGRP_cliparms
Specifies the array of records to be specified for the CLIPARMS key value for requests whose cliname key value is YKDEFGRP.
bcmapi_cgmake.py
copyGroupID
Specifies the ID of the copy group for which copy pairs are to be created and operated.
routeID
Specifies the ID of the route list.
-
If you are running bcmapi_cgdef.py, create a CSV file and include the information.
-
Run the sample code.