live.smapi
Class SMAPI_Interface

java.lang.Object
  extended bylive.smapi.SMAPI_Interface

public class SMAPI_Interface
extends Object

SMAPI_Interface is a library that utilizes the z/VM SMAPI to provide the same feature set as the SMAPI but without the trouble of the confusing technical details of the SMAPI. You will not need to check return or reason codes, or worry about setting the correct parameters. This library provides procedures that reduce the complexity of many SMAPI procedure calls by using sane default values for arguments and reducing the amount of usually unneeded options available to the programmer. It also provides procedures that exactly corespond to the SMAPI calls so that the programmer can still utilize the full power of the SMAPI if neccessary. Note: Not all functions have been written, and some that have been written do not allow you to make full use of the underlying SMAPI call. In these cases, the limitations are clearly explained.

Author:
Jason J. Herne (jjherne@us.ibm.com), Emily Kate Celeskey (eceleske@us.ibm.com)

Field Summary
private static String ACTIVE_IMAGE_QUERY
           
private static String AUTH_LIST_ADD
           
private static String AUTH_LIST_QUERY
           
private static String AUTH_LIST_REM
           
private static byte B_LINETERM
           
private static byte B_NULL
           
private static byte B_SPACE
           
private static String FIND_STORAGE
           
private  String hostName
           
private static String IMAGE_ACTIV
           
private static String IMAGE_CREATE_DM
           
private static String IMAGE_DEACT
           
private static String IMAGE_DEDIC_DM
           
private static String IMAGE_DEDICATE
           
private static String IMAGE_DELETE_DM
           
private static String IMAGE_DEV_RESE
           
private static String IMAGE_DISK_CP
           
private static String IMAGE_DISK_CP_DM
           
private static String IMAGE_DISK_CREAT
           
private static String IMAGE_DISK_CREAT_DM
           
private static String IMAGE_DISK_DEL
           
private static String IMAGE_DISK_DEL_DM
           
private static String IMAGE_DISK_SH
           
private static String IMAGE_DISK_SH_DM
           
private static String IMAGE_DISK_UNSH
           
private static String IMAGE_DISK_UNSH_DM
           
private static String IMAGE_LOCK_DM
           
private static String IMAGE_NAME_QU_DM
           
private static String IMAGE_PSWD_SET_DM
           
private static String IMAGE_QUERY_DM
           
private static String IMAGE_RECY
           
private static String IMAGE_REPLACE_DM
           
private static String IMAGE_STAT_QUER
           
private static String IMAGE_UNDED
           
private static String IMAGE_UNDED_DM
           
private static String IMAGE_UNLCK_DM
           
private static String IMAGE_VOL_ADD
           
private static String IMAGE_VOL_DEF_DM
           
private static String IMAGE_VOL_DEL
           
private static String IMAGE_VOL_QUE_DM
           
private static String IMAGE_VOL_REM_DM
           
private static String LOW_FREE_ADDR
           
private static String NAME_LIST_ADD
           
private static String NAME_LIST_DES
           
private static String NAME_LIST_Q_ALL
           
private static String NAME_LIST_REM
           
private static String NAMELIST_QUERY
           
static int NL_GUESTADDED
           
static int NL_LISTMADE_GUESTADDED
           
static int NL_LISTMADE_GUESTTHERE
           
private static String NULL_CALL
           
private  String password
           
private  int port
           
private static String PROTO_CREA_DM
           
private static String PROTO_DEL_DM
           
private static String PROTO_NM_QU_DM
           
private static String PROTO_QUE_DM
           
private static String PROTO_REPL_DM
           
private static String QUER_NET_MEMBERS
           
private static String QUER_NIC_ADDR
           
private static String QUERY_ASYNC_OP
           
private static String QUERY_VIRTUAL
           
private static String SS_ACC_ADD_DM
           
private static String SS_ACC_QUE_DM
           
private static String SS_ACC_REM_DM
           
private static String SS_CREATE
           
private static String SS_DELETE
           
private static String SS_QUERY
           
private static String SS_REPLACE
           
private static String STAT_CHANG_ACT_DM
           
private static String STAT_CHANG_DEA_DM
           
private static String STAT_CHANG_IMM_DM
           
private  String userName
           
private static String VIRT_NET_AD_CR
           
private static String VIRT_NET_AD_CR_DM
           
private static String VIRT_NET_AD_DE
           
private static String VIRT_NET_AD_DE_DM
           
private static String VIRT_NET_CON_CR
           
private static String VIRT_NET_CON_CR_DM
           
private static String VIRT_NET_CON_DE
           
private static String VIRT_NET_CON_DE_DM
           
private static String VIRT_NET_LAN_CON
           
private static String VIRT_NET_LAN_CON_DM
           
private static String VIRT_NET_LAN_DS
           
private static String VIRT_NET_LAN_DS_DM
           
private static String VIRT_NET_LAN_QU
           
private static String VIRT_NET_VSW_CON
           
private static String VIRT_NET_VSW_CON_DM
           
private static String VIRT_NET_VSW_DS
           
private static String VIRT_NET_VSW_DS_DM
           
private static String VIRT_NET_VSW_MAKE
           
private static String VIRT_NET_VSW_QUE
           
private static String VIRT_NET_VSW_SET
           
private static String VIRT_SWIT_CREATE
           
private static String VSW_DEL
           
private static String VSW_DET
           
 
Constructor Summary
SMAPI_Interface(String hostName, int port, String userName, String password)
          Creates a new SMAPI Interface object with the given parameters.
 
Method Summary
 LinkedList activeImagesQuery()
          UNOFFICIAL: This function returns a LinkedList of Strings.
private  void asynchronousCall(String asyncOperationID)
          Corresponds to the SMAPI procedure QUERY_ASYNCHRONOUS_OPERATION_1.
private  LinkedList connectRequest(String functionName, String parms)
          Executes the requested SMAPI function given its name and parameters.
private  LinkedList connectRequestRAW(String functionName, String parms)
          Executes the requested SMAPI function given its name and parameters.
