The AR2UPDTE and UPDTE2AR Utilities

UPDTE2AR Utility

The UPDTE2AR utility is a program that is used to create an AR370 archive by reading in the contents of a file in IEBUPDTE input format. The IEBUPDTE input file must contain 80-byte records in the format accepted by the OS/390 IEBUPDTE utility and described in the IBM manual MVS/DFP Utilities (SC26-4559). The file is divided into segments by IEBUPDTE "./ ADD" control records: each segment represents a single PDS member. A file can be generated in this format from an OS/390 card-image partitioned data set using the SAS System's SOURCE procedure. UPDTE2AR reads in this data and creates an AR370 archive. This archive can then be manipulated by the AR370 utility to delete, move, replace, view, or extract members.

UPDTE2AR options allow you to control the translation of PDS member names to archive member names. They also specify whether the archive's symbol table should mimic the source PDS directory or include all external symbols defined in members of the PDS.

Using UPDTE2AR under CMS

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

updte2ar [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:

-a ending appends the specified ending to the input member name to produce the output archive member name. The ending is limited to 8 characters.

-l Converts the member names to lowercase.

-s specifies that all external symbols defined in any input member are to be included in the archive symbol table. An archive produced with the -s option of UPDTE2AR has the same linking characteristics as an archive produced directly with AR370. If -s is omitted, then the archive symbol table references only the member names and aliases referenced by ./ control statements in the input file. An archive produced without -s has the linking characteristics of the source PDS.

-t c : s specifies a translation rule to be used by UPDTE2AR when deriving an archive member name from a PDS 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 input member name, it is to be replaced by the string s in the output archive member name.

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

Note: Under CMS, the default filetype for the infile argument is IEBUPDTE. 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 archive. The default filetype for the outfile argument is A. 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 UPDTE2AR command lines on CMS.

updte2ar test.iebupdte testlib.a: Create a new archive named testlib.a using the IEBUPDTE input format file named test.iebupdte .
updte2ar -t QU:? -t $:x test3.iebupdte testlib3.a: Create a new archive named testlib3.a using the IEBUPDTE input format file named test3.iebupdte . Convert all letters QU to question marks and then convert all dollar signs to x's.
updte2ar -l -a .o test.iebupdte testlib4.a: Create a new archive named testlib4.a using the IEBUPDTE input format file named test.iebupdte . Put all the member names in lowercase and append a .o to each member name. For example, the input member BUILD would be translated to the archive member build.o .

Using UPDTE2AR in TSO

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

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

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

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

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

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

Using UPDTE2AR under OS/390 Batch

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

The UPDTE2AR cataloged procedure is used to execute UPDTE2AR under OS/390 batch. You must provide a SYSIN DD statement defining the IEBUPDTE format input file and a SYSARLIB DD statement defining the output AR370 archive. If you need to pass special UPDTE2AR options, specify the OPTS keyword in the EXEC statement, as shown below. See the section Using UPDTE2AR under CMS for information on the UPDTE2AR options and their meanings.

Sample JCL for Running the UPDTE2AR Cataloged Procedure shows typical JCL for using the UPDTE2AR cataloged procedure.

Sample JCL for Running the UPDTE2AR Cataloged Procedure
//SAMPU2AR JOB job card information //*------------------------------------------ -------------- //* INVOKE UPDTE2AR //* //* REPLACE GENERIC DATA SET NAMES AS APPROPRIATE //*------------------------------------------ -------------- //STEP1 EXEC UPDTE2AR,OPTS='options' //U2A.SYSARLIB DD DSN=output.ar370.archive,DISP=OLD //U2A.SYSIN DD DSN=updte.format.input,DISP=SHR //

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

The UPDTE2AR contains the JCL shown in Expanded JCL for UPDTE2AR.

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

UPDTE2AR Diagnostics

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

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

An error occurred when attempting to read from the input file filename. Check all input files for validity and integrity. Input files should be fixed-length record format with 80-byte records.

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 under 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 out put files must have valid CMS-style file identifiers.

LSCAU6 Error: Wrong number of command-line arguments.

Correct usage: updte2ar [-l] [-s] [-a ending] [-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: updte2ar [-l] [-s] [-a ending] [-t c1:s1
         [-t c2:s2...]] filein fileout

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

LSCAU8 Error: Argument following -a cannot be longer than 8 characters.

Correct usage: updte2ar [-l] [-s] [-a ending] [-t c1:s1
         [-t c2:s2...]] file-in file-out

The -a option specified a suffix that was more than 8 characters.

LSCAU10 Error: Unrecognized option -option .

Correct usage: updte2ar [-l] [-s] [-a ending] [-t c1:s1
         [-t c2:s2...]] filein fileout

The only valid options in UPDTE2AR are: -l , -s , -a ending, -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: updte2ar [-l] [-s] [-a ending] [-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 IEBUPDTE file will then be translated to the string s in the resulting AR370 archive.

LSCAU19 Error: invalid name for symbol, " symbolname " specified in a SYMDEF control st atement.

SYMDEF symbols must be 1 to 8 characters in length. The symbol name symbolname is too long. Symbols specified via SYMDEF control statements must be at least 1 character and not more than 8 characters in length. Check the SYMDEF cards in the input object files.

LSCAU20 Error: invalid SYMDEF control card in file " filename ".

An AR370 SYMDEF control statement in the input file filename contained invalid syntax. Check the SYMDEF control statement in the specified input file to make sure it conforms to the general form and syntax of linkage editor control statements. Make sure the symbol names are between 1 and 8 characters in length.

LSCAU21 Error: Unable to write object to AR370 archive file, " filename ".

LSCAU22 Error: Encountered EOF in continued SYMDEF card in file, " filename ".

An AR370 SYMDEF control statement in the file filename is invalid. An End of File was encountered in place of the continuation of the SYMDEF card. Check the SYMDEF cards in the input file.

LSCAU23 Error: Unable to open IEBUPDTE 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.

LSCAU24 Error: Unable to open AR370 archive 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.

LSCAU25 Error: Read of input file, "[ filename ]" failed.

When attempting to read the input file named filename, UPDTE2AR was unable to read 80 bytes. The IEBUPDTE utility requires the input file to be 80-byte records, blocked or unblocked. Check the input file for validity and integrity.

LSCAU26 Error writing library header to output 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 cause this message. Make sure the space available for the output file is large enough to hold all the output.

LSCAU27 Error in seeking to offset in file, " filename ".

An error occurred when attempting to position to an offset in the file filename.

Chapter Contents
Previous
Next
Top of Page

`-a` ending	appends the specified ending to the input member name to produce the output archive member name. The ending is limited to 8 characters.
`-l`	Converts the member names to lowercase.
`-s`	specifies that all external symbols defined in any input member are to be included in the archive symbol table. An archive produced with the `-s` option of UPDTE2AR has the same linking characteristics as an archive produced directly with AR370. If `-s` is omitted, then the archive symbol table references only the member names and aliases referenced by ./ control statements in the input file. An archive produced without `-s` has the linking characteristics of the source PDS.
`-t` c `:` s	specifies a translation rule to be used by UPDTE2AR when deriving an archive member name from a PDS 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 input member name, it is to be replaced by the string s in the output archive member name.