Systems Management API Support

cacc supports the IBM Systems Management Application Programming Interface (SMAPI) component of z/VM. With this support, a set of interface routines allow you to use cacc to perform the directory management functions that are called as part of the Systems Management API.
vmx32besp
VM:Secure
supports the IBM Systems Management Application Programming Interface (SMAPI) component of z/VM. With this support, a set of interface routines allow you to use
VM:Secure
to perform the directory management functions that are called as part of the Systems Management API.
This support replaces calls to IBM-supplied routines with calls to
VM:Secure
commands. After you set up a Systems Management API server environment, use the instructions in this section to add
VM:Secure
-specific components. These components receive control when the SMAPI server environment receives a request from a SMAPI client.
For more information about the server and the Systems Management APIs, see the IBM
Systems Management Application Programming
guide.
Contents
Configure the Server Environment
Several
VM:Secure
facilities must be available to use
VM:Secure
with the SMAPI server environment. The required settings are listed as follows:
To configure the server environment:
  1. Configure
    VM:Secure
    to use IBM Advanced Program-to-Program Communication (APPC) between a client issuing
    VM:Secure
    commands and the
    VM:Secure
    service. Change the configuration as follows:
    1. Add a RESID record in the PRODUCT CONFIG file.
      RESID
      resourcename
      • resourcename
        A unique name assigned to an APPC resource identified on an IUCV statement.
    2. To identify the resource in the RESID record, add the following statement to the
      VMSECURE
      directory entry:
      IUCV *IDENT
      resourcename
      LOCAL
      • resourcename
        The unique name of an APPC resource
  2. Use the CONFIG DASD command to add a unique
    extentname
    field to each EXTENT statement in the
    VMSECURE
    DASD CONFIG file.
  3. Configure
    VM:Secure
    to use the Servant Facility if your site is not already using it.