private  void errorCheck(String desc, int rc, int rs)
          Given an RC/RS pair, compare them against known errors and throw an appropriate exception if an error is detected.
 String getLowestFreeAddress(String guestName, String size)
          UNOFFICIAL: Returns the lowest free virtual address for a particular user.
 String getNICaddress(String netName, String guestName)
          UNOFFICIAL: This function returns the virtual address of a specified NIC for a specified user on a specified network .
 void imageActivate(String guestName)
          Corresponds to the SMAPI procedure IMAGE_ACTIVATE.
 void imageCreate(String guestName, String prototypeName, String password)
          Corresponds to the SMAPI procedure IMAGE_CREATE.
 void imageDeactivate(String guestName)
          Corresponds to the SMAPI procedure IMAGE_DEACTIVATE.
 void imageDelete(String guestName)
          Corresponds to the SMAPI procedure IMAGE_DELETE.
 int imageDiskCopy(String strGuestName, String strVirtualDeviceAddress, String strSourceImageName, String strSourceDeviceAddress, String strAllocationType, String strDiskMode, String strReadPW, String strWritePW, String strMultiPW)
          Copies a minidisk from one guest to another
 int imageDiskCopyDM(String strGuestName, String strVirtualDeviceAddress, String strSourceImageName, String strSourceDeviceAddress, String strAllocationType, String strDiskMode, String strReadPW, String strWritePW, String strMultiPW)
          Copies a minidisk from one guest's directory to another guest's directory
 void imageDiskCreate(String strGuestName, String strVirtualDeviceAddress, String strAllocationType, String strAllocUnitSize, String strDiskSize, String strDiskMode, String strFormat, String strReadPW, String strWritePW, String strMultiPW)
          Creates a new minidisk for a guest
 void imageDiskCreateDM(String strGuestName, String strVirtualDeviceAddress, String strAllocationType, String strAllocUnitSize, String strDiskSize, String strDiskMode, String strFormat, String strReadPW, String strWritePW, String strMultiPW)
          Creates a new minidisk for a guest's directory entry
 void imageDiskDelete(String strGuestName, String strVirtualDeviceAddress)
          This function deletes a minidisk from a guest
 void imageDiskDeleteDM(String strGuestName, String strVirtualDeviceAddress)
          This function deletes a minidisk from a guest's directory entry
 void imageDiskShare(String sourceGuestName, String sourceVaddr, String destGuestName, String destVaddr, String accMode, String passwordNeededToLink)
          Corresponds to the SMAPI procedure IMAGE_DISK_SHARE.
 void imageDiskShareDM(String sourceGuestName, String sourceVaddr, String destGuestName, String destVaddr, String accMode, String passwordNeededToLink)
          Corresponds to the SMAPI procedure IMAGE_DISK_SHARE.
 void imageDiskUnshare(String guestUsingDisk, String vaddrOfGuestUsingDisk, String guestOwningDisk, String vaddrOfGuestOwningDisk)
          Corresponds to the SMAPI procedure IMAGE_DISK_UNSHARE.
 void imageDiskUnshareDM(String guestUsingDisk, String vaddrOfGuestUsingDisk, String guestOwningDisk, String vaddrOfGuestOwningDisk)
          Corresponds to the SMAPI procedure IMAGE_DISK_UNSHARE.
 void imageLock(String guestName)
          Corresponds to the SMAPI procedure IMAGE_LOCK.
 LinkedList imageNameQuery()
          Corresponds to the SMAPI procedure IMAGE_NAME_QUERY.
 LinkedList imageQuery(String guestName)
          Corresponds to the SMAPI procedure IMAGE_QUERY.
 void imageReplace(String imageName, LinkedList imageDefLines)
          Corresponds to the SMAPI procedure IMAGE_REPLACE.
 void imageSetPassword(String guestName, String password)
          Corresponds to the SMAPI procedure IMAGE_PASSWORD_SET.
 void imageUnlock(String guestName)
          Corresponds to the SMAPI procedure IMAGE_UNLOCK.
 int nameListAdd(String listName, String nameToAdd)
          Corresponds to the SMAPI procedure NAME_LIST_ADD.
 void nameListDestroy(String listName)
          Corresponds to the SMAPI procedure NAME_LIST_DESTROY.
 LinkedList nameListQuery(String listName)
          Corresponds to the SMAPI procedure NAME_LIST_QUERY.
 LinkedList nameListQueryAll()
          UNOFFICIAL: This function returns all information from the SMAPI namelist file which is used to store the SMAPIs namelists and their members.
 int nameListRemove(String strListName, String strNameToRemove)
          Corresponds to the SMAPI procedure NAME_LIST_REMOVE.
 void nullRequest()
          Executes a simple SMAPI call that does nothing other than authenticate with the SMAPI server.
private  Network parseGLan(LinkedList lines)
          Parses Guest LAN output from the query networks SMAPI call.
private  LinkedList parseNetworks(LinkedList tokens)
          Parses output from the query networks SMAPI call.
private  LinkedList parseServerStream(String data)
          Parses raw data returned from the SMAPI server and returns a LinkedList of Strings representing the returned data.
private  Network parseVSwitch(LinkedList lines)
          Parses VSwitch output from the query networks SMAPI call.
 void prototypeCreate(String name, LinkedList linesList)
          Corresponds to the SMAPI procedure PROTOTYPE_CREATE.
 void prototypeDelete(String prototypeName)
          Corresponds to the SMAPI procedure PROTOTYPE_DELETE.
 LinkedList prototypeNameQuery()
          Corresponds to the SMAPI procedure PROTOTYPE_NAME_QUERY.
 LinkedList prototypeQuery(String prototypeName)
          Corresponds to the SMAPI procedure PROTOTYPE_QUERY.
 LinkedList queryNetworkMembers(String netName)
          UNOFFICIAL: This function returns the members of a specified VSwitch, or all VSwitches on the system.
private  String readUntilSeeChar(StringBuffer sb, byte character)
          Read from a string buffer until we need a given character, remove and return all the read data.
 LinkedList returnQueryVirtual(String guestName)
          UNOFFICIAL: Returns the results of QUERY VIRTUAL for the given guest.
 void sharedStorageAddAccess(String guestName, String segmentName)
          Corresponds to the SMAPI procedure SHARED_STORAGE_ACCESS_ADD.
 void sharedStorageCreate(String guestName, String segmentName, String pageRange, String accessDescriptor)
           
 void sharedStorageDelete(String guestName, String segmentName)
          Corresponds to the SMAPI procedure SHARED_STORAGE_DELETE.
 String sharedStorageFindPageRange(String segmentSizeInMB, String guestName)
          UNOFFICIAL: Given a guest to use as a model, find an appropriate page range for a new shared segment of the given size.
 LinkedList sharedStorageQuery()
          UNOFFICIAL: We currently use an unofficial call to do this.
 boolean sharedStorageQueryAccess(String guestToQuery, String segToQuery)
          Queries access information for a shared storage segment.
 void sharedStorageRemoveAccess(String guestName, String segmentName)
          Corresponds to the SMAPI procedure SHARED_STORAGE_ACCESS_REMOVE.
 void virtualLANCreate(String lanName)
          UNOFFICIAL: Creates a guest LAN.
 int virtualLANCreateAndConnect(String lanName, String guestName)
          Corresponds to the SMAPI procedure VIRTUAL_NETWORK_LAN_CONNECT.
 int virtualLANCreateAndConnectDM(String lanName, String guestName, String vaddr)
          Corresponds to the SMAPI procedure VIRTUAL_NETWORK_LAN_CONNECT_DM.
 int virtualLANDisconnectAndDelete(String lanName, String guestName, String vaddr)
          Corresponds to the SMAPI procedure VIRTUAL_NETWORK_LAN_DISCONNECT.
 int virtualLANDisconnectAndDeleteDM(String lanName, String guestName, String vaddr)
          Corresponds to the SMAPI procedure VIRTUAL_NETWORK_LAN_DISCONNECT_DM.
 LinkedList virtualLanQuery()
          Corresponds to the SMAPI procedure VIRTUAL_NETWORK_LAN_QUERY.
 void virtualSwitchCreate(String switchName, String portname, String raddr)
          UNOFFICIAL: Creates a VSwitch with the given parameters.
 int virtualSwitchCreateAndConnect(String switchName, String guestName, String vaddr, String portname, String raddr)
          Corresponds to the SMAPI procedure VIRTUAL_NETWORK_VSWITCH_CONNECT.
 int virtualSwitchCreateAndConnectDM(String switchName, String guestName, String vaddr, String portname, String raddr)
          Corresponds to the SMAPI procedure VIRTUAL_NETWORK_VSWITCH_CONNECT_DM.
 void virtualSwitchDelete(String switchName)
          UNOFFICIAL: Deletes a VSwitch from the system.
 void virtualSwitchDetatch(String guestName, String vaddr)
          UNOFFICIAL: Detatches a guest's virtual NIC from the VSwitch it is attched to.
 int virtualSwitchDisconnectAndDelete(String guestName, String switchName, String vaddr)
          Corresponds to the SMAPI procedure VIRTUAL_NETWORK_VSWITCH_DISCONNECT.
 int virtualSwitchDisconnectAndDeleteDM(String guestName, String switchName, String vaddr)
          Corresponds to the SMAPI procedure VIRTUAL_NETWORK_VSWITCH_DISCONNECT.
 void virtualSwitchSet(String switchName, String grantID, String revokeID)
          Corresponds to the SMAPI procedure VIRTUAL_NETWORK_VSWITCH_SET.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NAMELIST_QUERY

