STAFUpgradeUtil.xml

STAFUpgrade

Upgrades the version of STAF running on a remote target machine. The target machine where STAF will be upgraded to a new version must already have STAF running.

Note that this version of STAFUpgradeUtil.xml only supports upgrading target machine(s) to STAF V3.3.0 or later.

The minimum version of STAF that must be running on the target machine is:

• 3.0.0 if the target machine is a Windows machine
• 3.1.3 if the target machine is a Unix machine

The STAX machine must be running STAF V3.1.0 or later.

The target machine(s) must give the STAX machine trust level 5 and must give the installer machine trust level 4 or higher.

The installer machine must give the STAX machine trust level 4 or higher.

The STAF installer files must be downloaded to a single directory on the installer machine so that this function can copy the appropriate STAF installer file from the installer machine to the remote target machine. Note that only the InstallAnywhere Bundled JVM installer files (e.g. STAFxxxx-setup-linux.bin, STAFxxxx-setup-win32.exe) and GNU zipped tar installer files (e.g. STAFxxxx-linux-tar.gz) are supported by this function. The InstallAnywhere NoJVM installer files (e.g. STAFxxxx-setup-linux-NoJVM.bin) are not supported.

A STAF upgrade doesn't automatically use the same settings that were selected by the previous STAF install. Also, this function doesn't support every STAF installation option, such as overriding the version of STAF Python, Perl, or Tcl support installed by default.

Notes:

1. This is the function you call to upgrade STAF. All of the other functions in this library are just "helper" functions and are not intended to by called by other functions.
2. You must import all of the functions in this library file to use this function.
3. This function also requires that you import functions from the STAXUtil.xml library file.

This function takes an argument map
Name	Description	Required	Private	Default	Properties
targetMachine	The endpoint for the target machine on which you want to upgrade STAF. If your target machine does not have a STAF interface listening on the same port as your STAX machine and Installer machine, then you will need to specify the port explicitly, e.g. mysystem.company.com@6500. Or, if your target machine is running multiple instances of STAF, then you will need to specify the port explicitly to be sure to communicate with the instance of STAF that you want to upgrade.	Yes	No	N/A
installerMachine	The endpoint for the machine where the STAF installer files reside	Yes	No	N/A
installerDirectory	The directory on the installerMachine where the STAF installer file(s) reside. The function will then automatically determine the STAF installer file to use to upgrade STAF. It does this by determining the os/architecture, etc. of the target machine and chooses a .bin/.exe file over a tar.gz file if both exist in the installer directory. Note that only the InstallAnywhere Bundled JVM installer files (e.g. STAFxxxx-setup-linux.bin, STAFxxxx-setup-win32.exe) and GNU zipped tar installer files (e.g. STAFxxxx-linux.tar.gz) are supported by this function. The InstallAnywhere NoJVM installer files (e.g. STAFxxxx-setup-linux-NoJVM.bin) are not supported by this function. You must specify the installerDirectory argument OR the installerFile argument, but not both.	No	No	None
installerFile	The fully-qualified name of the STAF installer file that resides on the installerMachine. This file will be used to upgrade STAF on the target machine. Note that you should specify either the name of an InstallAnywhere Bundled JVM installer file or the name of a GNU zipped tar installer file. You must specify the installerDirectory argument OR the installerFile argument, but not both.	No	No	None
preferredProcessorType	Indicates whether you would prefer to use a 64-bit over a 32-bit STAF installer file if one is available for the target machine's operating system, or vice versa. This argument is only used if you specified the installer directory so that the function automatically determines the STAF installer file to use to upgrade STAF. Valid values are '32-bit' or '64-bit'.	No	No	'64-bit'
preferredFileType	Indicates the type of installer file you would prefer to use to install STAF if it is available for the target machine's operating system: 1=InstallAnywhere .bin or .exe file, 2=tar.gz or tar.Z file (STAFInst). This argument is only used if you specified the installer directory so that the function automatically determines the STAF installer file to use to upgrade STAF.	No	No	1
installShieldTempDir	The directory on the target machine to use for storing temporary files created by InstallAnywhere. This argument is only used if an InstallAnywhere file (e.g. .bin or .exe) is used to upgrade STAF. If the install fails because InstallAnywhere does not have enough space to extract temporary files, you will either need to make free up space in the default temporary directory for InstallAnywhere or use this argument to specify a different temporary directory.	No	No	None
port	A port number to be used to communicate to a temporary STAFProc instance that will be started during the STAF upgrade process. This port must not currently be used by any instance of STAF running on the target machine.	No	No	6599
installType	Indicates whether to a 'Full' or 'Minimal' install. Note that a 'Full' install type installs all STAF files including all supported codepages.	No	No	'Full'
updateEnvVars	Indicates the type of environment variables to update. This argument is only used if an InstallAnywhere file (e.g. .bin or .exe) is used to upgrade STAF. The valid values are "System", "User", and "None". "System" specifies to update the system environment variables and the start menu (if on Windows). "User" specifies to update the user's environment variables. "None" specifies to not update the environment.	No	No	'System'
tcpipVersion	Indicates whether to install support for IPv4 only or for IPv4 and IPv6. The valid values are "IPv4 only" and "IPv4 and IPv6". Note that the target machine must support IPv6 in order to install support for IPv4 and IPv6.	No	No	'IPv4 only'
importMachine	The endpoint for the machine where the STAXUtil.xml file resides. This function imports and uses functions in the STAXUtil.xml file provided with STAX.	No	No	'local'
importDirectory	The directory where the STAXUtil.xml file resides on the importMachine.	No	No	'{STAF/Config/STAFRoot}' + '/services/stax/libraries'
verifyOnly	A flag that indicates whether you just want to verify if the target machine meets the pre-requisites checks to be able to have STAF upgraded (but not actually perform the STAF upgrade). A value that evaluates via Python to true (e.g. 1) indicates to only perform a pre-req check and not to perform the upgrade. A value that evaluates via Python to false (e.g. 0) indicates to perform the STAF upgrade (assuming it passes pre-req checking).	No	No	0

