How to use Macros in Installation Procedures within a CA Client Automation Software Delivery job.

Document ID : KB000026243
Last Modified Date : 14/02/2018
Show Technical Document Details

Introduction:

The use of macros allow added flexibility when configuring software delivery jobs across platforms. This document details how to use Macros in Installation Procedures within a CA Client Automation Software Delivery job.

 

Question:

What are some of the parameter macros supported by software delivery (they are expanded when the item procedure is activated).

 

Answer:

The parameter macros are divided into the following categories:

  • Job related macros
  • Target related macros
  • Software item related macros
  • Manager time related macros
  • Software location related macros
  • Reboot related Macros
  • InstallShield parameters
  • Redirection in Item Procedures

Job Related Macros
$rf
Creates a result file to view the output of a job.

  1. If the application has a parameter to write output to a file, for example /F (if the syntax for the command states /F:file), then /F:$rf can be used.

  2. If the application writes to stdout, you can redirect the output to the output file using >$rf. Refer to the "Redirection using the Item Procedure Parameters" section on this page.

To view the output of a job, select a Job Target in the right pane, by expanding a job in the Jobs list. Right-click and select Properties... in the context menu. In the Job Target Properties dialog that appears, select the Job output tab. The result file will be displayed here.

$up
Selection of this macro enables setting User parameters in the Job Options tab.

$joid
Expands to the job object identifier (this can be useful when creating unique keys).

$#bg
Runs the job in the background.

$#ec:xx
Overrides the usual exit code interpretation (where exit code=0 means OK, otherwise error). You can change this by an explicit specification of the exit code interpretation. The specification can be done/ concatenated in any of the following four ways:

  • $#ec:a-b
    where a denotes the start of the interval and b the stop.

  • $#ec:a-
    where a denotes the start of the interval (which is open upwards).

  • $#ec:-b
    where b denotes the stop of the interval (which is open downwards, that is, starting with 0).

  • $#ec:b
    where b denotes the specific exit code.

Example:
$#ec:3010 $#ec:0-100. Here exit code 3010 and all codes in the interval 0 to 100 are interpreted as OK.

Target Related Macros
$cn
Selects the computer name and LAN id of the PC, the Item Procedure is executed in.

Expanded value:
ComputerName ComputerLanId.

$hd
Supplies a string of fixed drive letters. Expanded value: CDE (string of drive letters).

$hd is not supported for UNIX item procedures.

$()
In this macro you can, within the brackets, refer to a parameter, which is stored in the Unicenter Software Delivery database on the Unicenter Software Delivery server, if the following actions have been taken:

  1. A parameter package has been created, using the Packager, and registered in the Library

  2. The parameter package has been installed on the Unicenter Software Delivery server, which is to evaluate the reference to the parameter.

The contents between the brackets has the structure X/Y/parameter, where X=the packaging computer where the parameter package was created and Y=the parameter package.

$() can also be used in queries and as user parameter when defining jobs.

Software Item Related Macros
$in
Expands to the item name.

$iv
Expands to the item version.

$ip
Expands to the item procedure source path (in the library). Useful when writing batch files, which refers to the root location of the source files.

This macro cannot be used from external procedures.

$pn
Expands to the procedure name.

$pf
Expands to the current procedure file (of the current MSI-package).

$ioid
Expands to the item object identifier. This can be useful when creating unique keys.

Manager Time Related Macros
$cl
Selects the date and time registered on the manager's clock when activation took place.

Expanded value: hour minutes seconds year month day.

$cl+nn
Selects the manager time and adds the specified number of minutes.

Expands the same as $cl.

$cl-nn
Selects the manager time and subtracts the specified number of minutes.

Expands the same as $cl.

Software Location related Macros
$msi
Expands to the path of the directory, where MSILIB resides; the path used for MSI administrative installations.

This macro only applies to MSI-packages.

The relevant item procedure now handles the expansion to the MSI subdirectory, into which an Administrative Installation of the current item once was made.

$cd()
Used for example to provide a path to a file on a specific CD.

Usage: $cd(OfficeSw)\Subdir\msispy.msi, where OfficeSw is the CD label and Subdir is the directory on the CD, in which the msi-file msispy.msi is located.

Reboot Related Macros
The following macros can be added to the command line of the procedure or as user parameters for the job container, provided the command line of the procedure accepts user parameters, which is enabled by the $up macro. During job evaluation and build, the manager looks for these macros. If they are found they will be removed from the command line and transformed into job definition properties, which are sent to the agents.