private static final String NAMELIST_QUERY
See Also:
Constant Field Values

AUTH_LIST_ADD

private static final String AUTH_LIST_ADD
See Also:
Constant Field Values

AUTH_LIST_QUERY

private static final String AUTH_LIST_QUERY
See Also:
Constant Field Values

AUTH_LIST_REM

private static final String AUTH_LIST_REM
See Also:
Constant Field Values

IMAGE_ACTIV

private static final String IMAGE_ACTIV
See Also:
Constant Field Values

IMAGE_CREATE_DM

private static final String IMAGE_CREATE_DM
See Also:
Constant Field Values

IMAGE_DEACT

private static final String IMAGE_DEACT
See Also:
Constant Field Values

IMAGE_DELETE_DM

private static final String IMAGE_DELETE_DM
See Also:
Constant Field Values

IMAGE_DEDICATE

private static final String IMAGE_DEDICATE
See Also:
Constant Field Values

IMAGE_DEDIC_DM

private static final String IMAGE_DEDIC_DM
See Also:
Constant Field Values

IMAGE_DEV_RESE

private static final String IMAGE_DEV_RESE
See Also:
Constant Field Values

IMAGE_UNDED

private static final String IMAGE_UNDED
See Also:
Constant Field Values

IMAGE_UNDED_DM

private static final String IMAGE_UNDED_DM
See Also:
Constant Field Values

IMAGE_DISK_CP

private static final String IMAGE_DISK_CP
See Also:
Constant Field Values

IMAGE_DISK_CP_DM

private static final String IMAGE_DISK_CP_DM
See Also:
Constant Field Values

IMAGE_DISK_CREAT

private static final String IMAGE_DISK_CREAT
See Also:
Constant Field Values

IMAGE_DISK_CREAT_DM

private static final String IMAGE_DISK_CREAT_DM
See Also:
Constant Field Values

IMAGE_DISK_DEL

private static final String IMAGE_DISK_DEL
See Also:
Constant Field Values

IMAGE_DISK_DEL_DM

private static final String IMAGE_DISK_DEL_DM
See Also:
Constant Field Values

IMAGE_DISK_SH

private static final String IMAGE_DISK_SH
See Also:
Constant Field Values

IMAGE_DISK_SH_DM

private static final String IMAGE_DISK_SH_DM
See Also:
Constant Field Values

IMAGE_DISK_UNSH

private static final String IMAGE_DISK_UNSH
See Also:
Constant Field Values

IMAGE_DISK_UNSH_DM

private static final String IMAGE_DISK_UNSH_DM
See Also:
Constant Field Values

IMAGE_LOCK_DM

private static final String IMAGE_LOCK_DM
See Also:
Constant Field Values

IMAGE_NAME_QU_DM

private static final String IMAGE_NAME_QU_DM
See Also:
Constant Field Values

IMAGE_PSWD_SET_DM

private static final String IMAGE_PSWD_SET_DM
See Also:
Constant Field Values

IMAGE_QUERY_DM

private static final String IMAGE_QUERY_DM
See Also:
Constant Field Values

IMAGE_RECY

private static final String IMAGE_RECY
See Also:
Constant Field Values

IMAGE_REPLACE_DM

private static final String IMAGE_REPLACE_DM
See Also:
Constant Field Values

IMAGE_STAT_QUER

private static final String IMAGE_STAT_QUER
See Also:
Constant Field Values

IMAGE_UNLCK_DM

private static final String IMAGE_UNLCK_DM
See Also:
Constant Field Values

IMAGE_VOL_ADD

private static final String IMAGE_VOL_ADD
See Also:
Constant Field Values

IMAGE_VOL_DEL

private static final String IMAGE_VOL_DEL
See Also:
Constant Field Values

IMAGE_VOL_DEF_DM

private static final String IMAGE_VOL_DEF_DM
See Also:
Constant Field Values

IMAGE_VOL_QUE_DM

private static final String IMAGE_VOL_QUE_DM
See Also:
Constant Field Values

IMAGE_VOL_REM_DM

private static final String IMAGE_VOL_REM_DM
See Also:
Constant Field Values

NAME_LIST_ADD

private static final String NAME_LIST_ADD
See Also:
Constant Field Values

NAME_LIST_DES

private static final String NAME_LIST_DES
See Also:
Constant Field Values

NAME_LIST_REM

private static final String NAME_LIST_REM
See Also:
Constant Field Values

PROTO_CREA_DM

private static final String PROTO_CREA_DM
See Also:
Constant Field Values

PROTO_DEL_DM

private static final String PROTO_DEL_DM
See Also:
Constant Field Values

PROTO_NM_QU_DM

private static final String PROTO_NM_QU_DM
See Also:
Constant Field Values

PROTO_QUE_DM

private static final String PROTO_QUE_DM
See Also:
Constant Field Values

PROTO_REPL_DM

private static final String PROTO_REPL_DM
See Also:
Constant Field Values

SS_ACC_ADD_DM

private static final String SS_ACC_ADD_DM
See Also:
Constant Field Values

SS_ACC_QUE_DM

private static final String SS_ACC_QUE_DM
See Also:
Constant Field Values

SS_ACC_REM_DM

private static final String SS_ACC_REM_DM
See Also:
Constant Field Values

SS_CREATE

private static final String SS_CREATE
See Also:
Constant Field Values

SS_DELETE

private static final String SS_DELETE
See Also:
Constant Field Values

SS_QUERY

private static final String SS_QUERY
See Also:
Constant Field Values

SS_REPLACE

private static final String SS_REPLACE
See Also:
Constant Field Values

STAT_CHANG_ACT_DM

private static final String STAT_CHANG_ACT_DM
See Also:
Constant Field Values

STAT_CHANG_DEA_DM

private static final String STAT_CHANG_DEA_DM
See Also:
Constant Field Values

STAT_CHANG_IMM_DM

private static final String STAT_CHANG_IMM_DM
See Also:
Constant Field Values

VIRT_NET_AD_CR

private static final String VIRT_NET_AD_CR
See Also:
Constant Field Values

VIRT_NET_AD_CR_DM

private static final String VIRT_NET_AD_CR_DM
See Also:
Constant Field Values

VIRT_NET_AD_DE

private static final String VIRT_NET_AD_DE
See Also:
Constant Field Values

VIRT_NET_AD_DE_DM

private static final String VIRT_NET_AD_DE_DM
See Also:
Constant Field Values

VIRT_NET_CON_CR

private static final String VIRT_NET_CON_CR
See Also:
Constant Field Values

VIRT_NET_CON_CR_DM

private static final String VIRT_NET_CON_CR_DM
See Also:
Constant Field Values

VIRT_NET_CON_DE

private static final String VIRT_NET_CON_DE
See Also:
Constant Field Values