Returns:

A list containing the return code and result from upgrading STAF on the target machine.

If it was successful, the return is 0 and the result contains a message with the location where STAF was upgraded on the target machine, the STAF installer file used, and the new STAF version. If it failed, a non-zero return code and an error message will be returned.

Examples:

1. Here's an example that requests to upgrade STAF on target machine 'client1.company.com' using machine 'server1.company.com' as the machine where the STAF installer files reside in directory '/STAFInstallFiles/330':

     <call function="'STAFUpgrade'">
       {
         'machine': 'client1.company.com',
         'installerMachine': 'server1.company.com',
         'installerDirectory': '/STAFInstallFiles/330
       }
     </call>
   
     <script>[rc, result] = STAXResult</script>

2. Here's an example that requests to upgrade STAF on target machine 'client1' and specifies to use STAF installer file '/STAFInstallFiles/330/STAF330-linux.tar.gz' on machine 'server1':

     <script>
       installerMachine = 'server1.company.com'
       linuxInstallFile = '/STAFInstallFiles/330/STAF330-linux.tar.gz'
     </script>
             
     <call function="'STAFUpgrade'">
       { 'machine': 'client1', 'installerMachine': installerMachine,
         'installerFile': linuxInstallFile }
     </call>
   
     <script>[rc, result] = STAXResult</script>

STAFUpgrade_Step1

Performs Step 1 in the STAF Upgrade process where it installs a temporary version of STAF. It does this as follows:

1. Copy installFile to target machine
2. If target machine is Unix, give execution permissions to the installFile
3. Delete the install directory on the target machine if it exists and delete the install log file on the target machine if it exists
4. Start a process to execute the installFile

This function takes a list of arguments
Name	Description	Required	Private	Default	Properties
targetMachine	The target machine where STAF is to be upgraded	Yes	No	N/A

Returns:

A return code. If this step is successful, the return code is 0. If the step failed, the return code is non-zero.

STAFUpgrade_Step2

Performs Step 2 in the STAF Upgrade process where it starts the temporary instance of STAF that it just installed. It does this as follows::

1. Create a STAF config file to use when starting the temporary instance of STAF that uses a TCP interface with the specified port and gives the STAX machine trust level 5.
2. Start STAFProc for the temporary STAF instance.

This function takes a list of arguments
Name	Description	Required	Private	Default	Properties
targetMachine	The target machine where STAF is to be upgraded	Yes	No	N/A

Returns:

A return code. If this step is successful, the return code is 0. If the step failed, the return code is non-zero.

STAFUpgrade_Step3

Performs Step 3 in the STAF Upgrade process where it shuts down the instance of STAF to be upgraded.