Install Product API Components in the SMAPI Server
SMAPI provides several request server IDs and servant server IDs. In this procedure, you modify the VSMGUARD ID and the "long call" servant VSMWORKn for use with
VM:Secure
and give the servant and request servers appropriate authorizations in VM:Secure rules if VM:Secure is configured as your ESM. These instructions refer to the IBM
Systems Management Application Programming
guide in the installation chapter “Defining the Servers".
If, after implementing and verifying all the changes described here to interface SMAPI with VM:Secure, you have problems with the SMAPI interface to VM:Secure please contact technical support for assistance before making additional SMAPI or VM:Secure configuration changes.
To install the
VM:Secure
API components in the VSMWORKn virtual machines
and give request and servant servers required authorizations:
  1. Install the request servers VSMREQIN, VSMREQI6 and VSMEVSRV and the SMAPI servant server IDs (collectively; VSMWORKn and VSMGUARD), as described in the section “Setting up and Configuring the Server Environment” in the IBM S
    ystems Management Application Programming
    guide. If you plan to use IUCV to perform SMAPI requests, also install the VSMREQIU server.
  2. All
    VM:Secure
    components that the SMAPI servant servers require are distributed on the
    VM:Secure
    public files disk, usually the VMANAGER 193 disk. Some
    VM:Secure
    customers copy the files on the 193 to a public disk such as the MAINT 19E Y-Disk. If your installation does not have those files on a public disk, then:
    1. Add this statement to the directory entry of each SMAPI servant ID:
      LINK VMANAGER 193 293 RR
    2. Add this statement to the PROFILE EXEC for each SMAPI servant ID:
      ACCESS 293 H
    If you have an alternate method of accessing files on the
    VM:Secure
    PUBLIC disk, implement that method for each SMAPI servant ID.
  3. Allow each SMAPI servant ID to issue CP Diagnose code X’D4’. With no External Security Manager, privilege class "B" is needed in each directory entry. If you are using an External Security Manager, perform one of the following steps:
    • For the
      VM:Secure
      Rules Facility, add the following SYSTEM rule for each SMAPI servant ID:
      ACCEPT VSMWORKn DIAGD4 ACCEPT VSMGUARD DIAGD4
    • For another ESM, use the appropriate controls in the ESM to allow each SMAPI servant to issue the appropriate Diagnose codes.
  4. Allow each SMAPI request server ID and servant server ID to issue CP Diagnose code X’88’. With no External Security Manager, directory record OPTION DIAG88 is needed in each directory entry. If you are using an External Security Manager, perform one of the following steps:
    • For the
      VM:Secure
      Rules Facility, add the following SYSTEM rule for each SMAPI servant ID, and each of the SMAPI request servers:
      ACCEPT VSMWORKn DIAG88 ACCEPT VSMGUARD DIAG88 ACCEPT VSMEVSRV DIAG88 ACCEPT VSMREQIN DIAG88 ACCEPT VSMREQI6 DIAG88 ACCEPT VSMREQIU DIAG88
    • For another ESM, use the appropriate controls in the ESM to allow each SMAPI servant server ID and request server to issue the appropriate Diagnose codes.
  5. Allow each SMAPI servant server ID to LINK to VMANAGER 1FF minidisk. If you are using an External Security Manager, also perform one of the following steps:
    • For the
      VM:Secure
      Rules Facility, add the following VMANAGER rule for each SMAPI servant server ID as shown below :
      ACCEPT VSMWORKn LINK 1FF RR (NOPASS ACCEPT VSMGUARD LINK 1FF RR (NOPASS
    • For another ESM, use the appropriate controls in the ESM to allow each SMAPI servant to link to VMANAGER 1FF read only.
  6. Update the SMAPI Server Configuration File as documented in the section “The Server Configuration File” of the chapter “Setting up and Configuring the Server Environment” in the IBM
    Systems Management Application Programming
    guide. To interface with VM:Secure you need to perform the following additional steps for SMAPI configuration by updating the DMSSICNF COPY file, usually located on the MAINT 193 minidisk.
    You are changing the value of the configuration file attribute named “DM_Exit” from its default value of “DMSSIXDM” to the value “VMXSIXDM”. As a result, the VMXSIXDM routine that
    VM:Secure
    supplies is used as the “Directory Manager Exit Routine”.
    Additionally, you need to configure SMAPI to only use its own request authorization process and not an ESM as VM:Secure does not support authorization requests for SMAPI services. To configure SMAPI this way set the configuration file attribute “Authorization_Policy =” to the value “Authorization_Policy_AuthlistOnly”.
    Lastly,
    VM:Secure
    performance is not improved when the SMAPI caching facility is active. Performance is actually improved when the SMAPI cache facility is turned off because
    VM:Secure
    updates the online directory at the successful completion of each SMAPI request, so caching directory updates is unnecessary overhead. To configure SMAPI so that the cache facility is disabled set the “LOHCOST_Enabled=” attribute to the value “0” (zero).
    In summary set the following attributes for SMAPI configuration file, DMSSICNF COPY, as shown below.
    DM_exit = "VMXSIXDM"
    Authorization_Policy = Authorization_Policy_AuthlistOnly
    The Authorization Policy setting is only if VM:Secure is your ESM.
    LOHCOST_Enabled = 0
Files Provided for the SMAPI Server
The following files, installed using the instructions in the previous section, provide the support to use
VM:Secure
routines with the Systems Management API.
  • VMXSIXDM EXEC
    The VMXSIXDM EXEC is a large SELECT construct, with a WHEN clause for each API routine. It retrieves the original CSL parameters to a stem ‘p’, where p.1 is the first argument, p.2 is the second, and so on. The arguments to each API routine are validated and then used to construct
    VM:Secure
    commands to carry out the requested system management function.
  • VMXSIXIC EXEC
    The VMXSIXIC EXEC supplies logic for the the Image_Definition_Create_DM systems management API.
  • VMXSIXID EXEC
    The VMXSIXID EXEC supplies logic for the Image_Definition_Delete_DM systems management API.
  • VMXSIXIQ EXEC
    The VMXSIXIQ EXEC supplies logic for the Image_Definition_Query_DM systems management API.
  • VMXSIXIU EXEC
    The VMXSIXIU EXEC supplies logic for the Image_Definition_Update_DM systems management API.
  • VMXHVCD4 MODULE
    This MODULE is called by VMXSIXDM to issue a CP Diagnose Code X’D4’.
  • VMXSML2P REXX
    Used by VMXSMAPI EXEC to convert logical file line images to REXX parameters.
  • VMXSMP2L REXX
    Used by VMXSMAPI EXEC to convert REXX parameters to logical file line images.
  • VMXQSVM EXEC
    Used by the SMAPI user exit logic to obtain the module name for communications to the
    VM:Secure
    service virtual machine.
Understanding a
VM:Secure
-Specific Return Code (596) from the Socket SMAPI Server
When the Socket SMAPI Server issues
VM:Secure
commands that do not have a corresponding return code that the API defined, the SMAPI server responds to the caller with a special 596 Return Code value. When a 596 Return Code is presented, a special Reason Code is provided to indicate the nature of the problem. The Reason Code consists of the return code from the
VM:Secure
command that the API called, added to a unique number for each command. For instance, if the API issued an ADDMDISK command (encoded as 900000) that responded with a return code value of 15, reason code 900015 is issued.
The following table defines the encoded value associated with a specific
VM:Secure
command:
Command Name
Associated encoded value
NOTIFY
200000
TAG
300000
SCAN
400000
WORKUNIT
500000
ADDENTRY
600000
DELENTRY
700000
DUPMDISK
800000
ADDMDISK
900000
DELMDISK
1000000
LOCK
1100000
UNLOCK
1200000
PASSWORD
1300000
GETENTRY
1400000
REPENTRY
1500000
VMXDSD00
1600000
MAP
1700000
ADMIN
1800000
VERSION
1900000
QUERY
2000000
TESTLOCK
2100000
CHGMDISK
2200000
GENINCL
2300000
ENTRY
2400000
Product Command Authorization
To use the SMAPI services, authorization to execute
VM:Secure
commands is needed for two types of user IDs:
  1. The user ID passed as the authorized user on a Socket Server API call
  2. The user ID for the SMAPI servant IDs VSMGUARD, VSMWORK2, VSMWORK3, and so on
These user IDs must be authorized as follows:
  • Specify the user ID in the VSMWORK1 AUTHLIST file for the SMAPI Socket Server.
  • Specify the user ID on a “GRANT *ALL TO
    userid
    ” record in the AUTHORIZ CONFIG file, using the CONFIG command.
  • Use the ADMIN MANAGERS command to configure the user ID as a valid
    VM:Secure
    Directory Manager.