ar2updte and updte2ar Utilities

Introduction

The utilities ar2updte and updte2ar transform an ar370 archive into a file which is suitable for input to the IBM IEBUPDTE utility, and vice versa. These utilities can be useful for converting an existing object code PDS into an ar370 archive and for creating an MVS PDS from an existing archive.

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 MVS 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-MVS 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 that the case of option characters is not significant, but that case is significant for most option arguments.

The following options are recognized by the ar2updte utility:

TABLE 29. 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" on       |
|         | page 105 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:

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.

ar2updte Diagnostics

The following diagnostic message 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 can not 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. Can not 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. Can not 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.

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 MVS 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 MVS card-image partitioned data set using the MVS SAS System's PROC SOURCE. 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.

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.

updte2ar Syntax

The updte2ar utility is invoked with the following command:

  updte2ar [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 proper by white space, but need not be. Note that the case of option characters is not significant, but that case is significant for most option arguments.

The following options are recognized by the updte2ar utility:

TABLE 30. updte2ar Options

-------------------------------------------------------------------------------------
| Option     | Description                                                          |
=====================================================================================
| -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 will have            |
|            | the same linking characteristics as an archive produced              |
|            | directly with ar370. If -s is omitted, then the archive              |
|            | symbol table will reference only the member names and                |
|            | aliases referenced by ./ control statements in the input file. An    |
|            | archive produced without -s will have 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.

Examples

The following examples show typical updte2ar command lines.

 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 testlib.a
Create a new archive named testlib3.a using the IEBUPDTE input format file named test.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.

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.

 003 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 composed of 80-byte records.
 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: 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.
 007 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 in the command line. Be sure the command line is formatted correctly.
 008 Argument following -a cannot be longer than 8 characters. 
  Correct usage: updte2ar [-l] [-s] [-a ending] [-t c1:s1 [-t c2:s2...]] 
   filein fileout
The -a option specified a suffix that was more than 8 characters.
 010 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.
 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: 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.
 019 Invalid name for symbol, "symbolname" specified in a SYMDEF control 
 statement.
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.
 020 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.
 021 Unable to write object to ar370 archive 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.
 022 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.
 023 Unable to open IEBUPDTE file, "filename".
An attempt to open the file "filename" failed. Check all input files for validity and integrity.
 024 Unable to open ar370 archive file, "filename".
An attempt to open the file "filename" failed. There may be a file system problem or failure.
 025 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 composed of 80-byte records. Check the input file for validity and integrity.
 026 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 be the cause. Make sure the space available for the output file is large enough to hold all the output.
 027 Error in seeking to offset in file, "filename".
An error occurred when attempting to position to an offset in the file, "filename".