List of sample codes and how to run them

Business Continuity Manager Web API Reference Guide

Version
9.9.1
Audience
anonymous
Part Number
MK-96HC137-03

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.

Table. List of 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:

  1. Starting the TSO/E address space and BCM Web API server
  2. Running YKENV to check Business Continuity Manager environment variables
  3. Running YKLISTID to output a list of configuration file IDs
  4. Stopping the BCM Web API server and TSO/E address space

bcmapi_remote.py

A script for establishing an environment for the Remote DKC Control function. This script performs the following processing:

  1. Running YKDEFRMT to create a route list definition file and a command device definition file

  2. Running YKDSPRMT to display the contents of the route list definition file and the command device definition file

  3. Running YKBLDRMT to sequentially register each of the command devices on the command device lines that are defined in the route list and originate from the execution host

  4. Running YKDSPRMT and confirming that the command device has been registered

bcmapi_scan.py

A script for obtaining volume information. This script performs the following processing:

  1. Running YKBTSCAN to create a disk configuration definition file

  2. Running YKGETHDA to display the contents of the disk configuration definition file

bcmapi_cgdef.py

A script for defining a copy group. This script performs the following processing:

  1. Running YKDEFGRP to create a copy group definition file

  2. Running YKIMPORT to add or update copy pair information in the copy group definition file

    For the CSV files (pair information CSV file, CTG information CSV file, and EXCTG information CSV file) that are the input for YKIMPORT, allocate a dataset and enter the information in advance.

  3. Running YKGETGRP to display the contents of the copy group definition file

bcmapi_cgmake.py

A script for creating a copy group. This script performs the following processing:

  1. Running YKLOAD to load the copy group definition file to the BCM Web API server

  2. Running YKQUERY to obtain the copy pair status of the copy group

  3. Running YKMAKE to create a copy group

  4. Running YKEWAIT and checking whether the copy group has changed to the DUPLEX status

  5. Running YKGETGRP and then YKEWAIT to display the status of the copy group. If YKEWAIT terminates abnormally, copy pairs with a copy pair status other than DUPLEX or PENDING are displayed in addition to the summary information.

How to run sample codes

  1. Run Configuring environment settings for the BCM Web API to allow BCM Web API to run on the host.
  2. Install Python.

  3. 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

  4. To perform user authentication by using a client certificate instead of a user ID and password, perform the following procedure.

    1. 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.

    2. Transfer the dataset in which the exported client certificate is saved to the client where the sample code will be run.

    3. 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
  5. 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.

  6. 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.

  7. If you are running bcmapi_cgdef.py, create a CSV file and include the information.

  8. Run the sample code.