VIRT_NET_CON_DE_DM

private static final String VIRT_NET_CON_DE_DM
See Also:
Constant Field Values

VIRT_NET_LAN_CON

private static final String VIRT_NET_LAN_CON
See Also:
Constant Field Values

VIRT_NET_LAN_CON_DM

private static final String VIRT_NET_LAN_CON_DM
See Also:
Constant Field Values

VIRT_NET_LAN_DS

private static final String VIRT_NET_LAN_DS
See Also:
Constant Field Values

VIRT_NET_LAN_DS_DM

private static final String VIRT_NET_LAN_DS_DM
See Also:
Constant Field Values

VIRT_NET_LAN_QU

private static final String VIRT_NET_LAN_QU
See Also:
Constant Field Values

VIRT_NET_VSW_CON

private static final String VIRT_NET_VSW_CON
See Also:
Constant Field Values

VIRT_NET_VSW_CON_DM

private static final String VIRT_NET_VSW_CON_DM
See Also:
Constant Field Values

VIRT_NET_VSW_DS

private static final String VIRT_NET_VSW_DS
See Also:
Constant Field Values

VIRT_NET_VSW_DS_DM

private static final String VIRT_NET_VSW_DS_DM
See Also:
Constant Field Values

VIRT_NET_VSW_QUE

private static final String VIRT_NET_VSW_QUE
See Also:
Constant Field Values

VIRT_NET_VSW_SET

private static final String VIRT_NET_VSW_SET
See Also:
Constant Field Values

QUERY_ASYNC_OP

private static final String QUERY_ASYNC_OP
See Also:
Constant Field Values

NULL_CALL

private static final String NULL_CALL
See Also:
Constant Field Values

VIRT_NET_VSW_MAKE

private static final String VIRT_NET_VSW_MAKE
See Also:
Constant Field Values

ACTIVE_IMAGE_QUERY

private static final String ACTIVE_IMAGE_QUERY
See Also:
Constant Field Values

NAME_LIST_Q_ALL

private static final String NAME_LIST_Q_ALL
See Also:
Constant Field Values

QUERY_VIRTUAL

private static final String QUERY_VIRTUAL
See Also:
Constant Field Values

LOW_FREE_ADDR

private static final String LOW_FREE_ADDR
See Also:
Constant Field Values

FIND_STORAGE

private static final String FIND_STORAGE
See Also:
Constant Field Values

QUER_NIC_ADDR

private static final String QUER_NIC_ADDR
See Also:
Constant Field Values

QUER_NET_MEMBERS

private static final String QUER_NET_MEMBERS
See Also:
Constant Field Values

VIRT_SWIT_CREATE

private static final String VIRT_SWIT_CREATE
See Also:
Constant Field Values

VSW_DEL

private static final String VSW_DEL
See Also:
Constant Field Values

VSW_DET

private static final String VSW_DET
See Also:
Constant Field Values

B_NULL

private static final byte B_NULL
See Also:
Constant Field Values

B_LINETERM

private static final byte B_LINETERM
See Also:
Constant Field Values

B_SPACE

private static final byte B_SPACE
See Also:
Constant Field Values

NL_GUESTADDED

public static final int NL_GUESTADDED
See Also:
Constant Field Values

NL_LISTMADE_GUESTADDED

public static final int NL_LISTMADE_GUESTADDED
See Also:
Constant Field Values

NL_LISTMADE_GUESTTHERE

public static final int NL_LISTMADE_GUESTTHERE
See Also:
Constant Field Values

hostName

private String hostName

port

private int port

userName

private String userName

password

private String password
Constructor Detail

SMAPI_Interface

public SMAPI_Interface(String hostName,
                       int port,
                       String userName,
                       String password)
Creates a new SMAPI Interface object with the given parameters. The userName and password parameter are used to authenticate to the SMAPI server.

Parameters:
hostName - The host name or IP address of the z/VM system to connect to.
port - The port number the SMAPI server is listening on.
userName - The user name used to authenticate to the SMAPI server.
password - The password used to authenticate to the SMAPI server.
Method Detail

nullRequest

public void nullRequest()
                 throws exceptions.SMAPIException
Executes a simple SMAPI call that does nothing other than authenticate with the SMAPI server. This serves no purpose other than to check and see if the username and password supplied are a valid combination.

Throws:
exceptions.SMAPIException

nameListQuery

public LinkedList nameListQuery(String listName)
                         throws exceptions.SMAPIException
Corresponds to the SMAPI procedure NAME_LIST_QUERY. Queries the contents of a name list.

Parameters:
listName - The name of the namelist to query.
Returns:
LinkedList A List of Strings, each one is a name in the namelist querried.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

nameListAdd

public int nameListAdd(String listName,
                       String nameToAdd)
                throws exceptions.SMAPIException
Corresponds to the SMAPI procedure NAME_LIST_ADD. Creates/adds a new name to a name list. This function will add a name to an existing name list. If the name list specified does not exist, a new list will be created and nameToAdd will be added to the new list. Returns an integer. The return value's meaning is as follows: 0 - the guest was added to the (existing) name list 1 - the guest was added to a new name list 2 - the guest was already a member of the name list, and no change was made

Parameters:
listName - Name list to which an entry will be added.
nameToAdd - Name to add to the name list.
Returns:
0, 1, or 2 corresponding to addition, creation, or no change as described above.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

nameListDestroy

public void nameListDestroy(String listName)
                     throws exceptions.SMAPIException
Corresponds to the SMAPI procedure NAME_LIST_DESTROY. Deletes a name list.

Parameters:
listName - The name of the list to destroy.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

nameListRemove

public int nameListRemove(String strListName,
                          String strNameToRemove)
                   throws exceptions.SMAPIException
Corresponds to the SMAPI procedure NAME_LIST_REMOVE. Delete/remove an entry from a name list. If the removal causes the list to be empty, the list will be deleted. The return value's meaning is as follows: 0 - the guest was removed from the name list 1 - the guest was removed, list was destroyed 2 - the guest was not in the list

Parameters:
strListName - name list from which to remove an entry.
strNameToRemove - Name to remove from the name list.
Returns:
int Code to tell how the removal went.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

asynchronousCall

private void asynchronousCall(String asyncOperationID)
                       throws exceptions.SMAPIException
Corresponds to the SMAPI procedure QUERY_ASYNCHRONOUS_OPERATION_1. This call is used by smapilib to wait for asynchronous operations to complete. This is not something that can currently be used by the end user because smapilib automatically calls this function which will return as soon as the asyncronous operation is complete.

Parameters:
asyncOperationID - ID of the asynchronous operation.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

prototypeNameQuery

public LinkedList prototypeNameQuery()
                              throws exceptions.SMAPIException
Corresponds to the SMAPI procedure PROTOTYPE_NAME_QUERY. Used to obtain a list of all prototypes that exist.

Returns:
Linked list containing Strings corresponding to the prototype names.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

prototypeCreate

public void prototypeCreate(String name,
                            LinkedList linesList)
                     throws exceptions.SMAPIException
Corresponds to the SMAPI procedure PROTOTYPE_CREATE. Creates a new prototype based on the provided statements. A prototype is a pseudo directory entry that can be used as a model to create new guests.

Parameters:
name - The name of throws prototype to create
linesList - A LinkedList of strings. Each string is a line/entry in the new prototype.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

prototypeDelete

public void prototypeDelete(String prototypeName)
                     throws exceptions.SMAPIException
