This page describes 'cmx.exe' (convert marc xml), a command-line version of MARC Report's MARC/XML utilities. This utility supports the same features as the 'windows' versions implemented in MARC Report, including stylesheets.
CMX is distributed with all copies of MARC Report, beginning with version 236.
Requirements
Note: the above requirements will also apply to 'X-Cat' (our Xml aware concatenation utility), currently in development.
Updates
CMX may be updated from time to time. CMX may also become out of date with MARC Report's MARCXML module. MARC Report subscribers should follow the usual update procedures. Non-subscribers should check the link that follows for updates.
Manual
The 'manual' for CMX is the file called 'cmxhelp.txt' which will be found in the MARC Report 'Help' folder. A copy of that manual follows.
NAME
cmx - command-line version of MARC Report's MARCXML utilities
RUNNING IN WINDOWS
The file cmx.exe is installed with MARC Report. This .exe file must remain in
the MARC Report program folder, but you can create a shortcut to it and
relocate the shortcut wherever you desire. Or, create a shortcut for a command
prompt, and then set it to open in the MARC Report folder.
SYNOPSIS
cmx [supply the name of a configuration file]
cmx [supply the parameters on the command line]
For examples, see the section EXAMPLES below.
DESCRIPTION
A command-line interface to the 'MARC21 To Xml' and 'Xml To MARC21' utilities
that are distributed with MARC Report. Records are read from the specified
source file, converted, then written to the specified results file.
By default, MARC21 records are converted to MARCXML records; and MARCXML
records are converted to MARC21 records. (For definitions of MARC21 and
MARCXML, visit the MARC Standards site at: http://www.loc.gov/marc/).
An option exists (see the OPTIONS section below) to supply the name of a XSL
stylesheet as a parameter. In this case, MARC21 records are converted to
MARCXML, and then the MARCXML is 'transformed' by the stylesheet; and, in the
other direction, the XML records are transformed by the stylesheet to MARCXML,
which is then converted to MARC21. Thus, any stylesheet used with the program
must support MARCXML.
Most stylesheets supported by the program are distributed with the MARC Report
installation; these stylesheets will be copied to a folder named 'Stylesheets'
in the user's 'My Documents\MarcReport' folder the first time MARC Report
runs. These stylesheets are also freely available from the Library of
Congress's MARCXML page: http://www.loc.gov/standards/marcxml.
OPTIONS
There are two ways to use cmx.
First, supply all parameters in a config file, and then simply issue the
command:
cmx configfile
on the command line, where 'configfile' is a plain text file that contains
the parameters to be used in the conversion. A config file may have any valid
windows filename; we recommend using the .cfg extension. When parameters are
given in a config file, each parameter must be given at the beginning of a new
line.
The second mode of usage is to supply all parameters to the program on the
command-line itself:
cmx --option1=something --option2=something --option3="something else"
The parameters follow the convention of name/value pairs, where the parameter
name is followed by '=', then by the parameter value, with no intervening
blank spaces. When parameters are given on the command-line, they must begin
with '--', and there can be no line breaks in the command. The opening '--'
is optional within a config file. When parameter values (such as filenames)
include blank spaces, the value must be enclosed in quotation marks (again,
this is not necessary when using a config file).
The list of supported parameters follows. Parameter names are not
case-sensitive, but case is observed in the value portion. With the exception
of '--help', which must occur as the only parameter, the order of parameters
is not important.
--help display this parameter list and exit
--conversiontype required; either 'marc2xml' or 'xml2marc'
--marcfilename MARC source file if marc2xml; MARC result file if xml2marc
--xmlfilename XML source file if xml2marc; XML result file if marc2xml
--workdir optional; if specified, cd to this directory when cmx starts
--xslfilename optional; if specified, an XSL stylesheet to apply
--showprogress optional; true/false: display/suppress a windows progress bar
Parameter names can be shortened to the first four letters of the above; this
might be useful on the command-line.
EXAMPLES
If using a config file:
cmx mymarc2xml.cfg
--where mymarc2xml.cfg contains the following lines:
conversiontype=marc2xml
marcfilename=d:\marc\extract-110211.mrc
xmlfilename=e:\work\extract-dc.xml
showprogress=false
xslfilename="C:\Documents and Settings\Richard\My Documents\MarcReport\Stylesheets\marc21slim2rdfdc.xsl"
The command-line version of the above is:
cmx --conversion=marc2xml --marcfilename=d:\marc\extract-110211.mrc --xmlfilename=e:\work\extract-dc.xml --xslfilename="C:\Documents and Settings\Richard\My Documents\MarcReport\Stylesheets\marc21slim2rdfdc.xsl" --showprogress=false
Or, using the shortened parameter names:
cmx --conv=marc2xml --marc=d:\marc\extract-110211.mrc --xml=e:\work\extract-dc.xml --xsl="C:\Documents and Settings\Richard\My Documents\MarcReport\Stylesheets\marc21slim2rdfdc.xsl" --show=false
Both examples above convert the MARC records in 'extract-110211.mrc' to
Dublin Core using the 'marc21slim2rdfdc.xsl' stylesheet, without displaying
a progress bar.
In some cases, parameter specification might be made easier by setting a
working directory:
cmx --workdir=d:\marc --conversion=marc2xml --marcfilename=mondays.mrc --xmlfilename=mondays.xml
In this case, the input file must reside in the 'd:\marc' folder, and the
output file will be written there.
Parameter names may also be shortened to their first four letters; thus:
cmx --work=d:\marc --conv=marc2xml --marc=mondays.mrc --xml=mondays.xml --show=false
is the same as the previous example, with the exception of suppressing the
progress bar.
Given two config files named mymarc2xml.cfg and myxml2marc.cfg, containing
these lines:
(mymarc2xml.cfg)
conversiontype=marc2xml
marcfilename=d:\marc\extract-110301.mrc
xmlfilename=e:\work\extract-110301.xml
showprogress=false
(myxml2marc.cfg)
conversiontype=xml2marc
marcfilename=d:\marc\roundtrip.mrc
xmlfilename=e:\work\extract-110301.xml
showprogress=false
--it would be possible to convert a file of MARC records to MARCXML and then
back to MARC by adding the following two lines to a windows .bat file:
cmx mymarc2xml.cfg
cmx myxml2marc.cfg
One might insert custom scripts into the batch processing stream as follows:
cmx mymarc2xml.cfg
someScriptThatTweaksText e:\work\extract-110301.xml e:\work\extract-110301-r.xml
cmx myxml2marc.cfg
Care must be taken that the custom script output file is coordinated with the
input filename expected by the next cmx job. In the example above, we would
need to set the 'xmlfilename' parameter of the second cmx job
to 'e:\work\extract-110301-r.xml'.
If queueing cmx jobs in a .bat file, it might be useful to check the result
of each cmx job before going on to the next. A simple example follows:
cmx mymarc2xml.cfg
IF ERRORLEVEL 1 GOTO ExitErrorLabel
cmx myxml2marc.cfg
IF ERRORLEVEL 1 GOTO ExitErrorLabel
GOTO ExitOk
:ExitErrorLabel
rem Script terminated on error
:ExitOk
The long path to the stylesheet folder may prove cumbersome for command-line
users. Such users may wish create an environment variable for that folder.
For example, after we set 'XSLPATH' to the stylesheet folder, we may use:
cmx --conv=marc2xml --marc=d:\marc\extract-110211.mrc --xml=e:\work\extract-dc.xml --xsl="%XSLPATH%marc21slim2rdfdc.xsl"
Finally, note that the above examples all assume that cmx is being run from
the MARC Report installation directory, or that this directory is part of the
windows PATH variable. If the latter is not the case, the exe will have to
be called as follows:
"C:\Program Files\TMQ\MARC Report\cmx.exe" [parameters or config file]
(assuming MARC Report is installed in the default folder). If one is familiar
with the DOS shell, it might be possible to work around this. For example,
in the hypothetical folder 'F:\mx-work' we create a file called 'cmx.bat'
that contains these lines:
@echo off
"C:\Program Files\TMQ\MARC Report\cmx.exe" %1
We might now type:
F:\xmlwork> cmx my.cfg
to start the program.
NOTES
The XML support used by the program is supplied by MSXML. In the current
version, the default is MSXML 4.0, with a fallback to MSXML 3.0
The two modes of usage are mutually exclusive. For example, one cannot say:
cmx --workdir=C:\work mymarc2xml.cfg
DIAGNOSTICS
The application exits with a status of 0 on success, and outputs the phrase
'conversion results: [n]' to the console, where 'n' is a count of records
successfully processed; the application exits with a status of 1 if an error
occurs, in which case the phrase 'conversion results:' may be followed by an
error code.
AUTHOR
Copyright 2011, TMQ, Inc.
REQUIREMENTS
1) MARC Report must be installed on the computer where cmx is being used
2) the cmx executable is located in the same folder as the MARC Report executable