The AR2UPDTE and UPDTE2AR Utilities

AR2UPDTE Utility

AR2UPDTE is a utility program that converts an AR370 archive to an IEBUPDTE input format data file. AR2UPDTE reads in the archive and creates a new file of IEBUPDTE input format data. The AR2UPDTE output file can be used as input to the IBM IEBUPDTE utility to build an OS/390 partitioned data set that approximates the AR370 archive provided as input to AR2UPDTE. Together AR2UPDTE and IEBUPDTE can be used to copy every member of an AR370 format archive into a corresponding member of a partitioned data set.

Archives built on a non-OS/390 system may have member names that are not acceptable as member names to IEBUPDTE. AR2UPDTE offers a translation feature that permits the user to specify how archive member names should be translated to PDS member names. Default translation rules are always applied unless the user specifies that no translation should be performed.

Using AR2UPDTE under CMS

Under CMS, the AR2UPDTE utility is invoked directly with the following command:

ar2updte [options] infile outfile

options specifies one or more options, each of which is a single character preceded by a hyphen (-). Some options (for example, -t ) must be followed by an option argument. The argument may be separated from the option by white space, but this is not a requirement. Note that the case of option characters is not significant, but that case is significant for most option arguments.

The following options are recognized:

-t c : s

specifies a translation rule to be used by AR2UPDTE when deriving a PDS member name from an archive member name. More than one -t option can be specified. The option argument c : s indicates that if the string ' c ' (which can be longer than a single character) occurs in an archive member name, it is to be replaced by the string ' s ' in the output PDS member name.

Unless -x is specified, default member translation rules are used. See the section Default Member Translation Rules for details.

-x

specifies that no character translations will be applied to the member names during the archive to IEBUPDTE conversion. The -x argument is optional. The -x option can be used to preserve the original input archive's member names, even if they do not conform to the IEBUPDTE rules for acceptable PDS member names. The resulting output may not be usable as input to IEBUPDTE, but it can be used as input to UPDTE2AR to build a copy of the input archive.

The infile and outfile arguments must be specified. The infile argument specifies the archive file identifier. It must be a valid archive. The outfile argument specifies the file identifier of the resulting output file, which is in IEBUPDTE input format.

Note: Under CMS, the default filetype for the infile argument is A. If filetype is specified, it must be joined to the filename with a period (.). The default filemode for the infile argument is *. The outfile argument specifies the file identifier of the resulting output file which is in IEBUPDTE input format. The default filetype for the outfile argument is IEBUPDTE. If filetype is specified, it must be joined to the filename with a period (.). The default filemode for the outfile argument is *. [cautionend]

The following examples show typical AR2UPDTE command lines under CMS:

ar2updte testlib.a test.iebupdte: Create a new IEBUPDTE input format file named test.iebupdte from the archive testlib.a .
ar2updte -x testlib.a test2.iebupdte: Create a new IEBUPDTE input format file named test2.iebupdte from the archive testlib.a without performing any translations on the names of object members in the archive.
ar2updte -t ?:QU -t x:$ testlib.a test3.iebupdte: Create a new IEBUPDTE input format file named test3.iebupdte from the archive testlib.a . Convert all question marks to the letters QU, and convert all x's to the dollar sign.

Using AR2UPDTE in TSO

This section describes calling AR2UPDTE in TSO using the TSO CALL command. Use the following syntax:

CALL 'library.name(AR2UPDTE)' '[options] infile outfile' ASIS

Here, library.name is the name of the library containing AR2UPDTE. Consult your SAS/C Software Representative for C compiler products for the correct library name.

See the section Using AR2UPDTE under CMS for a description of the options. Note that infile and outfile will be interpreted as DDnames unless a SAS/C style prefix is used.

The following example shows a typical use of AR2UPDTE in TSO:

CALL 'SASC.LOAD(AR2UPDTE)' 'tso:testlib.a tso:testpds.data' ASIS

Using AR2UPDTE under OS/390 Batch

This section describes how to run AR2UPDTE under OS/390 batch using the AR2UPDTE cataloged procedure.

The AR2UPDTE cataloged procedure is used to execute AR2UPDTE under OS/390 batch. You must provide a SYSARLIB DD statement defining the input AR370 archive and a SYSPUNCH DD statement defining the output file. The output file must be defined to have fixed-record format with 80-byte records. If you need to pass special AR2UPDTE options, specify the OPTS keyword in the EXEC statement, as shown below. See the section Using AR2UPDTE under CMS for information on the AR2UPDTE options and their meanings.

Sample JCL for Running the AR2UPDTE Cataloged Procedure shows typical JCL for using the AR2UPDTE cataloged procedure, followed by calling IEBUPDTE to generate a PDS.


Sample JCL for Running the AR2UPDTE Cataloged Procedure



//SAMPAR2U   JOB job card information
//*------------------------------------------
--------------
//*  INVOKE AR2UPDTE FOLLOWED BY IEBUPDTE
//*
//*  REPLACE GENERIC DATA SET NAMES AS APPROPRIATE
//*------------------------------------------
--------------
//STEP1        EXEC AR2UPDTE,OPTS='options'
//U2A.SYSARLIB DD DSN=input.ar370.archive,DISP=SHR
//U2A.SYSPUNCH DD DSN=updte.format.output,DISP=(OLD,PASS)
//STEP2        EXEC PGM=IEBUPDTE,COND=(0,NE),PARM='NEW'
//SYSPRINT     DD SYSOUT=*
//SYSUT2       DD DSN=output.pds,DISP=(NEW,CATLG),UNIT=SYSDA,
//             SPACE=(your-space-values),
//             DCB=(RECFM=FB,LRECL=80,BLKSIZE=your-blksize)
//SYSIN        DD DSN=updte.format.output,DISP=OLD
//