Corresponds to the SMAPI procedure PROTOTYPE_DELETE. Deletes an existing prototype.

Parameters:
prototypeName - Name of the prototype to delete.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

prototypeQuery

public LinkedList prototypeQuery(String prototypeName)
                          throws exceptions.SMAPIException
Corresponds to the SMAPI procedure PROTOTYPE_QUERY. Querries a prototype and returns its contents lines/entries are newline separated.

Parameters:
prototypeName - Name of the prototype to return.
Returns:
Contents of the prototype querried.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

imageNameQuery

public LinkedList imageNameQuery()
                          throws exceptions.SMAPIException
Corresponds to the SMAPI procedure IMAGE_NAME_QUERY. Obtains a complete list of guests defined on the system.

Returns:
LinkedList List containing all defined guests.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

imageCreate

public void imageCreate(String guestName,
                        String prototypeName,
                        String password)
                 throws exceptions.SMAPIException
Corresponds to the SMAPI procedure IMAGE_CREATE. Creates a new guest. The account number parameter to the original SMAPI call has ben ignored.

Parameters:
guestName - Name of the new guest.
prototypeName - Name of the prototype this guest will be modeled after.
password - Password for this guest.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

imageReplace

public void imageReplace(String imageName,
                         LinkedList imageDefLines)
                  throws exceptions.SMAPIException
Corresponds to the SMAPI procedure IMAGE_REPLACE. Replaces a guests directory entry with the specefied lines.

Parameters:
imageName - name of the guest to replace.
imageDefLines - Array containing strings that represent the lines of the new directory entry for this guest.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

imageDelete

public void imageDelete(String guestName)
                 throws exceptions.SMAPIException
Corresponds to the SMAPI procedure IMAGE_DELETE. Deletes a guest from the system.

Parameters:
guestName - name of the guest to delete.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

imageQuery

public LinkedList imageQuery(String guestName)
                      throws exceptions.SMAPIException
Corresponds to the SMAPI procedure IMAGE_QUERY. Querries a guest and returns the statements in the guests directory entry as a newline separated string.

Parameters:
guestName - The name of the guest to query.
Returns:
String containing this guests directory entry.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

imageSetPassword

public void imageSetPassword(String guestName,
                             String password)
                      throws exceptions.SMAPIException
Corresponds to the SMAPI procedure IMAGE_PASSWORD_SET. Changes the password for a guest.

Parameters:
guestName - Name of the guest to set the password for.
password - The new password for the guest.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

imageLock

public void imageLock(String guestName)
               throws exceptions.SMAPIException
Corresponds to the SMAPI procedure IMAGE_LOCK. Locks a guest so that changes cannot be made to it. Any changes to the guest or device will result in an "Image locked" error. This wraper does not allow you to locak individual devices, just the guest as a whole.

Parameters:
guestName - The guest to lock, or the guest who owns the device you wish to lock.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

imageUnlock

public void imageUnlock(String guestName)
                 throws exceptions.SMAPIException
Corresponds to the SMAPI procedure IMAGE_UNLOCK. unlocks a locked guest.

Parameters:
guestName - The guest to unlock
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

imageActivate

public void imageActivate(String guestName)
                   throws exceptions.SMAPIException
Corresponds to the SMAPI procedure IMAGE_ACTIVATE. Logs on a guest. Unlike the underlying SMAPI call, we do not allow the use of namelists here.

Parameters:
guestName - The guest (or name list) to activate (log on).
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

imageDeactivate

public void imageDeactivate(String guestName)
                     throws exceptions.SMAPIException
Corresponds to the SMAPI procedure IMAGE_DEACTIVATE. logs a guest off of the system. The underlying SMAPI call allws the caller to specify a time limit before the guest is forced off the system, we always force immediately to ensure quick deactivation.

Parameters:
guestName - The name of the guest to log off.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

virtualLanQuery

public LinkedList virtualLanQuery()
                           throws exceptions.SMAPIException
Corresponds to the SMAPI procedure VIRTUAL_NETWORK_LAN_QUERY. Querries all guest LANs and VSwitches on the system and returns the information as a LinkedList Network objects. The output Strings are equivalent to what you would get if you issed the CP command "QUERY LAN ALL". The underlying SMAPI call allows the caller to specific any LAN name, we only support querying all LANs.

Returns:
LinkedList of network objects.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

parseNetworks

private LinkedList parseNetworks(LinkedList tokens)
                          throws exceptions.SMAPIException
Parses output from the query networks SMAPI call. Reads the output from the SMAPI call VIRTUAL_NETWORK_LAN_QUERY and returns a list of Network objects, one for each network present in the output.

Parameters:
tokens - The output from VIRTUAL_NETWORK_LAN_QUERY
Returns:
LinkedList List of network objects.
Throws:
exceptions.SMAPIException

parseGLan

private Network parseGLan(LinkedList lines)
                   throws exceptions.SMAPIException
Parses Guest LAN output from the query networks SMAPI call. Given a section of output from VIRTUAL_NETWORK_LAN_QUERY, remove the lines corresponding to a Guest LAN existing at the top of the output from the list, parse those lines to determine information about the guest LAN, and return a Network object repreenting that guest LAN.

Parameters:
lines - Output from VIRTUAL_NETWORK_LAN_QUERY
Returns:
Network object representing a LAN.
Throws:
exceptions.SMAPIException

parseVSwitch

private Network parseVSwitch(LinkedList lines)
                      throws exceptions.SMAPIException
Parses VSwitch output from the query networks SMAPI call. Given a section of output from VIRTUAL_NETWORK_LAN_QUERY, remove the lines corresponding to a VSwitch existing at the top of the output from the list, parse those lines to determine information about the VSwitch, and return a Network object representing that VSwitch.

Parameters:
lines - Output from VIRTUAL_NETWORK_LAN_QUERY
Returns:
Network object representing a LAN.
Throws:
exceptions.SMAPIException

imageDiskCreate

public void imageDiskCreate(String strGuestName,
                            String strVirtualDeviceAddress,
                            String strAllocationType,
                            String strAllocUnitSize,
                            String strDiskSize,
                            String strDiskMode,
                            String strFormat,
                            String strReadPW,
                            String strWritePW,
                            String strMultiPW)
                     throws exceptions.SMAPIException
Creates a new minidisk for a guest

Parameters:
strGuestName - Guest to create minidisk for
strVirtualDeviceAddress - Virtual address to create minidisk at
strAllocationType - How to allocate minidisk (T, V, or AUTO)
strAllocUnitSize - What units to allocate the minidisk in (cylinders or blocks)
strDiskSize - How large of a disk to create
strDiskMode - What type of access to have for the minidisk (e.g. RR or RW)
strReadPW - ReadPW for the disk
strWritePW - WritePW for the disk
strMultiPW - MultiPW for the disk
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

imageDiskCreateDM

public void imageDiskCreateDM(String strGuestName,
                              String strVirtualDeviceAddress,
                              String strAllocationType,
                              String strAllocUnitSize,
                              String strDiskSize,
                              String strDiskMode,
                              String strFormat,
                              String strReadPW,
                              String strWritePW,
                              String strMultiPW)
                       throws exceptions.SMAPIException
Creates a new minidisk for a guest's directory entry

Parameters:
strGuestName - Guest to create minidisk for
strVirtualDeviceAddress - Virtual address to create minidisk at
strAllocationType - How to allocate minidisk (T, V, or AUTO)
strAllocUnitSize - What units to allocate the minidisk in (cylinders or blocks)
strDiskSize - How large of a disk to create
strDiskMode - What type of access to have for the minidisk (e.g. RR or RW)
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

