Running Control-D/WebAccess Shell Transformations

Control-D/WebAccess Server Desktop enables you to use third-party external transformation components. It uses the bmc-ctd-si-shell-transformer.dll Application Extension to trigger transformations from the third-party application. This extension invokes an external program when you trigger a transformation, which transforms reports within the Control-D/WebAccess Server Web Application.

Begin

1. From the Root directory, navigate to the following location:

   Configurations > WebAccess Server> WebAccess > WebAccess > Transformers

2. From the Transformers folder, select an item, right-click, and then click Add.

   The New Item window appears.

3. In the Basic tab, define the following fields:

   1. In the Display Name field, define the new transformer name.

   2. In the From Extension field, determine the input file type.

   3. In the To Extension field, determine the output file type.

   4. In the Program field, type the following:

      bmc-ctd-si-shell-transformer.dll

4. In the Advanced tab, in the Param field, type the following command, as described in Syntax:

   Command "%%IN%%" ["%%OUT%%"] ["%%LV%%"] [{%%RA_ATTRIBUTE_NAME%%}] [{%%AD_PARAM%%}] [si_pagebreak=page_break_symbol] [si_dateformat=date_and_time_format] [si_timeout=number_of_seconds] {si_cleanup=yes|no}] [parameters required by external transformer executable]

   BMC recommends that you always enclose the %%IN%%, %%OUT%%, and %%LV%% macro variables with quotation marks.

5. Click Apply.

6. Click OK.

7. The configuration is complete.

Syntax

The following syntax structure defines an external transformer and its parameters in the Param field:

Command macros settings parameters

where

• Command: Defines the full path to the executable file of the external transformer, which you must define the first. The rest of the macros, settings, and parameters appear in the order needed for passing the data to the external transformer, as discussed in Command.

• Macros: Defines the shell transformer macro variables. You must replace the macro variables with actual values, which passes to an external transformer as its command line parameters, as discussed in Macros.

• Settings: Determines whether to use the shell transformer settings and delete them from command line, as discussed in Settings.

• Parameters: Defines other parameters required by the external transformer.

Command

In the Command section the full path to the executable file of the external transformer appears. You must first type the file path name in the Param field.

Type one of the following commands when you use a batch file to transform reports:

• cmd /c call batch_file_full_path parameters

  cmd /c call "d:\Program Files\BMC\test.bat" "%%IN%%" "%%OUT%%"

• cmd /c " batch_file_full_path parameters "

  cmd /c " "d:\Program Files\BMC\test.bat" "%%IN%%" "%%OUT%%" "

Macros

The macros section defines the shell transformer macro variables in paired %%, percent, symbols. Actual values replace the macro variables, which pass to an external transformer as its command line parameters.

Shell transformer macro variables include the following:

• %%IN%%: Full file path name to a temporary input file.

  ctd_installation_dir/transformer/input/file_gen2ext_{unique name}.original_ext

• (Optional) %%OUT%%: Full file path to the temporary output file.

  ctd_installation_dir/transformer/output/file_gen2ext_{unique name}.target_ext

• (Optional) %%LV%%: Full path to the temporary logical view text file.

  ctd_installation_dir/transformer/input/file_gen2ext_{unique name}_log_view

• (Optional) %%RA_ATTRIBUTE_NAME%%: Report attribute value macro.

  Select one the following RA_ATTRIBUTE_NAME macros:

  • RA_CATEGORY

  • RA_CHARS

  • RA_CLASS

  • RA_COPIES

  • RA_DECOLLATIONDATE

  • RA_DEST

  • RA_ENCODING

  • RA_FILEEXTENSION

  • RA_FORM

  • RA_FROMUSER

  • RA_JOBENDDATE

  • RA_JOBNAME

  • RA_JOBID

  • RA_JOBSTARTDATE

  • RA_LANGUAGE

  • RA_LINES

  • RA_LOCATION

  • RA_ORDERDATE

  • RA_ORIGINALENCODING

  • RA_PAGELISTMODE

  • RA_PAGES

  • RA_RECFM

  • RA_RECIPIENT

  • RA_REMARK

  • RA_REPORTNAME

  • RA_RESOURCESETID

  • RA_STATUS

  • RA_USERDEST

• (Optional)%%AD_PARAM%%: Report parameter.

  Select one of the following AD_PARAM macros:

  • AD_SESSIONID: Control-D/WebAccess session ID (unique value)

  • AD_USERNAME: Determines the username to log in to Control-D/WebAccess Server Desktop.

  • AD_HOSTNAME Determines where to connect the host.

  • AD_PAGESNUMBER: Determines the real number of the page in pages list.

  • AD_PARAM01: Defines an additional Control-D/WebAccess Server parameter.

  • AD_PARAM02: Defines an additional Control-D/WebAccess Server parameter.

  • AD_PARAM03: Defines an additional Control-D/WebAccess Server parameter.

  • AD_PARAM04: Defines an additional Control-D/WebAccess Server parameter.

  • AD_PARAM05: Defines an additional Control-D/WebAccess Server parameter.

  • AD_PARAM06: Defines an additional Control-D/WebAccess Server parameter.

Settings

The following table describes e shell transformer settings in the Settings area. Each setting begins with: si_.

Parameter	Description
si_dateformat=%d/%m/%Y %H:%M	Determines the date and time formats to replace all RA_…DATE macros. You can use the following common date separators: Slash / Dash – Space You must enclose the entire setting must in quotation marks; such as, "si_dateformat=%d/%m/%Y %H:%M" when the si_dateformat parameter contains a space. Default: Use %d/%m/%Y %H:%M when there is not a si_dateformat= setting appears.
si_pagebreak	Determines the symbol to place in the %%OUT%%, which shows a page break file for page break. You must use a hexadecimal format to determine the symbol. Default: 0x0c
si_timeout	Determines the number of seconds before the transformation process finishes. Default: 240 The following example lists sample outputs in different formats assuming a date of August 20, 2003, at 3:59:10 a.m. si_dateformat=%d,%m,%Y: 20,08,2003 si_dateformat=%d/%m/%Y %H:%M: 20/08/2003 03:59 si_dateformat=%m-%d-%y %H:%M:%S: 08-20-03 03:59:10 si_dateformat=%d/%m/%Y %k:%M: 20/08/2003 3:59
si_cleanup	Determines whether the transformer deletes the temporary input or output files. Default: Yes

The following table lists acceptable date and time format specifiers.

Format	Description
%d	Determines the number of digits to show a two-digit day of month. Valid values: 01−31
%H	Determines the number of digits to show a two-digit hour. Valid values: 00−23
%k	Determines the number of digits to show a two-digit hour. Valid values: 0−23 A blank space precedes single digits.
%m	Determines the number of digits to show a two-digit month. Valid values: 0−12
%M	Determines the number of digits to show a two-digit minute. Valid values: 0−59
%S	two-digit second Valid values: 00−59
%y	Determines the number of digits to show a two-digit year. Valid values: 00−99
%Y	Determines the number of digits to show a four-digit year.