This function takes a list of arguments
Name	Description	Required	Private	Default	Properties
targetMachine		Yes	No	N/A

Returns:

A return code. If this step is successful, the return code is 0. If the step failed, the return code is non-zero.

STAFUpgrade_Step4

Performs Step 4 in the STAF Upgrade process where it upgrades STAF (communicating to the target machine using the temporary instance of STAF).

This function takes a list of arguments
Name	Description	Required	Private	Default	Properties
targetMachine		Yes	No	N/A

Returns:

A return code. If this step is successful, the return code is 0. If the step failed, the return code is non-zero.

STAFUpgrade_Step5

Performs Step 5 in the STAF Upgrade process where it starts the instance of STAF that it just upgraded.

This function takes a list of arguments
Name	Description	Required	Private	Default	Properties
targetMachine	The target machine where STAF is to be upgraded	Yes	No	N/A

Returns:

A return code. If this step is successful, the return code is 0. If the step failed, the return code is non-zero.

STAFUpgrade_Step6

Performs Step 6 in the STAF Upgrade process where it shuts down the temporary instance of STAF.

This function takes a list of arguments
Name	Description	Required	Private	Default	Properties
targetMachine	The target machine where STAF is to be upgraded	Yes	No	N/A

Returns:

A return code. If this step is successful, the return code is 0. If the step failed, the return code is non-zero.

STAFUpgrade_InstallSTAF

Installs STAF on the target machine.

This function takes an argument map
Name	Description	Required	Private	Default	Properties
targetMachine	The endpoint for the target machine where STAF is to be installed	Yes	No	N/A
osName	The operating system of the target machine	Yes	No	N/A
installLocation	The target directory to install STAF	Yes	No	N/A
installCommand	The command to install STAF	Yes	No	N/A
installLogFile	The fully-qualified name of the log file to use when installing STAF	Yes	No	N/A
deleteInstallLocation	A flag indicating whether to delete the target directory to install STAF	No	No	1

Returns:

A return code. If the install is successful, the return code is 0. If the install failed, the return code is non-zero.

STAFUpgrade_GetInstallMethod

Determines if STAF was installed on the target machine in the installLocation using InstallAnywhere, InstallShield or STAFInst.

This function takes an argument map
Name	Description	Required	Private	Default	Properties
targetMachine	The endpoint for the target machine	Yes	No	N/A
installLocation	The directory on the target machine where STAF is to be upgraded	Yes	No	N/A

Returns:

A a list containing a return code and a result. If no errors occurred, the return code will be 0 and the result will contain the install method which will be one of the following:

• 'IA' if InstallAnywhere was used to install STAF
• 'STAFInst' if STAFInst was used to install STAF
• 'ISMP' if InstallShield MultiPlatform was used to install STAF

If an error occurred, the return code will be non-zero and the result will contain an error message.

STAFUpgrade_UpgradeSTAF

Upgrades STAF on the target machine.

This function takes an argument map
Name	Description	Required	Private	Default	Properties
targetMachine	The endpoint for the target machine	Yes	No	N/A
installLocation	The directory on the target machine where STAF is to be upgraded	Yes	No	N/A
installCommand	The command to use to install STAF	Yes	No	N/A
installLogFile	The log file name to use when installing STAF	Yes	No	N/A

Returns:

A return code. If the upgrade is successful, the return code is 0. If the upgrade failed, the return code is non-zero.

STAFUpgrade_StartSTAF

Starts STAF via a PROCESS START request with no WAIT option specified, redirecting stdout/stderr to a file.

This function takes an argument map
Name	Description	Required	Private	Default	Properties
testMach	The endpoint for the STAFProc instance that already is running on the target machine	Yes	No	N/A
newTestMach	The endpoint for the STAFProc instance to be started on the target machine	Yes	No	N/A
osName	The operating system type for the target machine	Yes	No	N/A
installLocation	The location where STAF is installed for the STAFProc instance to be started	Yes	No	N/A
configFile	The STAF configuration file name to use when starting STAF	Yes	No	N/A
stafprocOutFile	The name of the file to redirect stdout/stderr for starting STAFProc	Yes	No	N/A
instanceName	The STAF instance name to use when starting STAF	Yes	No	N/A
waitTime	The number of seconds to wait for STAFPro to be started	No	No	120

Returns:

A return code. If STAF starts successfully, the return code is 0. If fails to start STAF, the return code is non-zero.

STAFUpgrade_ImportSTAXUtil