imageDiskDelete

public void imageDiskDelete(String strGuestName,
                            String strVirtualDeviceAddress)
                     throws exceptions.SMAPIException
This function deletes a minidisk from a guest

Parameters:
strGuestName - Name of guest to delete disk from
strVirtualDeviceAddress - Virtual Device of disk to delete
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

imageDiskDeleteDM

public void imageDiskDeleteDM(String strGuestName,
                              String strVirtualDeviceAddress)
                       throws exceptions.SMAPIException
This function deletes a minidisk from a guest's directory entry

Parameters:
strGuestName - Name of guest to delete disk from
strVirtualDeviceAddress - Virtual Device of disk to delete
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

imageDiskCopy

public int imageDiskCopy(String strGuestName,
                         String strVirtualDeviceAddress,
                         String strSourceImageName,
                         String strSourceDeviceAddress,
                         String strAllocationType,
                         String strDiskMode,
                         String strReadPW,
                         String strWritePW,
                         String strMultiPW)
                  throws exceptions.SMAPIException
Copies a minidisk from one guest to another

Parameters:
strGuestName - Guest to copy minidisk to
strVirtualDeviceAddress - Virtual address to copy minidisk to
strSourceImageName - Guest to copy minidisk from
strSourceDeviceAddress - Virtual address to copy minidisk from
strAllocationType - How to allocate minidisk (AUTO G, R, or V)
strDiskMode - What type of access to have for the minidisk (e.g. RR or RW)
strReadPW - Read access password
strWritePW - Write access password
strMultiPW - Multi access password
Returns:
int 0 if the operation has returned without a failure, 1 if the DirMaint bug has shown up and we cannot determine if the call completed successfully (see comments)
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

imageDiskCopyDM

public int imageDiskCopyDM(String strGuestName,
                           String strVirtualDeviceAddress,
                           String strSourceImageName,
                           String strSourceDeviceAddress,
                           String strAllocationType,
                           String strDiskMode,
                           String strReadPW,
                           String strWritePW,
                           String strMultiPW)
                    throws exceptions.SMAPIException
Copies a minidisk from one guest's directory to another guest's directory

Parameters:
strGuestName - Guest to copy minidisk to
strVirtualDeviceAddress - Virtual address to copy minidisk to
strSourceImageName - Guest to copy minidisk from
strSourceDeviceAddress - Virtual address to copy minidisk from
strAllocationType - How to allocate minidisk (AUTO G, R, or V)
strDiskMode - What type of access to have for the minidisk (e.g. RR or RW)
strReadPW - Read access password
strWritePW - Write access password
strMultiPW - Multi access password
Returns:
int 0 if the operation has returned without a failure, 1 if the DirMaint bug has shown up and we cannot determine if the call completed successfully (see comments)
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

imageDiskShare

public void imageDiskShare(String sourceGuestName,
                           String sourceVaddr,
                           String destGuestName,
                           String destVaddr,
                           String accMode,
                           String passwordNeededToLink)
                    throws exceptions.SMAPIException
Corresponds to the SMAPI procedure IMAGE_DISK_SHARE. Creates a link to a guests virtual disk.

Parameters:
sourceGuestName - The name of the guest that owns the disk to be shared.
sourceVaddr - The address of the disk to be shared.
destGuestName - The guest that will obtain the link to the shared disk.
destVaddr - The virtual address that will be created and linked to the shared disk.
accMode - The mode that the disk will be shared in.
passwordNeededToLink - Optional. Password used to access the disk. Pass empty string to ignore this password.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

imageDiskShareDM

public void imageDiskShareDM(String sourceGuestName,
                             String sourceVaddr,
                             String destGuestName,
                             String destVaddr,
                             String accMode,
                             String passwordNeededToLink)
                      throws exceptions.SMAPIException
Corresponds to the SMAPI procedure IMAGE_DISK_SHARE. Creates a link to a guests virtual disk. This call modfies the user directory entry for this guest.

Parameters:
sourceGuestName - The name of the guest that owns the disk to be shared.
sourceVaddr - The address of the disk to be shared.
destGuestName - The guest that will obtain the link to the shared disk.
destVaddr - The virtual address that will be created and linked to the shared disk.
accMode - The mode that the disk will be shared in.
passwordNeededToLink - Optional. Password used to access the disk. Pass empty string to ignore this password.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

imageDiskUnshare

public void imageDiskUnshare(String guestUsingDisk,
                             String vaddrOfGuestUsingDisk,
                             String guestOwningDisk,
                             String vaddrOfGuestOwningDisk)
                      throws exceptions.SMAPIException
Corresponds to the SMAPI procedure IMAGE_DISK_UNSHARE. Removes a link to another guests disk.

Parameters:
guestUsingDisk - Name of the guest linking to the disk.
vaddrOfGuestUsingDisk - Virtual address of disk with respect to the guest with the link.
guestOwningDisk - Guest that owns the disk being linked to
vaddrOfGuestOwningDisk - Virtual address of disk with respect to the guest that owns the disk.
Throws:
exceptions.SMAPIException

imageDiskUnshareDM

public void imageDiskUnshareDM(String guestUsingDisk,
                               String vaddrOfGuestUsingDisk,
                               String guestOwningDisk,
                               String vaddrOfGuestOwningDisk)
                        throws exceptions.SMAPIException
Corresponds to the SMAPI procedure IMAGE_DISK_UNSHARE. Removes a link to another guests disk. This call modfies the user directory entry for this guest.

Parameters:
guestUsingDisk - Name of the guest linking to the disk.
vaddrOfGuestUsingDisk - Virtual address of disk with respect to the guest with the link.
guestOwningDisk - Guest that owns the disk being linked to
vaddrOfGuestOwningDisk - Virtual address of disk with respect to the guest that owns the disk.
Throws:
exceptions.SMAPIException

virtualLANCreateAndConnect

public int virtualLANCreateAndConnect(String lanName,
                                      String guestName)
                               throws exceptions.SMAPIException
Corresponds to the SMAPI procedure VIRTUAL_NETWORK_LAN_CONNECT. Creates a virtual LAN (if it does not already exist) and connects a VNIC to it. The VNIC is also created on the fly. This is the only official SMAPI method to couple a VNIC to a VLAN. Many parameters to the underlying SMAPI call are set to sane defaults. The resulting LAN will always be a QDIO, IP based SYSTEM owned LAN. The resulting VNIC will have allocated 3 devices.

Parameters:
lanName - The name of the LAN to couple to.
guestName - Guest owning the NIC.
Returns:
int 0 guest added to pre-existing guest LAN, 1 object directory offline, 2 new lan created
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

virtualLANCreateAndConnectDM

public int virtualLANCreateAndConnectDM(String lanName,
                                        String guestName,
                                        String vaddr)
                                 throws exceptions.SMAPIException
Corresponds to the SMAPI procedure VIRTUAL_NETWORK_LAN_CONNECT_DM. This call updates the guest directory entry. Creates a virtual LAN (if it does not already exist) and connects a VNIC to it. The VNIC is also created on the fly. This is the only official SMAPI method to couple a VNIC to a VLAN. Many parameters to the underlying SMAPI call are set to sane defaults. The resulting LAN will always be a QDIO, IP based SYSTEM owned LAN. The resulting VNIC will have allocated 3 devices.

