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.
VM:Securesupports 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:Secureto 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:Securecommands. 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 Programmingguide.
Configure the Server Environment
VM:Securefacilities must be available to use
VM:Securewith the SMAPI server environment. The required settings are listed as follows:
To configure the server environment:
- ConfigureVM:Secureto use IBM Advanced Program-to-Program Communication (APPC) between a client issuingVM:Securecommands and theVM:Secureservice. Change the configuration as follows:
- Add a RESID record in the PRODUCT CONFIG file.RESIDresourcename
- resourcenameA unique name assigned to an APPC resource identified on an IUCV statement.
- To identify the resource in the RESID record, add the following statement to theVMSECUREdirectory entry:IUCV *IDENTresourcenameLOCAL
- resourcenameThe unique name of an APPC resource
- Use the CONFIG DASD command to add a uniqueextentnameVMSECUREDASD CONFIG file.
- ConfigureVM:Secureto 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:Secureand 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 Programmingguide 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:SecureAPI components in the VSMWORKn virtual machines
and give request and servant servers required authorizations:
- 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 Systems Management Application Programmingguide. If you plan to use IUCV to perform SMAPI requests, also install the VSMREQIU server.
- AllVM:Securecomponents that the SMAPI servant servers require are distributed on theVM:Securepublic files disk, usually the VMANAGER 193 disk. SomeVM:Securecustomers 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:
If you have an alternate method of accessing files on theVM:SecurePUBLIC disk, implement that method for each SMAPI servant ID.
- Add this statement to the directory entry of each SMAPI servant ID:LINK VMANAGER 193 293 RR
- Add this statement to the PROFILE EXEC for each SMAPI servant ID:ACCESS 293 H
- 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 theVM:SecureRules 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.
- 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 theVM:SecureRules 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.
- 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 theVM:SecureRules 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.
- 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 IBMSystems Management Application Programmingguide. 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 thatVM:Securesupplies 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:Secureperformance is not improved when the SMAPI caching facility is active. Performance is actually improved when the SMAPI cache facility is turned off becauseVM:Secureupdates 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_AuthlistOnlyThe 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:Secureroutines with the Systems Management API.
- VMXSIXDM EXECThe 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 constructVM:Securecommands to carry out the requested system management function.
- VMXSIXIC EXECThe VMXSIXIC EXEC supplies logic for the the Image_Definition_Create_DM systems management API.
- VMXSIXID EXECThe VMXSIXID EXEC supplies logic for the Image_Definition_Delete_DM systems management API.
- VMXSIXIQ EXECThe VMXSIXIQ EXEC supplies logic for the Image_Definition_Query_DM systems management API.
- VMXSIXIU EXECThe VMXSIXIU EXEC supplies logic for the Image_Definition_Update_DM systems management API.
- VMXHVCD4 MODULEThis MODULE is called by VMXSIXDM to issue a CP Diagnose Code X’D4’.
- VMXSML2P REXXUsed by VMXSMAPI EXEC to convert logical file line images to REXX parameters.
- VMXSMP2L REXXUsed by VMXSMAPI EXEC to convert REXX parameters to logical file line images.
- VMXQSVM EXECUsed by the SMAPI user exit logic to obtain the module name for communications to theVM:Secureservice virtual machine.
VM:Secure-Specific Return Code (596) from the Socket SMAPI Server
When the Socket SMAPI Server issues
VM:Securecommands 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:Securecommand 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
Associated encoded value
Product Command Authorization
To use the SMAPI services, authorization to execute
VM:Securecommands is needed for two types of user IDs:
- The user ID passed as the authorized user on a Socket Server API call
- 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 TOuserid” record in the AUTHORIZ CONFIG file, using the CONFIG command.
- Use the ADMIN MANAGERS command to configure the user ID as a validVM:SecureDirectory Manager.