Imports the STAFUtil.xml file.

This function takes an argument map
Name	Description	Required	Private	Default	Properties
importMachine	The endpoint for the machine where the STAXUtil.xml file resides.	Yes	No	N/A
importDirectory	The directory where the STAXUtil.xml file resides on the import machine.	Yes	No	N/A

Returns:

A return code. If the import is successful, the return code is 0. If the import failed, the return code is non-zero.

STAFUpgrade_GetSTAXMachineInfo

Gathers information about the STAX machine.

This function takes an argument map
Name	Description	Required	Private	Default	Properties
installerMachine	The endpoint for the installer machine (the machine where the STAF installer files reside)	Yes	No	N/A

Returns:

A list containing a return code and result.

If successful, the return code will be 0 and the result will contain a map with the following keys: 'version', 'STAFDataDir', 'osType, 'machine' For example:

  [0, {'version': '3.1.1', 'STAFDataDir': 'C:\STAF',
           'osType': 'Win2003', 'machine': 'server1.company.com'}]

If an error occurred, the return code with be non-zero and the result will contain an error message.

Examples:

  <call function="'STAFUpgrade_GetSTAXMachineInfo'">
    { 'installerMachine': 'server2.company.com' }
  </call>

  <script>[rc, result] = STAXResult</script>

STAFUpgrade_GetTargetMachineInfo

Gathers information about the target machine where STAF is to be upgraded.

This function takes an argument map
Name	Description	Required	Private	Default	Properties
targetMachine	The endpoint for the target machine	Yes	No	N/A
port	The port to use for the temporary STAFProc instance	Yes	No	N/A
STAXMachInfo	A map containing information about the STAX machine. The map has keys: 'version', 'STAFDataDir', 'osType', and 'machine'	Yes	No	N/A

Returns:

A list containing a return code and result.

If successful, the return code will be 0 and the result will contain a map with the following keys containing information about the target machine: 'dataDir', 'version', 'osName', 'osRevision', 'osMajorVersion', 'osMinorVersion', 'fileSep', 'stafRoot', 'configFile', 'intanceName', 'processorArchitecture', 'path', 'classpath', 'libPath', 'tmpDatDir', 'tmpMachine'

If an error occurred, the return code with be non-zero and the result will contain an error message.

Examples:

  <call function="'STAFUpgrade_GetTargetMachineInfo'">
    { 'machine': 'client1.company.com',
      'port': '6500',
      'STAXMachInfo': {'version': '3.1.1', 'STAFDataDir': 'C:\STAF',
                      'osType': 'Win2003', 'machine': 'server1.company.com'}
    }
  </call>

  <script>[rc, result] = STAXResult</script>

STAFUpgrade_GetInstallerFile

Determines the name of the installer file to use based on the operating system, type, architecture, etc. of the target machine to be upgraded.

This function takes an argument map
Name	Description	Required	Private	Default	Properties
machine	The endpoint for the target machine	Yes	No	N/A
installerMachine	The endpoint for the installer machine (where the STAF installer files reside)	Yes	No	N/A
installerDirectory	The directory on the installer machine where the STAF installer files reside	Yes	No	N/A
preferredProcessorType	The preferred processor type to use when choosing a STAF installer file	Yes	No	N/A
preferredFileType	The preferred type of STAF installer file (e.g. 1=InstallAnywgere file, 2=Tar file)	Yes	No	N/A
machineInfo	A map containing information about the target machine	Yes	No	N/A

Returns:

A list containing a return code and result.

If successful, the return code will be 0 and the result will contain a map with the following keys:

  installType       # 1=InstallAnywhere 2=STAFInst (tar.gz file)
  installerFile     # Fully-qualified installer file path and name
  installFileName   # Installer file name

  [0, {'installType': 1, 'installerFile': '/STAFBuilds/3.1.3',
           'installFileName': 'STAF313-setup-win32.exe'}]

If an error occurred, the return code with be non-zero and the result will contain an error message.

STAFUpgrade_CreateDirectoryIfDoesNotExist

Checks if the specified directory exists on the specified machine. If the directory doesn't exist, then it creates the directory on the specified machine.

This function takes an argument map
Name	Description	Required	Private	Default	Properties
directory	The name of a directory to create if it doesn't exist	Yes	No	N/A
machine	The machine where the directory should reside	Yes	No	N/A

Returns:

A list containing a return code and result.