Parameters:
lanName - The name of the LAN to couple to.
guestName - Guest owning the NIC.
vaddr - guestName virtual address of the new virtual NIC.
Returns:
int 0 guest added to pre-existing guest LAN, 1 object directory offline, 2 new lan created
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

virtualLANDisconnectAndDelete

public int virtualLANDisconnectAndDelete(String lanName,
                                         String guestName,
                                         String vaddr)
                                  throws exceptions.SMAPIException
Corresponds to the SMAPI procedure VIRTUAL_NETWORK_LAN_DISCONNECT. Disconnects a virtual NIC from a guest LAN and deletes the LAN if there are no more NICs connected to it.

Parameters:
lanName - The LAN to delete the NIC from.
guestName - Guest owning the NIC to delete.
vaddr - Base address of the NIC to delete.
Returns:
int 0 guest deleted from lan, 1 object directory is offline, 2 lan deleted
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

virtualLANDisconnectAndDeleteDM

public int virtualLANDisconnectAndDeleteDM(String lanName,
                                           String guestName,
                                           String vaddr)
                                    throws exceptions.SMAPIException
Corresponds to the SMAPI procedure VIRTUAL_NETWORK_LAN_DISCONNECT_DM. Disconnects a virtual NIC from a guest LAN and deletes the LAN if there are no more NICs connected to it. This call modifies the guests drectory entry.

Parameters:
lanName - The LAN to delete the NIC from.
guestName - Guest owning the NIC to delete.
vaddr - Base address of the NIC to delete.
Returns:
int 0 guest deleted from lan, 1 object directory is offline, 2 lan deleted
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

virtualSwitchCreateAndConnect

public int virtualSwitchCreateAndConnect(String switchName,
                                         String guestName,
                                         String vaddr,
                                         String portname,
                                         String raddr)
                                  throws exceptions.SMAPIException
Corresponds to the SMAPI procedure VIRTUAL_NETWORK_VSWITCH_CONNECT. Creates a virtual switch (if it does not already exist) and connects a VNIC to it. The VNIC is also created on the fly. This is the only official SMAPI method to couple a VNIC to a VSWITCH.

Parameters:
switchName - name of the VSWITCH to create/connect NIC to.
guestName - Guest to own NIC.
vaddr - Base address for NIC.
portname - The port name to connect the real device to
raddr - The physical address of the real OSA device
Returns:
int 0 guest connected to switch, 1 object directory is offline, 2 switch created
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

virtualSwitchCreateAndConnectDM

public int virtualSwitchCreateAndConnectDM(String switchName,
                                           String guestName,
                                           String vaddr,
                                           String portname,
                                           String raddr)
                                    throws exceptions.SMAPIException
Corresponds to the SMAPI procedure VIRTUAL_NETWORK_VSWITCH_CONNECT_DM. This call modifies the guests directory entry. This call connects a guest to a VSwitch

Parameters:
switchName - name of the VSWITCH to create/connect NIC to.
guestName - Guest to own NIC.
vaddr - Base address for NIC.
portname - The port name to connect the real device to
raddr - The physical address of the real OSA device
Returns:
int 0 guest added to switch, 1 object directory is offline, 2 switch created
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

virtualSwitchCreate

public void virtualSwitchCreate(String switchName,
                                String portname,
                                String raddr)
                         throws exceptions.SMAPIException
UNOFFICIAL: Creates a VSwitch with the given parameters. Does not require you to create or couple any virtual NIC at the time of creation, unlike the official SMAPI call.

Parameters:
switchName - Name of the VSwitch you are creating
portname - The portname for the real device attached to this VSwitch.
raddr - The address for the real device attached to this VSwitch.
Throws:
exceptions.SMAPIException

virtualLANCreate

public void virtualLANCreate(String lanName)
                      throws exceptions.SMAPIException
UNOFFICIAL: Creates a guest LAN. Does not require you to create or couple any virtual NIC at the time of creation, unlike the official SMAPI call.

Parameters:
lanName - Name of the guest LAN you are creating
Throws:
exceptions.SMAPIException

virtualSwitchSet

public void virtualSwitchSet(String switchName,
                             String grantID,
                             String revokeID)
                      throws exceptions.SMAPIException
Corresponds to the SMAPI procedure VIRTUAL_NETWORK_VSWITCH_SET. The underlying SMAPI call allows the caller to Set or change many different VSWITCH parameters. Our implementation only allows the use of VSwitch Set to grant/revoke guest access to the given VSwitch.

Parameters:
switchName - name of the VSWITCH to modify.
grantID - userID to grant access to the VSWITCH.
revokeID - userID to revoke access to the VSWITCH.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

virtualSwitchDisconnectAndDelete

public int virtualSwitchDisconnectAndDelete(String guestName,
                                            String switchName,
                                            String vaddr)
                                     throws exceptions.SMAPIException
Corresponds to the SMAPI procedure VIRTUAL_NETWORK_VSWITCH_DISCONNECT. Disconnects a virtual NIC from a VSWITCH and deletes the VSWITCH if there are no more NICs connected to it.

Parameters:
guestName - Guest owning the NIC to delete.
switchName - Name of VSWITCH.
vaddr - Base address of NIC.
Returns:
int 0 for guest removed from VSwitch, 1 object directory is offline, 2 VSwitch deleted
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

virtualSwitchDisconnectAndDeleteDM

public int virtualSwitchDisconnectAndDeleteDM(String guestName,
                                              String switchName,
                                              String vaddr)
                                       throws exceptions.SMAPIException
Corresponds to the SMAPI procedure VIRTUAL_NETWORK_VSWITCH_DISCONNECT. Disconnects a virtual NIC from a VSWITCH. This call modifies the guests directory entry.

Parameters:
guestName - Guest owning the NIC to delete.
switchName - Name of VSWITCH.
vaddr - Basee address of NIC.
Returns:
int 0 guest removed from VSwitch, 1 object directory offline, 2 VSwitch deleted
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

sharedStorageFindPageRange

public String sharedStorageFindPageRange(String segmentSizeInMB,
                                         String guestName)
                                  throws exceptions.SMAPIException
UNOFFICIAL: Given a guest to use as a model, find an appropriate page range for a new shared segment of the given size. The returned range will be above the models address space to ensure that no conflicts occur.

Parameters:
segmentSizeInMB - Size of desired shared segment.
guestName - Guest to use as model.
Returns:
String a string in the format nnnn-mmmm where nnnn and mmmm are both hexadecimal page numbers.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

sharedStorageCreate

public void sharedStorageCreate(String guestName,
                                String segmentName,
                                String pageRange,
                                String accessDescriptor)
                         throws exceptions.SMAPIException
Throws:
exceptions.SMAPIException

sharedStorageDelete

public void sharedStorageDelete(String guestName,
                                String segmentName)
                         throws exceptions.SMAPIException
Corresponds to the SMAPI procedure SHARED_STORAGE_DELETE. Deletes a shared storage segment.

Parameters:
guestName - Guest owning the segment.
segmentName - name of segment.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

sharedStorageQuery

public LinkedList sharedStorageQuery()
                              throws exceptions.SMAPIException
UNOFFICIAL: We currently use an unofficial call to do this. Corresponds to the SMAPI procedure SHARED_STORAGE_QUERY. Querries and returns info for all shared segments on the system.

Returns:
LinkedList corresponding to a Q NSS ALL command.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

sharedStorageAddAccess

public void sharedStorageAddAccess(String guestName,
                                   String segmentName)
                            throws exceptions.SMAPIException
