software tool house inc meta-update€¦ · this document is intended for remedy ars administrators...

Meta-Update

Release Notes

Software Tool House Inc

© 2019 Software Tool House

Release 5.85

Oct 08, 2019

Updated: 2011-May-31

Release 5.85

Meta-Update - 2 - Release Notes

Preface

Audience

This document is intended for Remedy ARS Administrators and developers who are familiar with both running and writing Meta-Update scripts.

This document describes the changes made in this release from the previous listed release.

Limitation of Liability

This program is provided "as-is". We are in no way liable for any losses arising from your use of this program, the sample scripts, or the documentation. It is your responsibility to evaluate this program. It is your responsibility to backup and protect your data. It is your responsibility to evaluate your use of this program for any particular purpose.

This manual does not represent a commitment to maintain any syntax or operation, nor is it warranted to be complete or accurate.

Copyrights

This program and this manual are copyrighted 1996-2019 by Software Tool House Inc.

Meta-Layer and Meta-Update are trademarks of Software Tool House Inc.

ARS, Remedy are registered trademarks of BMC Corporation. Solaris is a registered trademark of Oracle Inc. Windows is a registered trademark of Microsoft Corporation. PCRE (Perl Compatible Regular Expression) library is copyrighted © 1997-2019 by University of Cambridge and is distributed under the BSD license.

Updates

This program and this manual may change from time to time. The latest version is available at our web site: www.softwaretoolhouse.com.

Comments

Your comments are welcome! Please see: www.softwaretoolhouse.com/support and click Comments, or email us at [email protected]. We look forward to hearing from you!

http://www.softwaretoolhouse.com/

http://www.softwaretoolhouse.com/support

mailto:[email protected]


Table of Contents

Preface ................................................................................................................. 2 Audience ................................................................................................................................ 2 Limitation of Liability ............................................................................................................ 2 Copyrights ............................................................................................................................. 2 Updates .................................................................................................................................. 2 Comments ............................................................................................................................. 2

Table of Contents ................................................................................................ 3 Introduction ....................................................................................................... 10

Installation Notes .............................................................................................. 12 Backing Up Your Current Installation ................................................................................... 13 Expanding the Distribution .................................................................................................... 14 Complete Installation .............................................................................................................. 15

Current Release — 5.85 — 2019-Oct-08 ...................................................... 18 Overview .................................................................................................................................. 19 Release Date, Platforms, API Libraries ................................................................................. 20 API Library Upgraded ............................................................................................................. 21 Scripting Enhancements ........................................................................................................ 22 Bugs Fixed ............................................................................................................................... 23

Release — 5.80 — 2018-Feb-08 .................................................................... 24 Overview .................................................................................................................................. 25 Release Date, Platforms, API Libraries ................................................................................. 26 Scripting Enhancements ........................................................................................................ 27 New Command Line Switches ............................................................................................... 28 Documentation Enhancements ............................................................................................. 29

Release — 5.76 — 2018-Feb-08 .................................................................... 30 Overview .................................................................................................................................. 31 Release Date, Platforms, API Libraries ................................................................................. 32 Scripting Enhancements ........................................................................................................ 33 Documentation Enhancements ............................................................................................. 34

Release — 5.69 — 2017-Apr-14 .................................................................... 35 Overview .................................................................................................................................. 36 Release Date, Platforms, API Libraries ................................................................................. 37 Scripting Enhancements ........................................................................................................ 38 Other Enhancements .............................................................................................................. 39 Bugs fixed ................................................................................................................................ 40

Release 5.61 2016-Apr-15.............................................................................. 41 Overview .................................................................................................................................. 42 Release Date, Platforms, API Libraries ................................................................................. 43 Performance Enhancements .................................................................................................. 44 Scripting Enhancements ........................................................................................................ 45

Release 5.57 2015-Nov-24 ............................................................................. 46 Overview .................................................................................................................................. 47 Release Date, Platforms, API Libraries ................................................................................. 48


Bugs Fixed ............................................................................................................................... 49

Release 5.56 2015-Sep-30 ............................................................................ 50 Overview .................................................................................................................................. 51 Release Date, Platforms, API Libraries ................................................................................. 52 Scripting Enhancements ........................................................................................................ 53 Other Changes ......................................................................................................................... 54 Bugs Fixed ............................................................................................................................... 55 Documentation Changes ........................................................................................................ 56

Release 5.53 2014-08-15 ................................................................................ 57 Overview .................................................................................................................................. 58 Release Date, Platforms, API Libraries ................................................................................. 59 Performance Enhancements .................................................................................................. 60

Release 5.51 2014-06-15 ................................................................................ 61 Overview .................................................................................................................................. 62 Release Date, Platforms, API Libraries ................................................................................. 63 Script Enhancements .............................................................................................................. 64 Meta-Update Run Enhancements .......................................................................................... 65

API Retry Environment Variable ....................................................................................... 65 The Command Line ................................................................................................................. 66

Usage and Switches ........................................................................................................... 67 Usage Help Text .................................................................................................................. 69 Using Positional Arguments (Deprecated) ...................................................................... 70 Specifying Arguments in the script’s Main section ........................................................ 71

Bugs Fixed ............................................................................................................................... 72 Documentation Changes ........................................................................................................ 73 Documentation Changes ........................................................................................................ 74

Release 5.46 2014-01-10 ................................................................................ 76 Overview .................................................................................................................................. 77 Release Date, Platforms, API Libraries ................................................................................. 78 Bugs Fixed ............................................................................................................................... 79 Scripting Enhancements ........................................................................................................ 81

API Retry Environment Variable ....................................................................................... 81 Documentation Changes ........................................................................................................ 82

Release 5.45 2014-01-10 ............................................................................... 83 Overview .................................................................................................................................. 84 Release Date, Platforms, API Libraries ................................................................................. 85 Scripting Enhancements ........................................................................................................ 86

Script Path Environment Variable ..................................................................................... 86 Script File: Including Other Files ...................................................................................... 87 QueryStart= and QueryMax= ............................................................................................. 87 Copy Assignment Command Enhancements .................................................................. 88 Debugging ........................................................................................................................... 89 Debugging: List Files command ...................................................................................... 90

Other Changes ......................................................................................................................... 91 Scripting Depreciations and Changes .................................................................................. 92 Documentation Changes ........................................................................................................ 93 Operational Enhancements .................................................................................................... 94 Bugs Fixed ............................................................................................................................... 95


Release 5.37 2013-03-18 ............................................................................... 96 Overview .................................................................................................................................. 97 Release Date, Platforms, API Libraries ................................................................................. 98 Scripting Enhancements ........................................................................................................ 99 Additional automatic CTL-schema fields ............................................................................ 100

CTL – Schema Tag ............................................................................................................ 100 Until= Statement in Control Sections .................................................................................. 101 Trace Assignment Command .............................................................................................. 103 Other Changes ....................................................................................................................... 104 Scripting Depreciations and Changes ................................................................................ 105 Documentation Changes ...................................................................................................... 106 Bugs Fixed ............................................................................................................................. 107

Release 5.22 2013-01-10 ............................................................................. 110 Overview ................................................................................................................................ 111 Release Date, Platforms, API Libraries ............................................................................... 112 Scripting Enhancements ...................................................................................................... 113 Date Information Assignment Reference ............................................................................ 114 Format Value Assignments .................................................................................................. 116 Other Changes ....................................................................................................................... 117 Scripting Depreciations and Changes ................................................................................ 118 Documentation Changes ...................................................................................................... 119 Bugs Fixed ............................................................................................................................. 120

Release 5.20 2012-11-25 ............................................................................. 121 Overview ................................................................................................................................ 122 Release Date, Platforms, API Libraries ............................................................................... 123 Scripting Enhancements ...................................................................................................... 124 Other Changes ....................................................................................................................... 125

IdLog Facility ..................................................................................................................... 125 Scripting Depreciations and Changes ................................................................................ 128 Documentation Changes ...................................................................................................... 129 ARS Authentication Password Encryption ......................................................................... 130 SthLicUpd Maintenance Utility ............................................................................................ 131 Usage ...................................................................................................................................... 132

Sample Prompt Session: ................................................................................................. 133 Sample Password Session: ............................................................................................. 133 Using the generated SthLic.cmd or SthLic.sh files ................................................. 133

Bugs Fixed ............................................................................................................................. 135

Release 5.15 2011-12-10 ............................................................................. 137 Overview ................................................................................................................................ 138 Release Date, Platforms, API Libraries ............................................................................... 139 Scripting Enhancements ...................................................................................................... 140

@info Reference Assignment Command ....................................................................... 140 New Loop=Fields Iteration ............................................................................................... 141 New $redir$ keyword for @spawn .................................................................................. 142

Scripting Depreciations and Changes ................................................................................ 143 Documentation Changes ...................................................................................................... 144 Other Changes ....................................................................................................................... 145 Bugs Fixed ............................................................................................................................. 146

Release 5.13 2011-10-10 .............................................................................. 147 Overview ................................................................................................................................ 148 Release Date, Platforms, API Libraries ............................................................................... 149


Scripting Enhancements ...................................................................................................... 150 Assigning many fields and values to a single Tag ....................................................... 150

Scripting Depreciations and Changes ................................................................................ 151 Other Changes ....................................................................................................................... 152 Bugs Fixed ............................................................................................................................. 153


Sql= keyword added to field declarations ...................................................................... 158 New Predefined CTL Tag ................................................................................................. 158 Loop = String enhancements .......................................................................................... 159



Variable Target Fields assignments ............................................................................... 168 New reference command evaluating references for the Tag and Field ...................... 168 Update = Tag enhancements. .......................................................................................... 168 File Delimiters may be references .................................................................................. 169 Loop = String enhancements .......................................................................................... 169


Release 5.00 2011-06-11 ............................................................................. 173 Overview ................................................................................................................................ 174 Release Date, Platforms, API Libraries ............................................................................... 175 Scripting Enhancements ...................................................................................................... 176 Scripting Depreciations and Changes ................................................................................ 177 Other Changes ....................................................................................................................... 178 Bugs Fixed ............................................................................................................................. 179


Introduction


Introduction

This document identifies the changes made in this release over the previous listed release.

This document is cumulative. That is as each release becomes available, a new section is added describing the changes made from the previous release.

The document is organised into four sections:

1 Installation Notes

This section augments the Installation section of the Meta-Update User’s Guide and describes the procedure used to upgrade a current Meta-Update installation.

2 Current Release

This section identifies the current release and gives the following information on this release.

1 Overview This is a description of the major enhancements in the release.

2 Release Date, Platforms, and API Libraries.

Lists the date the release was made publicly available through the Software Tool House Support Web and the BMC Remedy API libraries and OS platforms supported.

3 Scripting Changes These are changes that this release brings to Meta-Update scripts. Additional scripting keywords, changes, and deprecated scripting constructs are listed. Deprecated keywords are sometimes carried over from the previous release for clarity. Any planned depreciations are also listed.

4 Changed files Lists the files that were changed in the distribution package.

5 Change Details Full details of all changed areas of Meta-Update.

6 Bug Fixes Summarises the tickets that were fixed in this Meta-Update release.


Installation Notes


Backing Up Your Current Installation

It is highly recommended that your current version of Meta-Update be backed up.

This is a very simple operation and guarantees that scripts you are currently running can be run without changes

Meta-Update installation consists of simply expanding the distribution zip or gzip file. As such, a backup is simply a copy of the current expanded file set.

