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'' 

1. -xmlfilename XML source file if xml2marc; XML result file if 'marc2xml –workdir optional; if specified, cd'' to this directory when cmx starts

1. -xslfilename optional; if specified, an XSL stylesheet to apply

1. -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
xslfilename="C:\Documents and Settings\Richard\My Documents\MarcReport\Stylesheets\marc21slim2rdfdc.xsl"
showprogress=false

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 then 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 This software may be used without registration so long as: 1) MARC Report is installed on the computer where it is being used 2) the cmx executable is located in the same folder as the MARC Report executable