Corresponds to the SMAPI procedure SHARED_STORAGE_ACCESS_ADD. Adds restricted access to a shared storage segment.

Parameters:
guestName - guest to give access.
segmentName - Segment name.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

sharedStorageRemoveAccess

public void sharedStorageRemoveAccess(String guestName,
                                      String segmentName)
                               throws exceptions.SMAPIException
Corresponds to the SMAPI procedure SHARED_STORAGE_ACCESS_REMOVE. Removes access to a shared storage segment.

Parameters:
guestName - Guest for whom to remove access.
segmentName - Segment name.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

sharedStorageQueryAccess

public boolean sharedStorageQueryAccess(String guestToQuery,
                                        String segToQuery)
                                 throws exceptions.SMAPIException
Queries access information for a shared storage segment.

Parameters:
guestToQuery - Name of the guest for whom to query shared storage segments
segToQuery - Name of the segment to query information for
Returns:
boolean Whether the guest is on the access list for the shared storage segment
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

returnQueryVirtual

public LinkedList returnQueryVirtual(String guestName)
                              throws exceptions.SMAPIException
UNOFFICIAL: Returns the results of QUERY VIRTUAL for the given guest. Can be parsed to get the used and free virtual addresses. The return value has the following format: USERNAME 0009 ON LDEV L0005 TERM START HOST TCPIP FROM 9.60.66.183 0009 CL T NOCONT NOHOLD COPY 001 READY FORM STANDARD 0009 TO OP1 RDR DIST OPERATOR FLASHC 000 DEST OFF 0009 FLASH CHAR MDFY 0 FCB LPP OFF 0009 3215 NOEOF OPEN 0046 NOKEEP NOMSG NONAME 0009 SUBCHANNEL = 0011 DASD 0190 3390 510RES R/O 107 CYL ON DASD 0700 SUBCHANNEL = 0012 NICS 1030 ON NIC 1030 UNIT 000 SUBCHANNEL = 0000 1030 QDIO-ELIGIBLE QIOASSIST NOT AVAILABLE

Parameters:
guestName - Guest for which to query virtual adddresses.
Returns:
LinkedList of strings, where each string is one line of results from Query Virtual
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

getLowestFreeAddress

public String getLowestFreeAddress(String guestName,
                                   String size)
                            throws exceptions.SMAPIException
UNOFFICIAL: Returns the lowest free virtual address for a particular user.

Parameters:
guestName - Guest to query.
size - Size of free virtual address space needed (i.e. NICS need 3)
Returns:
String Four digit hexadecimal number representing the starting address of the free virtual address space.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

queryNetworkMembers

public LinkedList queryNetworkMembers(String netName)
                               throws exceptions.SMAPIException
UNOFFICIAL: This function returns the members of a specified VSwitch, or all VSwitches on the system. The members list is obtained by issuing a Q VSWITCH netName ACC and reading the access lsit. The results are returned in a LinkedList of Networks.

Parameters:
netName - Name of the network to query, use "" or "&" to query all networks
Returns:
LinkedList of Networks, each with containing only network name and members
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

getNICaddress

public String getNICaddress(String netName,
                            String guestName)
                     throws exceptions.SMAPIException
UNOFFICIAL: This function returns the virtual address of a specified NIC for a specified user on a specified network .

Parameters:
netName - Name of the network the NIC is attached to.
guestName - Name of the guest to query on the given network
Returns:
String 4 digit hexadecimal number that is the starting address of the NICs address space.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

nameListQueryAll

public LinkedList nameListQueryAll()
                            throws exceptions.SMAPIException
UNOFFICIAL: This function returns all information from the SMAPI namelist file which is used to store the SMAPIs namelists and their members.

Returns:
LinkedList of NameLists
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

activeImagesQuery

public LinkedList activeImagesQuery()
                             throws exceptions.SMAPIException
UNOFFICIAL: This function returns a LinkedList of Strings. Each String represents a guest who is currently active.

Returns:
LinkedList of Strings (guest names)
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

virtualSwitchDelete

public void virtualSwitchDelete(String switchName)
                         throws exceptions.SMAPIException
UNOFFICIAL: Deletes a VSwitch from the system. Unlike the official SMAPI call, this one does not require that you decouple a specific virtual NIC before deleting the VSwitch.

Parameters:
switchName - Name of the switch to delete.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

virtualSwitchDetatch

public void virtualSwitchDetatch(String guestName,
                                 String vaddr)
                          throws exceptions.SMAPIException
UNOFFICIAL: Detatches a guest's virtual NIC from the VSwitch it is attched to. Unlike the official SMAPI call, this one does not delete the VSwitch if no online user in connected to it after the detatch.

Parameters:
guestName - Name of guest obtaining the NIC to detatch.
vaddr - The virtual address of the NIC to detatch.
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

connectRequest

private LinkedList connectRequest(String functionName,
                                  String parms)
                           throws exceptions.SMAPIException
Executes the requested SMAPI function given its name and parameters. Will return a linked list of strings. The first sting will be the RC, the second string will be the RS. The number of and meaning of the rest of the strings in the list is dependant on the exact SMAPI call being made. The parms String should be space delimited. If you wish to ignore an optional parameter a '&' character should appear in its place in the parms String.

Parameters:
functionName - The short name of the SMAPI function to be called.
parms - The space delimited list of paramters for the given SMAPI call.
Returns:
LinkedList RC, RS, and return information from the call
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

connectRequestRAW

private LinkedList connectRequestRAW(String functionName,
                                     String parms)
                              throws exceptions.SMAPIException
Executes the requested SMAPI function given its name and parameters. Will return a linked list of strings. The first sting will be the RC, the second string will be the RS. The number of and meaning of the rest of the strings in the list is dependant on the exact SMAPI call being made. The parms String is assumed to already be null delimited and correctly formatted to be sent off to the server. SMAPI calls with special formatting needs should use this call. The parms String is passed to the SMAPI server "AS IS".

Parameters:
functionName - The short name of the SMAPI function to be called.
parms - The paramters for the given SMAPI call, passed "AS IS".
Returns:
LinkedList RC RS and return information from the call
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException

parseServerStream

private LinkedList parseServerStream(String data)
Parses raw data returned from the SMAPI server and returns a LinkedList of Strings representing the returned data.

Parameters:
data - Raw data from the SMAPI server.
Returns:
LinkedList of Strings representing the returned data.

readUntilSeeChar

private String readUntilSeeChar(StringBuffer sb,
                                byte character)
Read from a string buffer until we need a given character, remove and return all the read data.

Parameters:
sb - A StringBuffer containing the data to search through.
character - The character we are looking for.
Returns:
String the data that was found before the requested character.

errorCheck

private void errorCheck(String desc,
                        int rc,
                        int rs)
                 throws exceptions.SMAPIException
Given an RC/RS pair, compare them against known errors and throw an appropriate exception if an error is detected. The message for the exception will contain a desc String passed in. The desc Strng is meant to contain a description of the function calling errorCheck() so the programmer will have a little more information when debugging. With proper descriptive messages, the error mesasges given from this function could possible be shown directly to and end-user. If this function returns without throwing an exception, no error was detected.

Parameters:
desc - String describing the function calling errorCheck.
rc - SMAPI return code
rs - SMAPI result code
Throws:
SMAPIException - An error occurred. This is the parent exception for all other exceptions in this library.
exceptions.SMAPIException


Copyright © 2005