On Windows, you could use Windows Explorer or the Command Prompt:

xcopy “C:\Program Files\SoftwareToolHouse\” “E:\bkp\C\Program

Files\SoftwareToolHouse\” /s

Similarly, on UNIX, you could use the cp command.

cp -r /apps/STH/* /bkp/apps/STH

To restore the previous version, simple copy the files in reverse.


Expanding the Distribution

Meta-Update Releases are complete distributions including all required binaries, sample scripts, and documentation.

A Meta-Update release is distributed as a single zip or g-zip file. The file may be expanded in your applications area. For example,

On Windows, you could unzip the distribution in:

“C:\Program Files\SoftwareToolHouse\”

Similarly, on UNIX, you will gunzip the file as you wish and then untar the resultant tar ball.

mkdir /apps/STH

chdir /apps/STH

gunzip SthMupd-5.45.tar.gz

tar -xvf SthMupd-5.45.tar


Complete Installation

There is no formal installation for Meta-Update. Meta-Update is meant to be run from a command line or shell or fired by ARS workflow, or other automated processes.

By expanding the distribution file, you have completed the installation of Meta-Update.


Current Release

5.85


Current Release — 5.85 — 2019-Oct-08


Overview

The current release - 5.85 includes: an upgrade to the Remedy 9.1.05 API libraries, performance enhancements, .new CTL-Section and CTL automatic fields and tags, bug fixes.

As of the 5.80 release, Meta-Update can open sessions to both BMC Remedy and ServiceNow servers.

Scripts can be used against either type of server or reading from one server and writing to another.

New scripting elements have been added to handle ServiceNow specific features. Some scripting elements cannot be used against ServiceNow servers.

The Meta-Update User’s Guide has been updated and there are some server specific scripting elements.

With the release only 64 bit binaries are made available.

Numerous performance improvements have been made.

Many new Samples added to the User Guide and the delivery. The User Guide has detailed explanations as together with running the sample in the Meta-Update debugger, are an invaluable guide to use as you progress from beginner through advanced, configurable scripts.

.


Release Date, Platforms, API Libraries

Release Number 5.86 Release Date 2019-Oct-08 Platforms Windows x64, Linux LX64 ARS API Libraries 9.1.5

Software Tool House recommends running Meta-Update compiled against the latest ARS API library no matter the ARS release of your server.

The downloadable distribution is built against the highest or second highest release of the BMC Remedy API.

As of 5.76, all Meta-Update binaries are compiled for 64-bit machines. There is no bin64 directory and the bin directory contains only 64-bit binaries.


API Library Upgraded

Area Description

All Binaries The Remedy API has been upgraded to BMC Remedy 9.1.05 or 1805 release.

This should make no difference to Meta-Update operation.

Meta-Update can connect with many different versioned Remedy and ServiceNow servers in a single script.


Scripting Enhancements

Area Description

Automatic Tag CTL

The CTL automatic tag no longer has the field Schema and

gains a field, Section.

CTL is used to define script level information.

$CTL, Section$ is the currently running section name.

Automatic Tag CTL-Section

Each executing section has a new tag generated using CTL, a minus, and the section name as the tag.

If a section launches another section, both the current launched section and the previous launching section’s CTL-Section tags are available.

Fields include Ix, the iteration index, Max, the maximum

number of iterations, Schema , an Update= schema.

Once a launched section completes, and processing returns to the launching section for its next iteration, the launched section’s tag is no longer defined. An error will result if referenced.

$CTL, Section$ is the currently running section name.


Bugs Fixed

Area Description

Attachment fields

Release 5.80 which added ServiceNow server types and special ServiceNow only attachment functionality, caused Remedy attachment functionality to cease working when copying attachments using references.

Increase in Section depth for Output=

An arbitrary limit of the Launch depth with sections that have an Output= to the same file and tag was reached in a script to report on SRD,

This has been increased from 10 to 100 and Meta-Update will not process that section if this limit is exceeded.


Release — 5.80 — 2018-Feb-08


Overview

The current release - 5.80 includes: performance enhancements, .a new feature to specify how Remedy Attachments retrieved through a Get filter are to be handled, and a new switch for ServiceNow instances to cause an instance behaviour to return no records on invalid queries.

As of this release Meta-Update can open sessions to both BMC Remedy and ServiceNow servers.







.



Release Number 5.80 Release Date 2018-Oct-19 Platforms Windows x64, Linux LX64 ARS API Libraries 9.1.2



As of 5.76, all Meta-Update binaries are compiled for 64-bit machines. There is no bin64 directory and the bin directory contains 64-bit binaries.



Area Description

@info A new variable is introduced: AttachGetFilter. It is set true with an Attachment field that would normally be NULL in the Database and is retrieved through the use of a Get filter.

Copy command Skip

options Two new Skip options are introduced to the Copy assignment command.

SkipAttach will skip all attachment fields of a record.

SkipAttachGF will skip attachment fields whose values

were derived from a Get Fields filter.


New Command Line Switches

Area Description -snQryChk

quit | set | ignore

Any query is dangerous to run against a ServiceNow instance that will return all records when an invalid query is performed through the REST api.

This switch controls how Meta-Update handles such a ServiceNow instance.

The default is quit.

set will cause the sys_properties record called

glide.invalid_query.returns_no_rows to true.


Documentation Enhancements

Area Description

Samples Additional Samples have been added to the documentation. These are described and fully annotated.

They can be used to learn Meta-Update scripting by reading and single stepping through the script with the debugger.

ServiceNow ServiceNow and Remedy only features and differences are tagged with icons throughout the documentation.

A new section is added highlighting the differences in Meta-Update scripting for ServiceNow and for Remedy.

Copy Assignment

Command

The new SkipAttach and SkipAttachGF are documented.

@info Assignment

Command

The new AttachGetFilter variable is documented.


Release — 5.76 — 2018-Feb-08


Overview

The current release - 5.76 incorporates release 5.75 on 2018-Jan-10, which was a significant enhancement to Meta-Update. 5.76 incorporates feedback from the 5.75 beta programme. 5.76 has no separate Release notes.

As of this release Meta-Update can open sessions to both BMC Remedy and ServiceNow servers.







.



Release Number 5.76 5.75 Release Date 2018-Feb-08 2018-Jan-10 Platforms Windows x64, Linux LX64 ARS API Libraries 9.1.2



As of 5.76, all Meta-Update binaries are compiled for 64-bit machines. There is no bin64 directory and the bin directory contains 64-bit binaries.



Area Description

@Cmd =

AttachLoad

An AttachLoad command is used to add an attachment to a

ServiceNow record. That attachment can come from the file system or from a Remedy attachment field..


Documentation Enhancements

Area Description

Samples Additional Samples have been added to the documentation. These are described and fully annotated.

They can be used to learn Meta-Update scripting by reading and single stepping through the script with the debugger.

ServiceNow ServiceNow and Remedy only features and differences are tagged with icons throughout the documentation.

A new section is added highlighting the differences in Meta-Update scripting for ServiceNow and for Remedy.

AttachLoad The new AttachLoad assignment command is documented.


Release — 5.69 — 2017-Apr-14


Overview

The 5.69 release accumulates a few fixes over several interim releases. It also includes enhancements and fixes to Meta-Schema. The 9.1.02 API is now in use in all Meta-Update binaries.

A Meta-Update script enhancement in File sections allows empty records to be processed. The default is to skip empty file rows.

An issue was discovered running Meta-Archive BMC Remedy ITSM 9.1 writing audit forms Meta-Archive when used against two servers.

The 5.63 limited release of Meta-Update fixes two infrequent issues:

A Date format of dd/Mm/yyyy would sometimes yield incorrect results when encountering a date like “31/3/2016”. Similarly, a format of d/M/yy would cause errors with dates like “31/02/2016”. Both formats are now equivalent

On Windows a larger stack is set. On Meta-Archive for HTML any field being accumulated in configured tables would cause a Meta-Update abort if its value was larger that approximately 1 Mb. This is now increased to 32Mb.

Note that in Linux a processes stack is set by a system command and is not part of the binary. On our system, the default is 10Mb.

5.56 is a significant maintenance release which offers 64 bit binaries, an updated PCRE component, and an upgrade to the 8.1.02 release of the BMC Remedy API, scripting enhancements.

It is recommended that the release notes for 5.56 be reviewed.

All platform distributions include both 32 bit and 64 bit distributions.



Release Number 5.69 Release Date 2017-Apr-14 Platforms Windows (i32, x64), Linux (LX32, LX64) ARS API Libraries 9.1.2 Included Releses 5.68 2017-Jan-05





Area Description

FieldsRequired = This keyword is used in a File section. It is a list of fields that will cause the record to be marked as an error.

In addition to “All” this keyword has been enhanced to

allow “None”, and the default, “One”. That default, “One”,

indicates that an empty record is to be skipped.

The value “None” indicates that am empty record is to be processed normally. All fields will have the NULL value.

Merge = Additional keywords “Replace” , “Error” and “NewId”

have been added when using the Merge= statement for the

Remedy Merge API.

When Merge = Yes is specified, the assigned fields

overwrite the same set of fields in a record if the field ‘1’ – or ‘Request ID’ is given and the record already exists. Any fields not being assigned would retain their original values if the record exists and be NULL if it didn’t exist.

When Merge = Replace is specified and a Request ID is

assigned and that record already exists, it will be deleted first and the set of fields will populate a new record. Any fields not assigned will have the NULL value.

When Merge = NewId is specified and a Request ID is

assigned and that record already exists, the Request ID value will be ignored and a new Request ID record will be created.

This is BMC Remedy behaviour. Meta-Update does not do the delete.

When Merge = Error is specified and a Request ID is

assigned and that record already exists, Remedy will generate an error.

Note that Merge can be used to create records by not

assigning the Request ID or assigning a Request ID

not in use. When creating records, the option Replace is

effectively the same as Yes. In Remedy 9.1 for some

“associated forms” such as Audit Logs and Archive forms, the option Replace is a requirement even when creating

records.

The Merge = options may be specified as a reference,

allowing dynamic selection of Merge options. Merge = $Cfg, MergeOpt$


Other Enhancements

Area Description

Meta-Schema Schema lists now include Audit information and index information

Menus definitions are, and menu results are not retrieved when schema list files are created.

Field files now include the table type indication so filters can be made conveniently.


Bugs fixed

Area Description

-d On some scripts using the Trace Push and Pop script statements (Meta-Archive), the Poped trace setting was incorrect.

Arg= Using argument names starting with “d” was problematic.

Meta-Update Stack increase

On Windows x64 binaries the stack is increased to accommodate very large Meta-Update values. It is now 1Gb

Note that Linux values are set by the system administrator and not in the binaries.


Release 5.61 2016-Apr-15


Overview

The 5.61 release of Meta-Update includes performance improvements in many areas of scripting, supports the BMC Remedy release 9 API, and introduces errors when an undefined tag or field is used in a reference.






Release Number 5.61 Release Date 2016-Apr-15 Platforms Windows (i32, x64), Linux (LX32, LX64) ARS API Libraries 9.1.0, 8.1.2




Performance Enhancements

Area Description

dereferencing tags. Tags are now hashed improving performance of complex scripts with many tags.

If cache If expressions are converted into binary trees and cached the first time through.

The expression is not parsed again. This happens even if the expression is used in different areas of the script..

Section names are case sensitive

Section names in a Meta-Update script have always been case sensitive. In some cases, prior versions would allow case differences from a section name and the referencing section name. These will now cause errors.



Area Description

dereferencing tags and fields

When a Tag or Field is not defined, Meta-Update will throw an error.

Expressions to be dereferenced will now cause errors in scripts that would have been “logically incorrect” but may have “worked” without errors before.

Consider this script fragment:

@Cmd = Ref, V, BooolVar, 1

@Cmd = @if(“$V, BoolVar$”)

@Cmd = Msg, i, BoolVar= $V, BoolVar$

@Cmd = endif

With this change, Meta-Update will throw an Error on lines 2 and 3.

Prior versions of Meta-Update would not throw an Error and would return the same un-dereferenced string. This would cause the if to be considered true and would yield this message:

i Msg SomeBoolVar= $V, SomeBoolVar$

The correct solution is to fix the typo on line 1 changing the misspelt “Boool” to “Bool”.


Release 5.57 2015-Nov-24


Overview

The 5.57 release of Meta-Update fixes a single reported problem with release 5.56.






Release Number 5.57 Release Date 2015-Nov-24 Platforms Windows (i32, x64), Linux (LX32, LX64) ARS API Libraries 8.1.2




Bugs Fixed

Area Description

@Cmd = Copy using in a file’s fields.

If the Copy command used a read server the 64 bit binaries could cause the read server tag to be not found.


Release 5.56 2015-Sep-30


Overview

The 5.56 release of Meta-Update is a significant maintenance release which offers 64 bit binaries, an updated PCRE component, and an upgrade to the 8.1.02 release of the BMC Remedy API, scripting enhancements.




Release Number 5.56 Release Date 2015-Sep-30 Platforms Windows (i32, x64), Linux (LX32, LX64) ARS API Libraries 8.1.2





Keyword Added Usage

Variable names for the Reference assignment commands

When assigning a Meta-Update variable, both the Tag and field of that variable can have substitution.

Before this release only the Tag could use substitution.

A new sample script 003-SvrInfo\900-SvrInfo-set.ini demonstrates a simple use of this feature. This script allows the setting of any of your server’s AR_INFO fields from the command line. For example, you could set your server into Admin mode in an automated way.

Field Format truncation added

A new keyword is added to field formats. This allows easier truncation of long values. Specifying ”trunc

nn” in a field format will cause the value to be at most

nn characters long.

Status = 0 If the Status keyword is used to inhibit status messages, the end of section message is also inhibited.

Loop = Join A new Loop type is introduced to follow all real forms that make up a Join.

@Cmd = Reference @fmtqry

A new Reference command is introduced that can take Remedy query text and replace all variables with the actual data of the supplied Remedy record.

Loop = String Sort options

On string loops, a reverse sort reverses the sequence of returned strings as though the string was read from right to left.

@Cmd = Copy single string target added

When assigning to an output pattern file, or a single string reference, the Copy command is now available to add text to the string.

An additional Ptn argument is added to specify the

string to be generated on each field.

Additional SkipDisplayOnly, and SkipNull keywords

are available to control the set of fields being copied.


Other Changes

Area Description

PCRE library upgrade PCRE version has been updated. Please see PCRE at http://pcre.org/ for full documentation.

Windows 8.33

Linux 8.2

Linux Glib 2_7 dependency removed in Linux distributions

A dependency for a glib component not in the recommended OS version for ITSM 7.6.04 has been removed.

Common release number

All Meta-Update utilities will now report a common release number.

The “R”, or Run level trace message will report the build date and internal release number. It will be split across two lines is required.

SthArsTime conversion utility added

This utility has been added to the distribution and documentation. It simply converts date and times between the internal database format and external dates.

http://pcre.org/


Bugs Fixed

Area Description

Missing or incorrectly spelled keywords in a ReadServer section cause Meta-Update to abort.

After the error message was produced Meta-Update did not terminate properly. Now fixed. Problem only happened when the Server, User, and/or Password keywords were missing.

AttachSave command fails after copying attachments into other Remedy forms.

The AttachSave assignment command would fail when the attachment being saved was already retrieved (for example to assign to another Remedy record).

This has been corrected.

Copying time fields When copying time of day fields an error was thrown.


Copying ARS fields with names ending in spaces

When copying ARS fields, fields with database names that ended with a space caused and unknown field error and were not copied. ITSM has a few such fields.


Copying into string fields ignored the Duplicate options

When copying from any type into string fields, the Copy always overwrote the contents of previously assigned fields.

Corrected so that the Duplicate options on the Copy command are followed.

LookUp Queries would not retry during server crashes.

When a LookUp issues an ARS Query, the retries would not be attempted. Note that Query= statements worked correctly.

Corrected.


Documentation Changes

Area Comments

Running Changed due to the 64 bit introduction. Output Statement More information and examples added. How to open

multiple CSV files added. Reference Command More information and examples added.

The new @fmtqry is added

Script Reference Loop statement

New type of Loop is documented.


Release 5.53 2014-08-15


Overview

The 5.53 release of Meta-Update is a maintenance release which offers a large performance improvement during form retrieval and corrects a little used omission in the Set Schema Archive assignment command.



Release Number 5.53 Release Date 2014-Aug-15 Platforms Windows, Linux

Solaris will be released Sep 15. ARS API Libraries 8.1




Performance Enhancements

Keyword Added Usage

Form Initialization When any Remedy forms are used in Meta-Update, information for that form and all its fields are retrieved from the server.

This process is improved by 14000% for large ITSM root request forms and by 260% for small forms.

It is further improved when server access times are longer.

The effect is that the first time a form is Queried, Updated, or Loaded, that is, the first time a form is introduced in a Meta-Update script and the CTL-form name tag is created, the number of server calls will be reduced from 2 + as many fields as defined in the form to 3.


Release 5.51 2014-06-15


Overview

The 5.51 release of Meta-Update introduces a new style of script arguments and script invocation that allows for default values, the ability to continue a Meta-Update job across server restarts without errors in the API.



Release Number 5.51 Release Date 2014-Jun-15 Platforms Windows, Solaris, Linux ARS API Libraries 8.1




Script Enhancements

Keyword Added Usage

Arg This keyword indicates a new style script argument which can have a default value specified. It is only available in the [Main] section.

The old style ArgNm keyword is supported but

deprecated.


Meta-Update Run Enhancements

Keyword Added Usage

SthApiRetry This environment variable can be used to have Meta-Update retry API calls on specified server errors.

New style of arguments The command to invoke Meta-Update can use new switch-style arguments in place of positional arguments.

The switch style arguments on the command enhance clarity and allow for default values to be specified.

New help text, -help switch

When Meta-Update is invoked with no arguments, the default help text is produced and no errors are returned. This text has been changed to outline the new script arguments.

A new switch: –help can be used to get more detailed

usage instructions.

API Retry Environment Variable

Some API functions can now retry the API call to the server based on configurable ARERR codes, a maximum number of retries, and a delay between retries.

The environment variable SthApiRetry= may be used to specify these retry settings.

Without this environment variable, all API calls that fail cause an error in Meta-Update that can result in a record being lost, not found, or the Meta-Update job terminating before processing all records of a query.

The format for the string is as follows: start_ARERR_number [ - stop_ARERR_number ] Retries Delay

Single or ranges of ARERR numbers can be specified. A Retry count of 0 means infinite number of retries.

The Delay is in seconds. A Delay of 0 means no delay.

On Windows and LINUX, one could set the retries like this:

set SthApiRetry=90-92 0 60 93 0 30

export SthApiRetry=90-92 0 60 93 0 30

These examples retry API calls resulting in error 90, 91, 92, 93, retrying an infinite number of times, with a 30 second delay on ARERR 93 (timeout due to busy server) and a 60 second delay for ARERR 90, 91, 92.


The Command Line A Meta-Update command at a minimum specifies the Meta-Update script and the starting section within that script. That script may require arguments and Meta-Update accepts built-in switches – for example to run the debugger or increase logging. To maintain compatibility there are two forms of Meta-Update command lines that can be given. The older, deprecated, command line uses unnamed positional script arguments coded in the order of the script’s Arg= statements and following a –p place marker.

>>> SthMupd.exe 090-SvrAdmin\220-SwLogs.ini Do –p tst1

I terminating successfully in 2 sec.

The new command line uses named arguments that can be coded in any order before or after the script and section.

>>> SthMupd.exe 090-SvrAdmin\220-SwLogs.ini Do –log tst1

I terminating successfully in 2 sec.

Either form of the command line may be used on any script. Software Tool House recommends the use of switch based arguments for clarity. By convention, in this document and in our samples, script arguments are specified after the script file and section name.

>>> SthMupd.exe 090-SvrAdmin\221-SwLogs.ini Do

Line 28 - required argument -log not on command line; no default specified

E . Function:

E . This is a Meta-Update script that switches the ARserver log files

E .

E . Usage

E . SthMupd 221-SwLogs Do -log xxx

E . where xxx is a log file name without a path

E . and without the .log

E . The path and ".log" are configurable

E . in the script

E . Examples

E . SthMupd 221-SwLogs Do -log my

E . will set all log files to: "/apps/bmc/ARSystem/db/my.log"

E .

E terminating unsuccessfully in 2 sec.

Meta-Update has a set of switches that may be specified on the command line. Each script can also define a set of arguments that may be set on the command line. Entering the Meta-Update command with no arguments yields usage help. Entering the Meta-Update command with the single –help switches yields more detailed help. SthMupd.exe

SthMupd.exe -help | more


Usage and Switches Entering the Meta-Update command with no arguments yields usage help. Entering the Meta-Update command with the single -help switches yields more detailed help.

SthMupd.exe

SthMupd.exe | more

Logging -d Specifies logging.

By itself, all specified full debugging logs to the default log file with no ARS Server logging and no Debug2 logging.

--d As above but includes Debug2 logging and ignores any Trace assignment commands in the script.

-q Inhibits echoing of specific logs to the console but does not affect the logging file.

-v Verbose. Equivalent to –d:qas All field structures, queries, and data values are logged.

Development switches -e Single error mode.

Stops execution of the script when the first error is encountered. -g Debugging more.

Enters the Meta-Update debugger.

Server switches

Note that servers and authentication may be specified on the command line, in the script, or default to the environment variables set by the SthLic.cmd batch file.

Defaults for the Main server when not coded on the command line or in the script are the environment variables:

D dD

ArsSvrAdmin The server name or IP. ArsPort The server port. Use of the port mapper is

the default and can be specified with zero. ArsUsr The ARS user that Meta-Update will be

running under. Note that this user generally has administrator rights.

ArsPwd The encrypted or plain text password of the ARS user that Meta-Update will be running under.

-server xxx Specified the main ARS server. May be an IP or machine name. May also point to a specific server of a load-balanced server group.

-port xxx Specified the main ARS server’s port number. Zero is the default and indicates that the port mapper is used.

-user xxx Specified the main ARS server’s login user that Meta-Update will be running under. Note that this user is generally an administrator.

-password xxx Specified the ARS user’s password. May be plain text or encrypted with SthLicUpd.cmd.


Other switches -help More detailed usage instructions.


Usage Help Text Meta-Update Version 5.51 for ARS lib 8.1.0

(c) Copyright 1996-2014 by Software Tool House Inc.

www.softwaretoolhouse.com

Function:

SthMupd runs a Meta-Update script at the specified section

against a BMC Remedy Server.

See: http://www.softwaretoolhouse.com for the User's Guide and Licensing.

Synopsis:

SthMupd [ switches ] script-file section [ script-arguments ]

The script-file and section must follow each other.

Switches and arguments have the form: -switch [ value ]

The script can include named arguments which are specified by using the script's

argument name as the switch followed by the value for that argument. The script

should explain its usage when run with Meta-Update with no switch arguments.

script-file is the Meta-Update script to run; may be found in the path-like

Environment Variable: SthScriptPath

section a section to process in the script file ("Do" for samples)

switches for logging; Warning: Produces large output and slows throughput.

-d Full tracing into SthMupd.log with no '2' or ARS server tracing

--d Full tracing like -d, plus: '2' and ignores script Trace commands

-d:x,y,f Tracing: x specifies tracing levels: qsad2flp

y ARS client tracing flags: fsap

f is the tracing file name (local or Caution: global)

-q,-quiet Quiet: inhibit all output to stdout (not log!)

-v Verbose: same as -d:qsa

switches for script development:

-g Debug Mode: enter script debugger; "help" for commands.

-e single Error: terminate job on first error (for script dev/test)

switches for specifying servers Note that servers must be licensed.

Set defaults with SthLic.cmd

-server server the [Main] server default: ENV, ArsSvrAdmin

-user user the [Main] server's ARS user default: ENV, ArsUsr

-password Enc:xxx the [Main] ARS User's password default: ENV, ArsPwd

-port port the [Main] server's ARS Port or 0 default: ENV, ArsPort

other switches

-help more detailed help (pipe to more)

Deprecated positional argument synopsis:

SthMupd [ switches ] script-file section [-p script-arg1 [ arg2 [ arg3 [

...] ] ] ]

For more details, execute:

SthMupd -help

143704.690 i terminating successfully in 0 sec.

In the local trace version, the –d switch causes a high level of tracing. This data is appended

to a file that will grow if not deleted occasionally. Without the –d, the file will still be continually

added to, but at a much reduced volume. Only Error, and other informational messages will be written. See Tracing below for more information. In the Trace Server version, the –d switch causes a lot of message traffic between Meta-

Update and the Trace daemon. The trace files are cycled through and do not grow beyond the limits specified in the trace configuration. See Tracing for more information.


The –q switch indicates quiet operation. No messages will be echoed to the stdout or stderr

files at all. This includes all Error and Info messages as well as the copyright notice. These messages will still appear in the logs. The –n switch indicates a null operation. No database writes are performed but all queries

and loads are processed. The assignments are also processed and the updating data is printed to the console. This may be very useful when you are developing a new script file. Note that with complex scripts, because no database writes are performed, references needed may not exist. The –e switch indicates a “single error” operation. The first error that occurs will stop the run.

Normally, a file or query is processed and sections that are launched may succeed or fail. If a launched section fails, then the remaining records in the file or query continue to be processed. Using the –e switch changes that behaviour so that the job is ends when the first

error happens. When developing scripts, this allows the developer to sort out each section in sequence quickly. The script-file parameter is the name of the file containing the Meta-Update controls and

the target record assignments. It must exist and read access must be permitted for the user running Meta-Update. The ArSvr, ArUsr, ArPwd, and, ArPort parameters will override similar parameters in the

Main section of the script file. If they are not coded in the assignment file, they are required on the command line. If ArSvr is coded, the ArUsr, ArPwd, are also required, and ArPort is required if the listed

server does not use Port Mapper. The command line arguments cause the equivalent script file keywords to be overridden and ignored. Generally, one would code these in the file and let the operating system’s file security prevent unauthorised access to that file. This would keep the ARS User and password secure. In the script, these may be set to environment variables or other references. The –p is simply a separator from the previous server, user parameters, and all the following

parameters. These next parameters can be referenced in the script file. They can be referred to as $001, $002, and so on, or they can be named and referenced by those names. These passed arguments can be used as keys in loads, or as text in queries and assignments. Wrap long values in quotes according to your shell as needed.

Using Positional Arguments (Deprecated) Following the script and section a –p switch is used as a script Argument place holder. This is

followed by the argument values specified in the same order as the Arg= or ArgNm=

statements in the script. As this is deprecated, Software Tool House recommends updating any batch files or $PROCESS$ filters to use the new switch based command line syntax.


Specifying Arguments in the script’s Main section

Arg = Optional. If coded, specifies a command argument and optionally a default

value. Only arguments without default values are required on the command line.

Arg = arg_name Default “default”

The reference would become $Arg, arg_name$

Each instance of Arg= names the next argument if positional arguments are

used on the command line.

For the switch based command line, the argument name is used as a switch and it is followed by the argument value:

SthMupd.exe MyScript.ini Do –arg_name “some value”


Bugs Fixed

Bug Description

Error thrown when Output= was coded and Assign= was coded.

An Output= requires an Assign= and an erroneous error was thrown saying that the Assign= was missing.

Error thrown when a complete reference Tag was deleted.

An assignment Reference command that deleted all member of a Tag failed with an error message.

Meta-Schema failed when a Push Fields action referenced a form that did not exist on the server.

This now causes an error message and an invalid Push Fields qualification but Meta-Schema no longer stops.



Area Description

Concepts Example changed

The example in the Concepts section was changed to show a useful “Migrate Any table” script because it is very useful yet quite simple script.

Running Meta-Update Details of the changes made for handling switch based script arguments.

ARRPC The BMC environment variable name for specifying RPC queues was corrected.

miscellany Examples of statement usage were added and changed. Unix and Windows differences were highlighted with an icon. Some passages were reworked for clarity. Customer’s documentation suggestions were incorporated.

We appreciate our customers’ feedback in our documentation and our products.


Release 5.46 2014-01-10


Overview

The 5.46 release of Meta-Update is a patch release for users of release 5.45.

A bug was introduced in 5.45 that caused errors on scripts that produced output files. This bug was fixed in this release No documentation changes other than this release guide were made.

An additional feature is also introduced. Through the use of an environment variable some specific ARS errors can cause the API call to be retired. This will allow Meta-Update jobs to survive ARS server restarts without losing any work.

Note that this feature is not yet in its final form and any syntaxes may be changed in a future release.



Release Number 5.46 Release Date 2014-Jan-10 Platforms Windows, Solaris, Linux ARS API Libraries 8.1, 8.0, 7.6.04




Bugs Fixed

Bug Description

Error thrown when Output= was coded and Assign= was coded.

An Output= requires an Assign= and an erroneous error was thrown saying that the Assign= was missing.

Meta-Schema failed when a Push Fields action referenced a form that did not exist on the server.

This now causes an error message and an invalid Push Fields qualification but Meta-Schema no longer stops.



Keyword Added Usage


API Retry Environment Variable

Some API functions can now retry the API call to the server based on configurable ARERR codes, a maximum number of retries, and a delay between retries.

The environment variable SthApiRetry= may be used to specify these retry settings.

Without this environment variable, all API calls that fail cause an error in Meta-Update that can result in a record being lost, not found, or the Meta-Update job terminating before processing all records of a query.

The format for the string is as follows: start_ARERR_number [ - stop_ARERR_number ] Retries Delay

Single or ranges of ARERR numbers can be specified. A Retry count of 0 means infinite number of retries.

The Delay is in seconds. A Delay of 0 means no delay.

On Windows and LINUX, one could set the retries like this:

set SthApiRetry=90-92 0 60 93 0 30

export SthApiRetry=90-92 0 60 93 0 30

These examples retry API calls resulting in error 90, 91, 92, 93, retrying an infinite number of times, with a 30 second delay on ARERR 93 (timeout due to busy server) and a 60 second delay for ARERR 90, 91, 92.


Release 5.45 2014-01-10


Overview

The 5.45 release of Meta-Update is a maintenance release. In addition to adding ARS 8.1 support, scripting enhancements have been added to enhance modularization of scripts, other scripting enhancements permit greater throughput by breaking up jobs to handle portions of the query results.

If you are upgrading from any release less than 5.20, this is a significant release and the release notes for 5.20 should be reviewed.



Release Number 5.45 Release Date 2014-Jan-10 Platforms Windows, Solaris, Linux ARS API Libraries 8.1, 8.0, 7.6.04





Keyword Added Usage


@include File include facility.

Script files can now include common elements allowing for a more modular design for complex scripts.

AssignInit= and

AssignTerm= in [Main]

The [Main] section can now include AssignInit= and

AssignTerm= assignment sections.

This is a good place for script configuration and script job synchronization signalling. These are done in order specified and before and after any other, control, sections’ AssignInit= and AssignTerm=.

QueryStart= Allows the query results to be started at a specified record.

QueryMax= Processes only the specified number of records from the Query result.

@Cmd = Copy

Meaning of CoreFields On Copy command, the default option of not copying core fields copies the “writable core fields”.

Debugging The @include facility changes the Meta-Update debugger by adding new debugging command to list files included by the script and changes the format of a line number when a script files includes other files.

Script Path Environment Variable

Scripts may be specified on the command line or may be found by searching an SthScriptPath environment variable.

SthScriptPath is set the same way as PATH according to the OS that Meta-Update is running on.

On Windows, one could set the script path like this:

set SthScriptPath=E:\Projects\ITSM\Scripts;D:\Apps\STH\samples\;

On LINUX, one could set the path like so:

export SthScriptPath=/Projects/ITSM/Scripts/:/Apps/STH/samples:

Note the difference in the path and directory separators.


Subdirectories in the paths are not searched. However if the script passed to the command line contains a relative path, that relative path will be checked against the SthScriptPath and

the first matching file will be opened.

Script File: Including Other Files

Script files may include other script files. The resulting script that Meta-Update executes will be the merge of all source files and included files in the order that they are included.

The @include file directive tells Meta-Update to stop processing this script source and

fold in the included source, and finally to resume processing the original script source at the line after the include statement at the original source’s section.

The file name specified on the directive cannot be a reference and must be a valid file name for the operating system on which Meta-Update is running. For example, directory separators must be the correct ones for Linux and Windows.

The SthScriptPath environment variable may be used to set a search path for the included

files. Then the script can simply reference the file name with no path information. That script can then be used on Linux and Windows.

QueryStart= and QueryMax=

Performance Considerations A Query result limit may be imposed through a Remedy server configuration setting.

Meta-Update will retrieve all query results by issuing a Remedy call to get the next chunk of results until all the results are retrieved. Once a set of Query results are retrieved, Meta-Update will retrieve the data for those results in blocks of 100 records. Each iteration of the section will load the next record from the current block until that block is exhausted. It will then retrieve the next block from Remedy. This reduces accesses to the Remedy server to once per 100 records, and 1 per query chunk with a Remedy Server maximum, or 1 if unlimited.

Additional Keywords

0 specifies unlimited


The following optional keywords may be included in a control section that has a Query=

statement.

QueryStart = nnn

QueryMax = nnn

If QueryStart= is coded, the first record returned by the query will be the record specified. If

QueryMax= is coded, the total number of records returned by the query will be limited to the

number given. The values can be integers or references that evaluate to integers. If missing, the default will be the first record returned by the query. The special integer 999,999,999 can be used to override a server-based limit on servers above release 7. It is unnecessary but possible to set this in a Meta-Update script. Meta-Update, by default, will continue issuing queries automatically until all results are exhausted. These keywords can be used to limit the number of records processed by a single job allowing you to start multiple jobs with different QueryStart= values.

In this example of a script, we will run 4 simultaneous jobs with 2.5k per job:

[Main]

ArgNm = start

ArgNm = max

ArgNm = qry

[Do]

Query = Src, HPD:Help Desk, $Arg, qry$

QueryStart = $Arg, start$

QueryMax = $Arg, max$

To fire the jobs we might use a batch file like this:

start SthMupd -d:i,,j1.log example.ini Do -p 00000 2500 1=1




Copy Assignment Command Enhancements

The meaning of “Core fields” as applied to the copy command, does not include core fields that can be assigned without the use of Merge. That is, a Copy command with the default NoCoreAssign option, will copy these fields:

Field Id Common Field Name

4 Assigned To

7 Status

8 Short Description

To not assign these fields with the copy command, add them to the Skip list.


This option is ignored when the target is not an ARS record, and all fields that can be copied – including core fields in the source if that source is an ARS record – are copied.

Debugging

The @include directive allows a single Meta-Update script to include other script files. The format of “Line Numbers” displayed and used as input in the Meta-Update debugger is changed as a result. There are two formats of line numbers when a script uses the @include directive: A single combined line number, A file specific line number comprising the file index and line number within that file. The combined number can be used as input and is listed along with the file specific number when listing source lines. It is the line number of the file that results when all @include directives are resolved. The file specific number consists of two parts: the “file index” and that file’s line number – not taking into consideration any other files.


Debugging: List Files command

The ListFiles command will list all source files and their indexes. List Files Use ListFiles to print your scripts source file name and file indexes:

Mupd Dbg > help listfiles

The ListFiles command lists all source files and file indexes of the

source script

lf ListFiles [n] list file names and indexes

When using multiple source files with the @include directive,

each file is given an index number from 1 upwards.

Line numbers are displayed and entered as either

[ix, num] where ix is the file index, or a single

line number, being the combined line number for the

script with all included files folded in.

The optional argument causes the single file name referenced by

the given index to be listed.

at: [Do] ln 42 Init

Mupd Dbg > listfiles

1 --> 100-Hpd.ini

2 --> 999-Includes\000-Jctl-Sync.ini

3 --> 999-Includes\100-CfgUpdFlag.ini

at: [ Cfg-asg ] 35 [1, 35] Asg

Mupd Dbg >


Other Changes

Area Description

Missing Assign= When a control section has any output with a Create=,

an Update=, or an Output= statement, an Assign= (or

AssignNew=) statement is required and, if missing, an

error is thrown and the control section is not run.


Scripting Depreciations and Changes

Depreciations Replacements

Missing endif Missing endif statement are now a hard error.


Operational Enhancements

Area Description

LookUp Caching LookUp Caches were not used when the lookup returned no records. If a cache is used, and, no records are returned on the first Query or QuerySql, then no further queries will be issued for the same LookUp_Key.

Trace Reductions Many key routines now issue a single “Debug” level trace rather than two function entry and exit traces.

Trace Reductions

-d and--d switches If the trace command line argument is used without specifying the trace levels, desired, the default level will be set to full debugging with the exclusion of the detailed debug level: 2.

An alternate switch --d includes all trace levels. You

can continue specifying the levels you want with –d:lvls as normal.

Specifying server tracing will continue to add the debug detail level 2 as expected.

Input Files with Field Headers can contain untitled columns.

When a delimited file such as a CSV contains columns with no field defined, no error is thrown, and that column will be ignored.

ARS Server Logging When ARS Server Logging is turned on, all ARS Server connections have the server logging enabled. This includes ReadServers.

-d:q Error When tracing level Q for Query is on, all trace messages have been enhanced to return the length of time the Remedy server took to respond.


Bugs Fixed

Bug Description

Error thrown when an empty string was assigned.

An assignment of an empty string caused Meta-Update to throw an error. This is now equivalent to the assignment of $NULL$

Memory leaks A few small memory leaks were corrected.


Release 5.37 2013-03-18


Overview

The 5.37 release of Meta-Update is fixes minor bugs, includes performance enhancements, and offers the scripting ability to terminate a section’s iteration on a condition without throwing an error.




Release Number 5.37 Release Date 2013-March-18 Platforms Windows, Solaris, Linux ARS API Libraries 8.0.0, 7.6.04, 7.6.03, 7.5, 7.1

Note that Software Tool House recommends running Meta-Update compiled against the latest ARS API library no matter the ARS release of your server.




Keyword Added Usage

Additional automatic CTL-schema fields.

The automatic tag for schema information now includes the attribute StatusNum.

This tells the number of values defined for the core field Status or ‘7’.

Until= In a control section that includes iteration with a Query=, QuerySql=, File=, or Loop=, the Until= offers a way to terminate that control section without error.

Trace Assignment Command

A new assignment command is added to control Meta-Update logging per section.


Additional automatic CTL-schema fields

CTL – Schema Tag

Any Remedy form queried, loaded, or updated by a script causes a new tag to be created.

The field, StatusNum is added.

StatusNum integer Number of Status (field 7) values. A zero indicates that this form has no Status and Status History.fields.

0


Until= Statement in Control Sections

The Until statement may be used only when a control section includes an iteration such as

Query=, QuerySql=, File=, or, Loop=.

The Until statement specifies a condition, that when true, causes the control section to stop

its iterations with no errors.

Until = @if(condition)

If an error is needed, use the Abort assignment command.

In a section that does not iterate, any Until= statement is ignored with a warning.

In the following example, an infinite loop is set up but is aborted after a single iteration.

[Do]

AssignInit = Do-asgInit

Loop = While(1)

Until = @if(1)

[Do]

AssignInit = Do-asgInit

Consider this example, where we want to validate that a root request and all its children exist in alternate – or archive – forms. If any child is missing, there is no point continuing. This request has failed the validation. So, say you may have sections querying all of the Incident’s children on the real forms, and a LookUps to check the Archive forms. When the first case of a missing child is found, there is no point continuing any of the queries for this incident’s children, so a flag can be set and all Launched sections would complete up to but not including the section that looped through the Incidents. That section would then iterate to the next Incident. In this example, the flag $V, Do$, is initialized to True and set false when a Work Log for this

incident is not found in the archive form.

[Do]

Query = Inc, &

HPD:Help Desk, &

qry

AssignPre = Do-asgPre

Launch = @if(“$V, Do$”) Do-WL

Launch = @if(“$V, Do$”) Do-delete

[Do-asgPre]

@Cmd = Ref, V, Do, 1

@Cmd = Ref, V, gotIncArch, @LookUp, &

Lkp-Inc-Arch, $Inc, 179$

@Cmd = @if(! “$V, gotIncArch$”) &

Ref, V, Do, 0

[Do-WL]

Query = WL, &

HPD:WorkLog, &

‘Incident Number’ = “$Inc, Incident Number$”

These two sections are entirely equivalent

The Until= stops the

processing of this Incident’s Work Logs as soon as a Work Log record is discovered missing from an Archive form.

If a Work Log is missing from an Archive form, we set the $V, Do$ flag to

false.


Until = (! “$V, Do$”)

AssignPre = Do-WL-asgPre

[Do-WL-asgPre]

@Cmd = Ref, V, gotIncWL, @LookUp, &

Lkp-Inc-WL, $WL, 179$

@Cmd = @if(! “$V, gotIncWL$”) &

Ref, V, Do, 0


Trace Assignment Command

The Trace command allows push, pop, and change the trace settings, when the script is run with tracing. The trace command is generally used while debugging scripts by inhibiting or reducing tracing in already debugged sections and then selectively tracing other sections.

@Cmd = Trace Push

@Cmd = Trace Trc-Lvl [, ARS_Trc_Lvl ]

@Cmd = Trace Pop

Push This is used to save the current trace levels.

Pop Resumes the trace levels at the time of the matching Push. Meta-Update

will issue a Warning when a Pop is used without a previous Push. Trc-Lvl A Trace Level setting. See Running Meta-Update, Tracing for more

information. ARS_Trc-Lvl An ARS Trace setting. Use a string of these letters:

s SQL f Filter

a API p Plugin


Other Changes

Area Description

Default tracing level changed for –d and a new ––d added.

By default, full tracing, as specified with the -d, no longer includes the detail level Dbg2. If ARS client side tracing is also set, the Dbg2 is still included as before.

The new switch --d (with two hyphens) may be used as a short cut to include full tracing including the Dbg2 level. The new switch also causes any trace commands in the script to be ignored.



Area Description

Script Reference New Until= feature added.

Additional information inserted and some sections were reorganized.


Bugs Fixed

Bug Description

Status= Status= incorrectly presumed 0,text when the integer was missing. This defaults to 1 now.

Status= Status= was ignored when specified in some control sections.

SthLicUpd The generated SthLic.cmd file had spaces inserted at the end of some of the “set” statements in Windows.

These were significant in a batch file and had to be manually deleted.

Unix users were not affected.


Release 5.22 2013-01-10


Overview

The 5.22 release of Meta-Update is a minor bug fix release, includes significant performance enhancements, and offers the scripting ability to evaluate dates.




Release Number 5.22 Release Date 2013-January-10 Platforms Windows, Solaris, Linux ARS API Libraries 8.0.0, 7.6.04, 7.6.03, 7.5, 7.1

Note that Software Tool House recommends running Meta-Update compiled against the latest ARS API library no matter the ARS release of your server. The downloadable distribution is built against the highest or second highest release of the BMC Remedy API.



Keyword Added Usage

Reference assignments of date value attributes

Any script date value (from Remedy, or interpreted as a date) can be parsed and its attributes assigned to a Tag.

This allows you to date arithmetic by simply adds and subtracts to an epoch time.

Reference assignments: formatting values

The same format specs used in interpreting SQL and CSV values can now be used to transform individual values and assign the new string to a variable.


Date Information Assignment Reference

The @date command assigns a specific set of fields describing the single date reference in

local time.

@Cmd = Reference, Tag, @date, date

@date @date is used to give information such as the day of week and the

“epoch” value of any date into a specific set of fields into the specified Tag (which can be a reference).

date this can be any Meta-Update recognized date. This can be a reference

that evaluates to such a date.

Meta-Update dates are of the form “1999/12/31 23:59:59” When a date is read from a Remedy Time Stamp or Date field, Meta-Update converts that date into the above format. Dates from files or SQL fields may be converted by value interpretation.

The following table lists the assignments made to the Tag.

Name Type Meaning Initial Value

DateType string Null $NULL$ or “”

Date valid date

Error invalid or unrecognized date

Null

epoch int The Remedy epoch date in number of seconds past 00:00 at Jan 1, 1970 UT

0

IsDaylight bool 1 if the date is in the daylight savings time zone, else 0

0

year int Year 0

mon int Month number 1..12 0

day int Day of month 0

daywk int Day of week with Sunday as 0 0

hour int Hour 0..23 0

min int Minute 0..59 0

sec int Second 0..59 0

The following script fragment will assign a new variable – Varc, Dte – as exactly one year back from the current date.

@Cmd = Ref, Vnow, @date, $TIMESTAMP$

@Cmd = Ref, Varc, yr, @eval &

$Vnow, year$ - 1

@Cmd = Ref, Varc, Dte, &

$Varc, year$/$Vnow, month$/$Vnow, day$ &

$Vnow, hour$:$Vnow, min$:$Vnow, sec$

The following will do the same but with the date being approximately one year ago:


@Cmd = Ref, Vnow, @date, $TIMESTAMP$

@Cmd = Ref, Varc, epoch, @eval &

$Vnow, epoch$ - 365.25 * 24 * 60 * 60

@Cmd = Ref, Varc, Dte-flds, @regex, &

/(.*)/, $Varc, epoch$

[Dte-flds]

Dte = $ Date: epoch


Format Value Assignments

Formatting Values — assigning a single value by transforming with a format

You can use a format assignment to transform a value according to a “format string”. Format Strings” are used in field declaration to interpret SQL or CSV columns or as an output transformation for CSV columns. See “Field Sections” in “Script Reference” for detailed information on format strings. There are two “forms” of a format reference assignment command:

@Cmd = Reference, Tag, Name, @fmt, Val, Fmt

@Cmd = Reference, Tag, Name, @fmtout, Val, Fmt

@fmt These are keywords and must be coded exactly as shown.

@fmtout @fmtout causes the transform to behave as though the field were being

prepared for an output CSV file. @fmt causes the opposite; that is the field is being interpreted for internal

use. This can affect dates for example. @fmt of a date always results in an

internal date and time stamp which can be used in ARS assignments and @date reference assignments. @fmtout, on the other hand, can yield a

wide variety of strings for a date. Val This is the source value. It can be a string reference. Quote this value if

needed. Fmt This is the format specification. It can be a string reference. Quote this

value if needed. Consider that you have an SQL column containing a Remedy time stamp value. You add a number of seconds to it and want to convert it to a date to be assigned to another Remedy field. This code fragment will do that:

@Cmd = Ref, V, NewDate, @eval $Sql, cDate$ - $V, Secs$

@Cmd = Ref, V, NewDate, @fmt, $V, NewDate$, “Date: epoch;”

Say you want to substitute the Remedy Dropdown list word for an integer, you could do the following:

@Cmd = Ref, V, DropName, @fmt $Sql, DopVal$ &

“Subst /0/New/ &

“Subst /1/Open/ &

“Subst /2/etc/”


Other Changes

Area Description

Performance Changes to how references are resolved offers significant performance improvements to most scripts.

Other Since the introduction of BMC ITSM 7.6.04 several tables include a Global Field which is sometimes set and sometimes missing. This field is sometimes missing from the Remedy API ARGetEntryMultiple data and is seemingly replaced by a NULL value for a field Id of zero (0). The API does not allow for field Ids of zero and this is in error.

Meta-Update now tracks of a record is missing values and if there are values for field id 0. It these events, no errors are thrown and the script functions normally.

It issues trace messages, hidden from the user, under the Data or Dbg settings. If the missing global field is itself referenced, an undefined field error will be thrown.



Area Description

Reference Assignments – Date Information

New feature added.

Reference Assignments – format values

New feature added.


Bugs Fixed

Bug Description

Read Server Password Encryption

The new ARS User password encryption facility was not extended to Read Servers causing failures to authenticate to a Read Server in some cases.

$TIME$ expansion failed on some 64 bit Windows machines.

On occasion, when $TIME$ was expanded on some 64 bit Windows machine, either the wrong date stamp would be produced or the Meta-Udpate process.would fail.


Release 5.20 2012-11-25


Overview

The 5.20 release of Meta-Update is a major change to the functionality and flexibility of Meta-Update scripts. Added features include:

1. Flexible IdLog reporting. 2. New automatic attributes. 3. Ability to assign references that are themselves a reference. 4. Ability to reference and set a form’s Archive properties. 5. Ability to encrypt ARS User passwords. 6. Automatic generation of the server selection batch file: SthLic.cmd or SthLic.sh

This release continues the introduction of new features to reduce efforts in writing complex scripts such as those needed for ITSM migrations and imports, or ITSM root request archiving.

This release adds the ability to encrypt ARS User passwords. A new utility is used to either encrypt passwords or generate the previously supplied and edited SthLic.cmd file. All bundled utilities will accept either encrypted or plain text ARS User passwords in whatever manor they are supplied.

Significant performance enhancements are made to the release version. Performance improvements are made to file handling on both input and output.

A new Linux release is now available.



Release Number 5.20 Release Date 2012-November-23 Platforms Windows, Solaris, Linux ARS API Libraries 8.0.0, 7.6.04, 7.6.03, 7.5, 7.1

Note that Software Tool House recommends running Meta-Update compiled against the latest ARS API library no matter the ARS release of your server. The downloadable distribution is built against the highest or second highest release of the BMC Remedy API.



Keyword Added Usage

IdLog The IdLog facility is enhanced and can be controlled on a detailed level. The IdLog keyword can be used in any control section. Different IdLog files may be generated on different events and assignments can be specified.

Merge= Merge may be specified as a reference and can have the value “Off”

Server= The ARS authentication keywords in [Main] will now default to use the standard environment variables if they are not coded on the command line or in the script. They must still be specified in Read Servers.

AR_INFO Assignments Any assignments to the automatic tag AR_INFO will issue a change to the value on the server.

Read Servers automatic tag AR_INFO is added and can be assigned

Similarly, a tag is automatically created for Read Servers, and any assignments will issue change the value on the server.

The Tag assigned in reference command may be a reference

When assigning variables using a reference command, the tag being assigned can itself be a reference.

This can be used to build arrays and advanced scripts.


Other Changes

Area Description

ARS Server Password Encryption

A facility for encrypting sign-on passwords has been introduced. All utilities will now accept either plain text or encrypted passwords.

SthLicUpd utility. A new utility is introduced to maintain the SthLic.cmd or SthLic.sh files generated with your licenses.

Performance Improvements on files

Both input and output files have performance improvements when field formatting is specified.

Output= can create new files

A section can have an Output= where the Tag is a reference. Each time the Output= is encountered, the Tag is dereferenced and if a new Tag, a new output file is opened. If the Tag has already been opened, a new record is written to the previously opened file.

IdLog Facility

The IdLog can now be fully controlled on section by section and event by event. The format and content of the output IdLog file can be specified. Any number of IdLog files with different content and on different events can be specified.

As many IdLog statements as needed may be coded in control sections.

An IdLog is used to create a delimited file with a row for each record read and updated. You can specify multiple IdLogs and events that the IdLog will be created for. You can also control the format and content of the IdLog fields.

An IdLog is primarily used to track errors so that a subsequent Meta-Update run can process only those records that resulted in errors.

Syntax and usage of IdLogs:

IdLog = Tag &

On Event1[,Event2...] &

Fdef def_section &

Fname file_name &

Key key &

Fasg assign_section

Tag The Tag identifies an IdLog file and file section. If the same Tag is used in

two different IdLog statements, they must specify the same file and file definition section or an error will result. You may change assignments and events on different IdLog statements in Launched sections


A special Tag is used to turn off all Id logging for a section:

IdLog = Off

On Specifies a series of events for which this Id Log will be written to.

Events are keywords and must be coded exactly as follows: Update a record is updated (successfully or not)

UpdateErr a record update failed

Create a record is created

CreateErr a record create failed

Iter an iteration is done: the next record, SQL row, or file row is read,

or the next loop value is processed IterErr an iteration failed.

Fdef Optional. Specifies a file section.

The IdLog will be written with the fields and attributes of this file section. Automatic fields, if not specified, will be added. If not specified, only the automatic fields will be in the IdLog file. These are:

Time The time of the event.

Server The ARS server name

User The ARS user

Schema The schema or file name. NULL for SQL queries.

Key The value of ‘1’ for ARS schemas, of a string made of the first

few attributes for SQL queries, files, and Loops. Operation One of: Read, Update, Create

Op2 Either blank or “Merge”.

Result One of: OK, Err, or Err followed by an error message.

Key Optional. A reference string that is used instead of the default key value

generally containing references from the sections iteration Tag.

Fasg Optional. An assignment section name. This can be used to override the

default assignments as given above or to assign values to other fields defined in the file section for this IdLog. For example you could add some fields from an SQL query to the IdLog and use the assignment section to assign values to the added fields and even to change the assignment to automatic fields such as the Schema or Key field.

The Tag is only used by Meta-Update to determine that two IdLogs from different sections refer to the same file. A special Tag is used to turn off all Id logging for a section:

IdLog = Off

When a section with an IdLog launches other sections, the IdLogs are carried through to that launched section unless that launched section has its own IdLog statements.

IdLogs are recognized as the same when they have the same Tag. It is an error to specify two IdLog statements with the same Tag and different file names or different file sections.


You can use the same Tag in a Launched section’s IdLog to specify a different assignment section. That section could include the launched section’s IdLog assignments if needed.




@Cmd = Copy Duplicate option default changed

As of this release, the default option when using the Copy assignment command is DupIgnore.

Use one of the Copy Duplicate assignment options in your script if this is not desired.

With the default, simply assign individual fields before the Copy command to override the Copy commands assignments.

Load statement (Deprecated) may fail in some cases.

The Load Statement has been deprecated for some time. As of this release, when a Request ID value is specified, and the form has undergone a Request ID prefix change, it is possible that the Load will fail.

A Load can always be replaced with a LoadQ with a Query of ‘1’ = “the id specified” on the

Load.

This has been the preferred way of Loading records for some time.

Note that the LookUp facility is another way of Loading records and has added functionality such as caching and the ability to fail without errors.

Support for deprecated Load Statements will be withdrawn and an error will be thrown showing the equivalent LoadQ statement.



Area Description

Licensing Usage of the generated SthLic.cmd (and SthLic.sh) file is described.

SthLicUpd Utility Usage of the new utility to generate these files is described.

ARS User Password Encryption

The Password encryption used by Meta-Update and bundled utilities is described.

Licensing Usage of the generated SthLic.cmd file is described.

Performance Tips A new Performance Tips section is added to the User’s Guide

AR_INFO A table of all available AR_INFO fields, whether they are readable or writable, and sample values from an OOTB 7.6.04 is included.

IdLog The IdLog facility is documented.

Samples Additional Samples are included and explained.

Load The deprecated Load= statement documentation has been removed.

FieldsRequired= FieldsInFile=

These keywords were missing and have been added to the File Section of the User’s Guide.


ARS Authentication Password Encryption

Passwords can now be encrypted using a utility. Once encrypted, only the same OS user that encrypted the password can use that password.

The SthLic.cmd and SthLic.sh scripts that set environment variables for a licensed server

and authentication can be automatically generated on all supported platforms – see below.

These files will allow the setting of environment variables by specifying the desired server, so that for example, a query can be run against one server and then run against another server.

All utilities bundled with Meta-Update will accept either plain text or encrypted passwords in all the methods that ARS Passwords may be set: on the command line, in scripts, or, in environment variables.

If using ARS password encryption, the supplied passwords must be encrypted for each Windows or Unix user that will use Meta-Update. The encryption / decryption is dependent on the currently signed on user.

A new version of the SthLic.cmd and SthLic.sh must be generated for each Windows or

Unix user even if the ARS User is the same.

This means that when using ARS Password Encryption, the files, SthLic.cmd and SthLic.sh

cannot be copied from machine to machine, and, if a single machine is used by more than one user, different SthLic.cmd and SthLic.sh files will need to be used by each user.


SthLicUpd Maintenance Utility

This utility can be used to encrypt ARS passwords and to generate an SthLic.cmd and

SthLic.sh scripts based on license files found in a specified file.

The utility is available on all supported platforms and may be run in prompt mode where it will ask you for all needed information.

Alternate names, ARS Server IPs, Ports, Users, and Passwords can be set. ARS Passwords by, default, are encrypted.

The SthLicUpd.exe utility will generate only one of the SthLic.cmd and SthLic.sh files as

appropriate for the system that it is being run on.

Files produced by SthLicUpd containing encrypted passwords are not transferrable across platforms or users. You have the choice to encrypt the ARS User’s password.


Usage

Function:

SthLicUpd is used to modify a Meta-Update SthLic.sh

Modes:

SthLicUpd can be run in different modes

Prompt will scan license files, prompt for needed info

and generate a new SthLic.sh.

Pwd will encrypt a single ARS user's password or modify

your SthLic.cmd file's passwords.

Synopsis:

SthLicUpd.exe mode [ switches ]

where:

mode is one of: Prompt or Pwd

Prompt Run in interactive mode to scan licenses

can supply -lics and -out arguments

Pwd Will encrypt ARS users’ passwords

switches are as follows:

-licpath path The path for the license files;

must be a directory

-out file The output path and file name

Default for -out is SthMupd.sh in the bin directory

that contains SthLicUpd.exe; that bin directory is also

the default for finding license files.

Miscellaneous switches

-d Specifies full tracing

See: http://www.softwaretoolhouse.com for the Meta-Update User's Guide.

Prompt mode will find all available *.lic files in a single directory and ask for any needed information. It will then generate a new SthLic.cmd or SthLic.sh file.

These files will set the environment variable for ARS server connectivity and authentication which all Meta-Update utilities will automatically pick up.

Password mode will simply allow you to encrypt any number of ARS User passwords. You can then use these encrypted password strings in any of the Meta-Update utilities to authenticate to the ARS server.


Sample Prompt Session:

Sample Password Session:

Using the generated SthLic.cmd or SthLic.sh files

On Unix the generated file must be set to be executable. To do so, enter the following command:

> chmod +x ./SthLic.sh

The shell script needs to be “Sourced” or any changes made to environment variables will be lost upon its completion.

When executing the shell script, source it by prefixing the command invocation with a dot, as follows:

> . ./SthLic.sh

D:\Apps\Sth\Meta-Update > SthLicUpd.exe Prompt

D:\Apps\Sth\Meta-Update >


D:\Apps\Sth\Meta-Update > SthLicUpd.exe Pwd


On Windows, simply execute the batch file normally:

> .\SthLic.cmd

The SthLic –help command will list all licensed servers and alternate names for the servers.

If the command has already been issued, that is, if the appropriate environment variables are already defined, the command will report the currently set server.

In the above example, a single server is licensed and it has two alternate names given for the convenience of SthLic users.


D:\Apps\Sth\Meta-Update > SthLic.cmd --help


Bugs Fixed

Bug Description

Request id value formatting

When a request id field underwent prefix or size changes is was possible for a query to return records with different request id value prefixes or sizes.

An Update= would sometimes fail to update a record due to this.

Fields named “1” that were not request ids caused Attachment transfer problems.

A non-request id field named “1” - but with a different field-id - caused an error when retrieving attachments.

Loop = Fields worked on ARS records only.

The new Loop = Fields facility failed any Tag that was not an ARS records. No customers were affected by this bug.

The sample script 000-SvrInfo has been significantly reduced by using the new Loop = Fields.

Loop = Fields didn’t display the field on the iteration message.

Now corrected. The Tag and Field are displayed.

Fields whose names ended in a space caused an error when they were in the Copy assignment commands Source Tag

If a form’s field’s name ended in a space, and a record of that form was used as the source tag in a copy assignment command, a “Field Not Found” error would be thrown.


Release 5.15 2011-12-10


Overview

The 5.13 release of Meta-Update continues the introduction of new features to reduce efforts in writing complex scripts such as those needed for ITSM migrations and imports.

This is a maintenance release of Meta-Update.



Release Number 5.15 Release Date 2011-December-10 Platforms Windows, Solaris ARS API Libraries 7.6.04, 7.6.03, 7.5, 7.1




Keyword Added Usage

A new reference command is added that yields information on a Tag and Field and its value.

This can be used to determine if a field exists, the type of field, and attributes of a field and schema.

A new Loop=Fields is introduced.

Fields of any tag can be looped through. For ARS tags this can be limited by field types. For example, the Samples now includes a Table backup / restore script that save attachments to the file system. It does this by looping through the attachment fields of the table it’s backing up.

The Reference @spawn introduces a keyword to allow placement of the spawned command redirection within the command.

The @spawn reference assignment command that returns the stdout and stderr text as references may need to insert the redirections to temporary files at a point in the command string other than at the end.

The $redir$ keyword may be used in the @spawn command to insert the redirection to files needed.

@info Reference Assignment Command

Assigning a set of single values to a Tag from an @info of a reference:

@Cmd = Reference, Tag, @info, SrcTag, [ SrcFld ]

@info @info requests a specific function. The SrcTag and SrcFld can

themselves be references. @info causes the Tag to be assigned a specific set of fields depending of reference passed.

SrcTag this can be a Tag loaded in your script, or a reference that will evaluate to

a Tag that is loaded in your script. If only the SrcTag is supplied, only

those names appropriate to the SrcTag “record” that is loaded.

SrcFld This can be a field name defined by the SrcTag “record”, or a reference

that will evaluate to such a field name. If the SrcTag is an ARS record,

the SrcFld may also be specified as a field id.

When a SrcFld is specified, the field and value specific assignments are

set.

The following [abbreviated] table lists [some of] the assignments made to Tag.

Name Type Meaning Initial Value


DefinedTag bool Tag is defined 0

DefinedField bool Field is defined 0

Type Undefined, ARS, File, SQL, String

Tag type Undefined

TypeSchema Regular, Join, View, Dialog, Vendor

ARS Schema Type ""

KeyLen integer Length of the request id field ('1'), almost always 15

15

FieldTypeInt integer ARS field type integer ""

FieldType Integer, Real, Char, Diary, Enum, Time, Bitmask, Bytes, Decimal, Attach, Currency, Date, Time_of_day,

ARS field type as a string ""

FieldId integer ARS field ID 0

FieldName string Field name ""

Value string The field value ""

ValueLength integer The length of the value 0

New Loop=Fields Iteration

There are four types of loops: String a string is parsed according to a specified delimiter.

Diary all entries in a Diary field value are iterated through.

While a loop continues while the specified condition is true.

Fields all fields defined by a source Tag are looped through.

A Fields loop sets the named values defined by the @info Reference assignment command (See above Error! Bookmark not defined. a more complete list) into the Tag: FieldName The name of the field of this iteration Value The actual value of that field ValueLength The length of the above string Example 3 Fields: Loop = Fields, fTag, SrcTT, Type Attachment, NoNulls

In the third example,a Loop of only a records’ attachment fields containing attachments (non-null) are iterated through. The Tag, fTag will contain the information returned from the @info reference assignment

command.


If the record has three attachment fields and two have no attachments (are $NULL$) the loop will execute once only with these fields being assigned to the fTag specified:

fTag Type ARS

SchemaName HPD:HelpDesk

FieldName Attachment1

FieldId 3000100010

FieldType Attachment

Value C:\tmp\Some_File.jpg

ValueLength 19

New $redir$ keyword for @spawn

Assigning a process’ stdout and stderr files to a string Tag:

@Cmd = Reference, Tag, @spawn, process [ arguments ]

@spawn This is a keyword and must be coded exactly as shown. This command

is used to make assignments to three specific string names on the specified Tag

rc the spawned process’ returned integer

stderr the stderr output (console errors) of the command;

if the process succeeded this is generally empty: “”

stdout the stdout output (console) of the command

The process must be on the path when Meta-Update starts. The process cannot have redirection operators for stdout and stderr. These are appended by Meta-Update. These are temporary files that will be automatically deleted after the command runs. If desired, the placement of Meta-Update’s stdout and stderr redirects may be controlled by use of the $redir$ string. If missing from the text to spawn, the redirects are added to the

end of the command text.




@Cmd = Copy Duplicate option default changed

As of this release, the default option when using the Copy assignment command is DupIgnore.

Use one of the Copy Duplicate assignment options in your script if this is not desired. With the default, simply assign individual fields before the Copy command.



Area Description

Loop= Fields in Concepts, Scripting Reference, Samples

The new Loop=Fields feature is described.

Assignment Reference @Cmd = Ref, @info

The new feature is described.

Assignment Reference @spawn

The $redir$ keyword is described.

Samples Table backup / Restore

A new sample is added. This is also available in the Script Library. A generalized table backup restore that handles attachment fields and can be run in either UNIX or Windows.


Other Changes


Bugs Fixed

A bug that caused String Loops with a single character delimiter to return a single value was introduced with multi-character delimiters in release 5.12. This was fixed.

This worked correctly on UNIX platforms and has been corrected so that it works correctly on Windows platforms as well.


Release 5.13 2011-10-10


Overview

The 5.13 release of Meta-Update continues the introduction of new features to reduce efforts in writing complex scripts such as those needed for ITSM migrations and imports.




Release Number 5.13 Release Date 2011-October-10 Platforms Windows, Solaris ARS API Libraries 7.6.04, 7.6.03, 7.5, 7.1




Keyword Added Usage

A new reference command is added so that many fields can be added to a single Tag at once.

Assigning variables is enhanced to that an assignment section may be called that has on the right side new variables added to a single Tag.

Assigning many fields and values to a single Tag

@Cmd = Reference, Tag, @, Sec

@ When the Name is a single “@”, it tells Meta-Update to treat the value as an

assignment section where any field can be assigned a value. All fields become a field of the named Tag.

This is a good way to assign many fields to a single Tag in one section.

Sec This is the single section name that will be executed.

All new fields assigned by placing the field name on the left will be added to the Tag. The section name can be a reference.

Assigning a field twice causes concatenation. If you need to initialise specific elements of the Tag or delete the Tag before this reference command is executed.

After either of these two assignment sections is executed, the following references will be defined: $V, v1$ v1-val $V, v2$ v2-val $V, v3$ v3-val

[Asg]

@Cmd = Ref, V, v1, “v1-val”



[Asg]

@Cmd = Ref, V, @, Asgv1

[Asgv1]

v1 = v1-val

v2 = v2-val

v3 = v3-val


Other Changes


Bugs Fixed

On Windows only, assigning a value to an environment variable did not change the process’ value for that variable. Spawned client processes did not have the up-to-date value in their environment.

This worked correctly on UNIX platforms and has been corrected so that it works correctly on Windows platforms as well.


Release 5.12 2011-09-24


Overview

The 5.12 release of Meta-Update introduces new features to reduce the complexity of writing selects in the QuerySql= keyword.




Release Number 5.12 Release Date 2011-September-24 Platforms Windows, Solaris ARS API Libraries 7.6.04, 7.6.03, 7.5, 7.1




Keyword Added Usage

Sql= added to file field declarations.

When a file and field is used for a QuerySql statement, the subselect text to select that field may be coded in the field’s Sql= value.

When generating the special CTL tag based on the fields, fields with Sql= will be replaced by the text of that Sql=.

Any substitutions in the body of the Sql= will be replaced when the QuerySql is invoked.

New predefined CTL Tag

When a QuerySql= is used in either a Control or LookUp section, and that QuerySql specified a field list for interpreting the results, the set of fields are made available in a special CTL tag.

This has the effect of reducing the code of the QuerySql= as the list of fields can be used to generate the select text.

The Tag is the name of the field section specified in the QuerySql, suffixed by “-SqlSelect”.

Loop = String enhancements.

A further enhancement allows to “double anchor” a string as a delimiter. Only when that string is preceded by two new lines, is that string considered a delimiter.

Sql= keyword added to field declarations

When declaring fields for files or SQL interpretations, a new Sql= keyword is available to associate Sql text with the field. This keyword must precede any format specifications.

This keyword is only used to generate an automatic CTL tag when used with the QuerySql=

keyword in a Control or LookUp section.

When used, this text replaces the field name in a string that can be used to select all fields declared in a field section referenced by the QuerySql= statement.

New Predefined CTL Tag

When a QuerySql= is used in either a Control or LookUp section, and that QuerySql=

specified a field list for interpreting the results, the set of fields are made available in a special CTL tag.


This has the effect of reducing the code of the QuerySql= as the list of fields can be used to

generate the select text.

The Tag is the name of the field section specified in the QuerySql=, suffixed by “-

SqlSelect”

Consider the following example:

QuerySql = Src, &

MySqlFields, &

select &

$CTL, MySqlFields-SqlSelect$ &

from $CFG, SqlPfx$.MySqlTable A &

where 1=1

[MySqlField]

OBJID = $

LOGIN = Sql=” ( select LOGIN &

from $CFG, SqlPfx$.AnotherTable &

where NAME = ‘A.NAME’ &

)”

DATE_CRE = $ Date: epoch

Assuming the $CFG, SqlPfx$ evaluates to “SA”, Meta-Update will send the following SQL

query to ARS:

select OBJID, ( select LOGIN from SA.AnotherTable where NAME =

A.NAME ) , DATE_CRE from SA.MySqlTable A where 1=1

Loop = String enhancements

Loop = String, Tag is now enhanced so that the delimiter specified may be a reference

and can be more than one character long and can be singly or doubly anchored by a new line.

When a double anchor is used, only when the delimiter string is preceded by two new lines does that string become a delimiter.

Consider the following example:

Loop = String, &

T, &

“^^***”, &

$Src, CASE_HISTORY$

If $Src, CASE_HISTORY$ contains the following text:

*** CASE OPEN 2011/08/01 sup1


The customer called complaining of slow response time. This

generally happens for a period of an hour across his lunch.

*** CASE NOTES 2011/08/02 sup1

Ran the tracert to his server when he experienced the slowness.

*** tracert output attached

*** CASE TRANSFERED 2011/08/02 sup-net

*** CASE CLOSED 2011/08/02 sup-net

Firewall change made.

Then the loop will be executed only four times. If a single anchor were used, the loop would be executed five times.


Other Changes


Bugs Fixed

The document specified the session time out keywords inconsistently. The corrected document is included in this release. TimeOutNormal= and TimeOutLong= are the correct

spellings.

When a Descending sort was applied to a field in a query, Meta-Update would throw an error saying “Descending was not a field in the form”. This has been corrected and an abbreviation for Ascending and Descending were introduced: -A and –D.


Release 5.11 2011-08-31


Overview

The 5.11 release of Meta-Update introduces new features, enhancements to the script debugger, and corrects some customer discovered issues.




Release Number 5.11 Release Date 2011-August-31 Platforms Windows, Solaris ARS API Libraries 7.6.04, 7.6.03, 7.5, 7.1




Keyword Added Usage

Variable Target Fields assignments

When assigning to ARS fields the field name can itself be a reference.

This allows assigning fields based on a configuration file or form.

New reference command evaluating references for the Tag and Field

A new form of Reference command is introduced that allows you to evaluate references as a Tag and Field pair and get the value of that field.

Update = Tag This form of Update= is used to avoid an ARS query when the update Tag references a retrieved ARS record at the time that the Update= is executed.

No ARS query is performed. If the Tag was loaded by a previous section, it is always reread – if possible.

If a re-read is not possible (because the Tag is of a Join form), the Tag will be released and can no longer be referenced.

In this case, an AssignPost can be used to reload the Tag.

File Delimiters may be references

For both input and output files, the delimiter character can be specified as a constant or a reference string.


Loop = String enhancements.

Delimiters may be references and strings.

This release introduces the concept of a Loop = String delimiter that can be larger than a single character. It also allows you to specify the delimiter as a string reference.

Regular expression assignments field section names may be references

This release allows you to code a reference for the field section in a regex reference command. This section, once dereferenced, must exist. It allows you to have differing field interpretations on the same fields.

Variable Target Fields assignments

When assigning values to fields of ARS records or CSV fields, it is now possible to use a string reference for the field name on the right hand side of the assignment.

In the following example, the field “Summary” will be assigned a value.

@Cmd = Ref, V, fld, “Summary”

$V, fld$ = “some value”

New reference command evaluating references for the Tag and Field

A new Reference command is supported to allow assignments to variables when the Tag or field name is itself in a variable.

@Cmd = Ref, V, fld, “Summary”

@Cmd = Ref, V, val, @val, Src, $V, fld$

In the above example, the value of $Src, Summary$ will be assigned to V, val.

Using these features, it is possible to process configuration files containing field names as values.

Update = Tag enhancements.

Update = Tag is now enhanced so that any Tag that is an ARS record can be updated in

any launched section.

This is no longer restricted to the case of a Query in the same section.

Any Tag can be updated, whether loaded from a Query, LoadQ, or LookUp.

This avoids an unnecessary query to determine the update record.


If the Tag being updated is loaded through any means other than a Query in the same section the record referenced in the tag is automatically reloaded.

If the section containing the Update=Tag also uses a Query= that specifies the same Tag, and there are no Launched sections, then the updated record will not be automatically reloaded. If there are sections to be Launched, then the record will automatically be reloaded.

If the Tag referenced is from a Join form, to automatic reloading is possible no matter where the Tag was loaded. In this case it is advisable to issue a LoadQ to reload the Tag in an AssignPost section.

File Delimiters may be references

The delimiter specified in the Type= keyword may be a reference which evaluates to a single character.

This allows a parameter driven approach to deciding to use commas or semi-colons as a CSV separator as used by Excel in different locals.

Loop = String enhancements

Loop = String, Tag is now enhanced so that the delimiter specified may be a reference

and can be more than one character long.

There are two types of string loop delimiters.

When a single character is used as a delimiter, the string is broken into a set of substrings that are iterated through. The single character delimiter is not part of any of the substrings.

Multiple-character delimiters can be anchored to the beginning or end of a line are returned with the substring expanded. If the evaluated delimiter begins with “^” then it must be immediately prefixed by a new line or the beginning of the string to match. If it ends in “$” then it must be immediately followed by a new line or the end of the string.


Other Changes

The Meta-Update debugger has been enhanced to provide a better user experience.

The List command in debugging now “remembers” where you were and can be used to sequence through the complete source.

When a Breakpoint is taken, the next list command without a line number or section name starts at the breakpoint.

The Debugging Help text has been expanded and clarified.


Bugs Fixed

The construct, @if(0), returned true. This bug manifested itself in any condition without a relational operator when the evaluated substitution returned an integer with the value 0. This bug was introduced in 5.00 and has been corrected.

A script line number was not displayed when an ARS filter caused an error to an Update or Create operation.

5.0 introduced a bug where a section with a Query= and Update= for that returned query records caused a script error message. This has been fixed and superseded by the new Update= facility.


Release 5.00 2011-06-11


Overview

The 5.00 release of Meta-Update introduces significant performance improvements, an enhanced Debugger, new features, and bug fixes.

It is also the first release to be compiled against the ARS 7.6.03 API libraries adding new supported keywords and AR_INFO values.

Caching of ARS and SQL records is supported in LookUp sections. To specify that caching is to be used, a Cache statement is introduced in a LookUp section. Caching records obviates the need to query ARS for records once retrieved significantly increasing performance.

The performance of Query iterations is enhanced automatically. No changes to scripts are needed. Records returned from a Query are retrieved from ARS in batches of 100 again significantly reducing the number of ARS Server calls in a Meta-Update job.

Additionally, the maximum number of Query results (an ARS server configuration) is ignored unless a maximum is specified.



Release Number 5.00 Release Date 2011-06-11 Platforms Windows

Solaris ARS API Libraries 7.6.04, 7.6.03, 7.5, 7.1




Keyword Added Usage

Cache Used in LookUp sections. See below for summary information. See the Meta-Update User’s Guide for more information.

@Cmd = Break Sets a script assignment Break Point triggered only if

debugging. Case title A new Case option is added to the field formats. Case

title causes all letters separated by white space to begin with an upper case letter and to continue with lower case letters.

LookUp sections may now include the Cache= keyword. If a LookUp does not include the Cache= keyword, no record caching is done and the LookUp section behaves as before.

When the Cache= keyword is coded in a LookUp, the string value passed to the LookUp must uniquely identify a LookUp record or row. The Cache stores the LookUp string and the record or row returned by that string. If that string is found in the cache, no query is actually performed with the LookUp section behaving as though the Query was performed and the cached record is returned in the LookUp Query or QuerySql tag.

Cache= may specify an integer where 0 means an unlimited LookUp cache and a non-zero integer represents a cache with a fixed number of elements.

The Cache= keyword is used for LookUp sections containing Query= and QuerySql= keywords. Only ARS and SQL records are cached. The keyword is ignored for File= and list LookUp section.

Please see the User’s Guide for more details on the LookUp Cache facility.

Query iterations are enhanced automatically. No changes to scripts are needed.

Records returned from a Query are retrieved from ARS in batches of 100 again significantly reducing the number of ARS Server calls in a Meta-Update job by a factor of 100.

Conditional Break points may be coded in a script. These have no effect when not debugging. When debugging, if the Break Condition is met, a debugger Break will be taken before the next assignment section. These Break points cannot be disabled with the debugger.




$ \$env-var $ The Tag ENV is set to all environment variables. Scripts will need to be changed to reference $ ENV, env-var $

$ 001 $ The Tag Arg is set with the fields named in the

[Main] ArgNm keyword containing the values of

passed arguments. Arguments not passed are set to $NULL$

The Tag “ENV” contains the environment variables set when Meta-Update starts.

When you assign a value to an environment variable, the Meta-Update process’ environment is changed to reflect that assignment. Any spawned client processes will have the changed environment variables. When Meta-Update completes, its parent environment does not change.

Arguments in scripts are named by using the [Main] ArgNm keyword. To reference an

argument, the Arg tag is used.


Other Changes

Three new utilities are bundled with Meta-Update. These are:

Utility Function

Meta-Query SthMqry.exe

Issues ARS and SQL queries on the command line and prepares the output as text or CSV files. No SQL client is needed.

Meta-Schema SthMsch.exe

Produces text and CSV files of field in ARS schemas. Meta-Delete SthMdel.exe

Deletes records in an ARS schema based on the given query.

Each of the above utilities will give a synopsis when executed with no arguments. These utilities are licensed separately. The generated license command file, SthLic.cmd, included with your Meta-Update licenses, sets the license keys for these utilities in the current command box environment.


Bugs Fixed

Attachments from Join forms containing a field named “1” were not retrievable.

Field formats containing “lf nt” and which were used to convert data for ARS input were incorrectly adding <cr><lf> characters. ARS always stores line feeds only in its field values. This format spec is ignored if inconsistent with what ARS stores internally. When used for output files, no changes have been made.

When debugging, a print for a complete SQL row Tag would not show the fields or values of that SQL row. Individual field values could be printed.


181

software tool house inc meta-update€¦ · this document is intended for remedy ars administrators...

Documents