If successful, the return code will be 0 and the result will be blank. For example:

  [0, '']

If an error occurred, the return code with be non-zero and the result will contain an error message.

STAFUpgrade_RunSTAFCmd

Logs a message about the STAF command being run, runs the specified STAF command (by submitting the specified request to the specified service on the specified machine). If the STAF command fails (e.g. it's return code is not in the list of valid return codes), records a fail testcase status and logs and sends a failure message to the STAX Monitor, and checks if the terminateJobFlag evaluates to true and, if so, terminates the job.

This function takes a list of arguments
Name	Description	Required	Private	Default	Properties
location	The machine to run the STAF command on	Yes	No	N/A
service	The service to submit the request to	Yes	No	N/A
request	The request to submit to the service	Yes	No	N/A
validRCList	A list of the valid return codes for this request	No	No	[ STAFRC.Ok ]
terminateJobFlag	A flag indicating whether to terminate the job if the STAF command's RC is not in the validRCList. The default is 0 which indicates not to terminate the job. Setting the flag to 1 indicates to terminate the job.	No	No	0
name	The name to use to identify the staf command in the STAX Monitor	No	No	'STAF %s %s %s' % (location, service, request)

Returns:

A list containing the return code and result from the STAF command.

If the STAF command was successful and the result buffer is '', returns:

  [0, None]

Examples:

1. Here's an example that submits a PING request to the PING service on the local machine and assigns the STAF command's RC and STAFResult to variables rc and result.

     <call function="'STAFUpgrade_RunSTAFCmd'">
       [ 'local', 'PING', 'PING' ]
     </call>
   
     <script>[rc, result] = STAXResult</script>

2. Here's an example that submits a DELETE ENTRY request to the FS service on machine client1.austin.ibm.com and assignes the STAF command's RC and STAFResult to variables rc and result:

     <script>
       location = 'client1.austin.ibm.com'
       service = 'FS'
       request = 'DELETE ENTRY %s CONFIRM' % (installLogFile)
     </script>
   
     <call function="'STAFUpgrade_RunSTAFCmd'">
       [ location, service, request, [ STAFRC.Ok, STAFRC.DoesNotExist ] ]
     </call>
   
     <script>[rc, result] = STAXResult</script>

STAFUpgrade_WaitForSTAFShutdown

Waits for STAF to become unavailable (that is, for the STAFProc daemon to be shutdown) on one or more machines. A maximum wait time can be specified, overriding the default maximum wait time of 5 minutes. If one or more machines are available, and the maximum wait time has not been exceeded, delays 5 seconds and then retries. This function can be useful after shutting down STAF one or more systems to verify that shutdown is complete.

This function takes a list of arguments
Name	Description	Required	Private	Default	Properties
machineList	A single machine or a list of machines for which you want to wait for STAF to become unavailable	Yes	No	N/A
maxWaitTime	The maximum length of time in seconds you want to wait for STAF to become unavailable on the specified machine(s). The default is 5 minutes (300 seconds).	No	No	300

Returns:

A list containing a return code and result.

If the machine(s) all have STAF unavailable within the maximum wait time, returns a return code of 0 and None for the result. That is, STAXResult would be:

  [0, None]

If the maximum wait time is exceeded, returns a return code of 1 and a list of machines that are available. For example, if machines 'machA' and 'machB' are still running STAF, STAXResult would be:

  [1, ['machA', 'machB']]

If an invalid (non-integer) maxWaitTime value is specified, returns a return code of -1 and None for the result. That is, STAXResult would be:

  [-1, None]

Examples:

1. Here's an example that waits for STAF to become unavailable on machA for the default time of 5 minutes:

     <call function="'STAFUpgrade_WaitForSTAFShutdown'">'machA'</call>

2. Here's an example that waits for STAF to become unavailable on three systems for a maximum of 60 seconds. If STAF is not unavailable on all three systems within 60 seconds, a failure message is logged and sent to the STAX Monitor.

     <script>machList = [ 'machA', 'machB', 'machC' ]</script>
   
     <call function="'STAFUpgrade_WaitForSTAFShutdown'">[ machList, 60 ]</call>
   
     <script>[rc, result] = STAXResult</script>
   
     <if expr="rc != 0">
       <call function="'STAXUtilLogAndMsg'">
         'STAXUtilWaitForSTAF failed. RC=%s Result=%s' % (rc, result)
       </call>
     </if>