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 which are not acceptable as member names to IEBUPDTE. ar2updte offers a translation feature which 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.

CAUTION:: ar370 archives are created and maintained only by ar370 and updte2ar . The internal structures and the data these files contain are in EBCDIC format. ar370 archives should never be modified or accessed in any way, other than through ar370 . Similarly, IEBUPDTE input format data files are created only by IEBUPDTE and ar2updte . The internal structures and the data these files contain are also in EBCDIC.

ar2updte Syntax

The ar2updte utility is invoked with the following command:

ar2updte [options...] infile outfile

The options portion of the command line 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 can be separated from the option by white space, but need not be.

Note: The case of option characters is not significant, but case is significant for most option arguments. [cautionend]
The following options are recognized by the ar2updte utility:

ar2updte Options
Option Description

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

-x
specifies that no character translations will be applied to the member names during the archive to IEBUPDTE conversion. 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.

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

*ar2updte* Options
Option	Description
`-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.
`-x`	specifies that no character translations will be applied to the member names during the archive to IEBUPDTE conversion. 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.
	Unless `-x` is specified, default member translation rules are used. See the section Default Member Translation Rules for details.

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.

Examples

The following examples show typical ar2updte command lines.

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 then convert all x's to the dollar sign.

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 the at symbol (@).
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 the pound sign (#), 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.

001 Error opening input file, "[filename]".

An attempt to open the file filename failed. Check all input files for validity and integrity.

002 Error opening output file, "[filename]".

An attempt to open the file filename failed. There may be a file system problem or failure.

003 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.

004 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.

006 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.

007 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.

009 Option -"option" needs to be followed by an argument.

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

The -"option" option must be followed by an argument.

010 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.

011 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.

012 Unable to identify ar370 archive, "[filename]".

An ar370 archive can not be located from the filename specified in the command line. The input file in the command line must be a valid archive file.

013 Error reading ar370 archive members in "[filename]".

An error occurred when attempting to read the members in the archive 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.

014 "[filename]" is not an ar370 archive.

This file filename is not an archive. It cannot be processed as an archive. The input for ar2updte must be an archive created by ar370 or udpte2ar .

015 File is not recognized as an archive. Can not process file"[filename]".

A file, filename, specified as an archive does not contain a valid archive header. Data read from the file is checked to verify it is an archive. If the archive has been modified by any utility other than ar370 or updte2ar data could be lost or corrupted.

016 Archive format unrecognized. Cannot process file "[filename]".

The file, filename, is an archive, but it contains an error in the symbol table. If the archive has been modified by any utility other than ar370 or updte2ar , data could be lost or corrupted.

017 Archive format unrecognized. Cannot process file "[filename]".

The file, filename, is an archive, but it contains an error in the string table. If the archive has been modified by any utility other than ar370 or updte2ar data could be lost or corrupted.

018 Error writing to output file, "[filename]".

An attempt to write one or more items to the output file 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.

028 The number of aliases for the member "[member name]" exceeds 16.

The member, member name, is defined with more than 16 aliases. All of these aliases have been included in the resulting IEBUPDTE input format data file. However, IEBUPDTE cannot process members defined with more than 16 aliases. The excess alias cards should be removed before running IEBUPDTE.

029 Duplicate member name "[member name]" has been generated in output.

member name is the identifier for more than one member in the archive. This name has been included more than once in the resulting IEBUPDTE input format file. However, the name of each PDS member must be unique, so before a partitioned data set is created, the IEBUPDTE input format file should be edited, or the archive should be manipulated using ar370 so that all members have unique names.

030 Symbol "[symbol name]" was previously defined and has been omitted from output.

Aliases are created for all symbols defined in each member of the archive. A symbol definition for symbol name appears in more than one member of the archive. Since PDS member and alias names must be unique, symbols that conflict with previous definitions have been omitted from the output. Linking characteristics of the partitioned data set should still be preserved since only the first symbol defined by an archive is linked when using the archive.

Chapter Contents
Previous
Next
Top of Page