In this example, options is any required AR2UPDTE options (for example, '-t ?:QU' ).

The AR2UPDTE procedure contains the JCL shown in Expanded JCL for AR2UPDTE.

Expanded JCL for AR2UPDTE
//AR2UPDTE PROC OPTS='' //**************************************************************** //* NAME: AR2UPDTE (AR2UPDTE) *** //* PRODUCT: SAS/C *** //* PROCEDURE: CONVERT AR370 ARCHIVE TO IEBUPDTE INPUT *** //* DOCUMENTATION: SAS/C COMPILER AND LIBRARY USER'S GUIDE *** //* FROM: SAS INSTITUTE INC., SAS CAMPUS DRIVE, CARY, NC *** //**************************************************************** //* //U2A EXEC PGM=AR2UPDTE,PARM='&OPTS DDN:SYSARLIB DDN:SYSPUNCH' //STEPLIB DD DSN=SASC.LOAD, // DISP=SHR COMPILER LIBRARY // DD DSN=SASC.LINKLIB, // DISP=SHR RUNTIME LIBRARY //SYSTERM DD SYSOUT=* //SYSPRINT DD SYSOUT=*

Default Member Translation Rules

Unless the -x option is specified, some translations are automatically performed by the AR2UPDTE utility:

If a period (.) is in a member name and it is not the first character, it is removed, and the rest of the member name is truncated (that is, MEMBER.NAME becomes MEMBER in the resulting IEBUPDTE file).
If a period (.) is the first character of a member name, it is translated to an at sign (@).
If blank ( ) is the first character of a member name and it is not a translate character, then it is translated to a dollar sign ($).
All member names are truncated to 8 characters since IEBUPDTE will not allow member names longer than 8.
All member names are uppercased.

Note: Translations specified by the user occur prior to the default translations. Interactions between the user specified translations and the default translations may cause unexpected behavior. For example, if the -t option is invoked with .:per , then the default translation which converts a leading period (.) to the at sign (@) will not occur. The leading period (.) will be converted to "per". Also, if the -t option is invoked with b:_ , then the b's will be converted to underscores (_) first and then to pound signs (#), by default. [cautionend]

AR2UPDTE Diagnostics

The following diagnostic messages are generated by the AR2UPDTE utility. Diagnostic messages from the run-time library that further describe the problem may appear in conjunction with the AR2UPDTE diagnostics.

LSCAU1 Error: opening input file, "[ filename ]".

An attempt to open the file filename failed. Under OS/390 this error occurs when the filename is a DDname and the DDname is not defined; but any file system problem or failure that might cause an open to fail could also cause this message.

LSCAU2 Error: opening output file, "[ filename ]".

An attempt to open the file filename failed. Under OS/390 this error occurs when filename is a DDname and the DDname is not defined; but any file system problem or failure that might cause an open to fail could also cause this message.

LSCAU3 Error: reading file, "[ filename ]".

An error occurred when attempting to read from the archive named filename. This diagnostic may be produced if the archive has been modified by any utility other than AR370 or UPDTE2AR; but any file system problem or failure that might cause a read to fail could also cause this message. Check all input files for validity and integrity.

LSCAU4 Error: writing file, "[ filename ]".

An attempt to write one or more items to the output file stream has been unsuccessful. Usually this is caused by having insufficient space available for all the output; but any file system problem or failure that might cause a write to fail could also be the cause. Make sure the space available for the output file is large enough to hold all the output.

LSCAU5 Error: creating CMS-style file identifier from filename, "[ filename ] ".

Files in CMS are named using a file identifier. The file identifier consists of three fields: filename, filetype, and filemode. An error occurred when attempting to create a valid CMS file identifier with the filename specified on the command line. All input and output files must have valid CMS-style file identifiers.

LSCAU6 Error: Wrong number of command line arguments.

Correct usage: ar2updte [-x | -t c1:s1 [-t c2:s2...]]
         filein fileout

The command line requires a minimum of two arguments, an input archive and an output filename.

LSCAU7 Error: loading list of translate characters.

Correct usage: ar2updte [-x | -t c1:s1 [-t c2:s2...]]
         filein fileout

The program failed while attempting to parse the options and translate characters in the command line. Be sure the command line is formatted correctly.

LSCAU9 Error: Option -t needs to be followed by an argument.

Correct usage: ar2updte [-x | -t c1:s1 [-t c2:s2...]]
         filein fileout

The -t option must be followed by an argument.

LSCAU10 Error: Unrecognized option -" option ".

Correct usage: ar2updte [-x | -t c1:s1 [-t c2:s2...]]
         filein fileout

The only valid options in AR2UPDTE are: -x and -t c : s.

LSCAU11 Error: The argument " argument " that follows the -t option must be in the form c:s where c is the string to be translated and s is the resulting string.

Correct usage: ar2updte [-x | -t c1:s1 [-t c2:s2...]]
         filein fileout

The -t option must be followed immediately with an argument in the form c : s. All strings ` c ' in the member names of the archive will then be translated to the string ` s ' in the resulting IEBUPDTE input file.

LSCAU12 Error: Unable to identify AR370 archive, "[ filename ]".