$rto:value
Defines the timeout in seconds for the shutdown dialog, where value is a numeric value greater than 0. If not set, the value is defined by configuration policy. If set, both initial timeout and every consecutive postpone use the value.

This macro is used by logoff and reboot routines.

Overrides policy: ITRM/USD/Agent/RebootPromptTO.

$rrt:value
Defines the number of allowed postpones, where value is a numeric value equal to or greater than 0. If not set, the value is defined by configuration policy.

This macro is used by logoff and reboot routines.

Overrides policy: ITRM/USD/Agent/RebootPromptRT.

$rbp:value
Specifies if a message should be displayed to the user before reboot or logoff is initiated. The value is 0 or 1. If not set, the value is defined by configuration policy. If set to 1, a requested reboot or logoff will not be initiated automatically. Instead a message is displayed prompting the user to save all work. The message does not have a timer and can only be closed by the user. By closing the message the shutdown is initiated.

This macro is used by logoff and reboot routines.

Overrides policy: ITRM/USD/Agent/PoliteReboot.

$rbf:value
Specifies if shutdown should be forced, where value is 0 or 1. If not set, the value is defined by configuration policy. If set to 1, the shutdown routine will force programs to shutdown.

This macro is used by logoff and reboot routines.

Overrides policy: ITRM/USD/Agent/ForcedReboot.

Logoff/Reboot after last job behavior:
Due to the boot option "Logoff/Reboot after last job" it may happen that more than one job may want to influence the boot parameters being used by the job procedure. Another scenario where this approach is used is when the reboot parameters are specified for a job for which no Logoff or Reboot is requested. In this case the following rules apply:

$rto: If more than one job carries the parameter the most restrictive will be used. This means the lowest timeout will be used.
$rrt: If more than one job carries the parameter, the most restrictive will be used. This means the lowest count will be used.
$rbp: If more than one job carries the parameter, the most restrictive will be used. This means that $rbp:0 will override $rbp:1.
$rbf: If more than one job carries the parameter, the most restrictive will be used. This means that $rbf:1 will override $rbf:0.

Compatibility considerations:
The reboot override functionality requires DSM r11.2. If the manager is r11.2 but the scalability servers or the agents are pre-r11.2, the reboot override functionality does not work and the default configuration is used by the agent. If the manager is not r11.2, the macros will remain on the command line and eventually get passed as regular parameters to the installer which is launched by the agent.

InstallShield Parameters
/SMS
Makes InstallShield setup.exe automatically wait for the installation to finish before exiting.

/s
Runs InstallShield Silent to execute a silent setup. A response file is needed.

/f1"setup.iss"
Specifies an alternate location and name of the response file (.iss) file. A response file is created using the /r parameter.

/f2$rf
Specifies an alternate location and name of the log file that is created by InstallShield Silent

/verbose$rf
Provides more detailed information when a setup.exe error occurs.

/uninst
Runs setup.exe as an uninstallation without reading the script.

/m"filename.mif"
Causes setup to generate a Management Information Format (.mif) file automatically at the end of setup.

/m1[serial number]
Tells setup to place the indicated serial number in the .mif file that is generated by the /m switch.

/m2[locale string]
Specifies the language in which the setup runs. Here [language ID] is a numeric language ID of the form 0xnnnn or simply nnnn.

The $ sign should only be used in the parameter macros mentioned above. Other parameters should not contain $.

Environment Variables in Parameters
It is possible to specify environment variables of the target machine in the parameters by adding a '%' sign before and after the variable name.

Example: %SDROOT%\mydir\yourdir would expand to C:\Program Files\CA\SD\mydir\yourdir on the target machine.

Redirection in Item Procedures
An example, where redirection (>>) is used in the Item Procedure command file to get the computer name and LAN ID, as well as server's clock, written into the result file:

@echo Computer name: %3>>%1

@echo Computer alias: %2>>%1

@echo Time: %4-%5-%6 %7: %8: %9>>%1

The procedure parameters are $rf $cn $cl, where %1 is connected with $rf, %2 and %3 with $cn and %4 - %9 with $cl.

Redirection using the Item Procedure Parameters
Redirection of command output can also be done in the following way, >$rf, when targeting jobs for Windows NT/2000/XP, UNIX and OS/2 computers. This type of redirection is not supported for Windows 95.

On UNIX and Windows NT/2000/XP, ">$rf", >"$rf" and >$rf all work. On Windows CE, just use ">$rf".

When a DM script is used, and the interpreter is launched from the command line, you have to use an escape character ">" from the command line interpreter.