Command-line MARC XML utility

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

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 executables

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