The AR370 Archive Utility

Using the AR370 Archive Utility under CMS

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

AR370 cmds [posname] arcname [fname...]

The cmds argument must be specified and consists of an optional hyphen ( - ), followed by one of the command characters d , m , r , x , or t . (t may be specified in combination with any other command.) Optionally, you can concatenate the command character with one or more of the command modifier characters a , b , e , f , j , q , or v . The command and command modifier characters are described later in this section.

The optional posname argument specifies the name of a specific archive member and is required only if one of the relative positioning command modifiers is specified.

The arcname argument specifies the archive fileid and must be present. The default filetype is A . If filetype is specified, it must be joined to the filename with a period (.). The default filemode is *. If a filemode is specified it must also be joined to the filetype with a period (.).

Each fname argument specifies the fileid of a file to be added or replaced or the name of an archive member to be manipulated. When used to specify fileids, the filename and filetype must be joined with a period (.). The default filemode is *. If a filemode is specified, it must also be joined to the filetype with a period (.). Member names must be specified exactly as they appear in the archive. When a file is added or replaced in the archive, the input archive member name is the filename.filetype translated to upper case.

One common use of the AR370 archive utility is to replace or add files to an archive. In the following example, the utility is invoked to replace the members RUN.TEXT and WALK.TEXT in the AR370 archive named ZOOM A, and verbose output is requested.

AR370 RV ZOOM RUN.TEXT WALK.TEXT

If either RUN.TEXT or WALK.TEXT does not exist in the ZOOM archive, they are added to the archive by the r command character.

When performing an add or replace, the CMS wildcard character, an asterisk (*), may be used in the filename or filetype for CMS style pattern matching; that is, all files matching the pattern are added or replaced. If you need a member name other than the filename, you can use the following syntax:

filename.filetype.filemode=membername

All of the filename, filetype, and filemode must be specified, and wildcards cannot be used. The new membername may be any name, but it is strongly recommended that it be a valid CMS filename, as members whose names are not valid CMS filenames are difficult to manipulate with the AR370 utility. Here is an example of the use of replace-as:

AR370 R MYLIB THIS.TEXT.A=THAT.OBJECT

This command stores the file THIS.TEXT.A in the archive MYLIB with member name THAT.OBJECT.

Command Characters

The following command characters are recognized:

d deletes the specified members from the archive.

m moves the specified members. By default, the members are moved to the end of the archive. If an optional positioning character ( a or b ) is used, the posname argument must be present to specify that the named members are to be placed after ( a ) or before ( b ) posname. Note that the members are moved in the order of their appearance in the archive, not in the order specified on the command line. This means that when a number of members are moved, they remain in the same order relative to each other as before the move.

r replaces the specified files in the archive, creating new members for any that are not already present. If an optional positioning character ( a or b ) is used, the posname argument must be present to specify that the new members are to be placed after ( a ) or before ( b ) posname. In the absence of a positioning character, new members are appended at the end. When the r command character is used, the AR370 archive utility creates an archive file if it does not already exist. If no files are specified by fname arguments, the utility creates an empty archive.

t types a description of the contents of the archive. If no member names are specified, all members in the archive are described by name. If any member names are specified, information appears about those members only. Additional information is produced when either the ( v ) or ( e ) command modifiers is specified.

x extracts the named archive members. If no names are specified, all members of the archive are extracted. The member name is used as the name of each extract output file. The extract command does not alter or delete entries from the library.

Optional Modifier Characters

The following optional modifier characters are recognized:

a After: Positions the members to be moved or replaced after the member specified by the posname argument. If you specify a , you must specify posname.

b Before: Positions the members to be moved or replaced before the member specified by the posname argument. If you specify b , you must specify posname.

e Enumerate: Lists the defined symbols for the members specified for the type command. This modifier is meaningful only when used with the type ( t ) command. When used with the verbose ( v ) command modifier, all defined and referenced symbols in the specified members are displayed.

f Files: On OS/390, specifies the use of a DDname prefix by the AR370 utility. Refer to the files option in Compiler Options for more information.

j Japan or uppercase: Produces all terminal output in uppercase ( japan ).

q Quick: Processes members of existing archives more quickly. This option keeps AR370 from reprocessing every member in the archive. It greatly reduces the amount of I/O needed to add, replace, delete, and move members in an archive, since no work file is used. You should use this option with care, however, because an existing library containing data could be destroyed if space in the data set runs out. Prior to using AR370 with the q option, it is recommended that you back up the archive so that you will not lose your data in the event that the original data set is destroyed.
The q option causes the member order to be maintained only in the symbol table. This avoids the I/O needed to reposition the actual objects within the archive. Only the order of members in the symbol table is relevant to the linker. Therefore, the order of the actual object files in the archive does not always have to be maintained. If an archive has been modified by AR370 and is subsequently changed without the q option, the actual order of the objects within the archive is changed to match the order of the members in the symbol table.

v Verbose: When used with the type ( t ) command, the v command modifier produces a long listing of information for each specified member in the form of name, date, size, and number of symbols. If no members are specified, a listing is produced for all members in the archive.
When used with the d , m , or x operations, the v modifier causes the AR370 archive utility to print each command operation character and the member name associated with that operation. For the r operation, the AR370 archive utility shows an a if it adds a new file or an r if it replaces an existing member. The verbose modifier also produces the AR370 archive utility's title and copyright notice.

y Yes: List the mangled name along with the demangled name. The y modifier is meaningful only when used with the e (enumerate) optional modifier.

Combinations of command and command modifier characters

Only the combinations of commands and command modifiers shown in the following table are meaningful.

Command and Command Modifier Combinations
Command Accepted Modifiers and Commands

d e, f, j, q, t, v

m e, f, j, q, t, v and a | b

r e, f, j, q, t, v and a | b

t d, e, f, j, m, r, v, x

x e, f, j, t, v

***Command and Command Modifier Combinations***
Command	Accepted Modifiers and Commands
`d`	`e, f, j, q, t, v`
`m`	`e, f, j, q, t, v` and `a \| b`
`r`	`e, f, j, q, t, v` and `a \| b`
`t`	`d, e, f, j, m, r, v, x`
`x`	`e, f, j, t, v`

Chapter Contents
Previous
Next
Top of Page

`d`	deletes the specified members from the archive.
`m`	moves the specified members. By default, the members are moved to the end of the archive. If an optional positioning character ( `a` or `b` ) is used, the posname argument must be present to specify that the named members are to be placed after ( `a` ) or before ( `b` ) posname. Note that the members are moved in the order of their appearance in the archive, not in the order specified on the command line. This means that when a number of members are moved, they remain in the same order relative to each other as before the move.
`r`	replaces the specified files in the archive, creating new members for any that are not already present. If an optional positioning character ( `a` or `b` ) is used, the posname argument must be present to specify that the new members are to be placed after ( `a` ) or before ( `b` ) posname. In the absence of a positioning character, new members are appended at the end. When the `r` command character is used, the AR370 archive utility creates an archive file if it does not already exist. If no files are specified by fname arguments, the utility creates an empty archive.
`t`	types a description of the contents of the archive. If no member names are specified, all members in the archive are described by name. If any member names are specified, information appears about those members only. Additional information is produced when either the ( `v` ) or ( `e` ) command modifiers is specified.
`x`	extracts the named archive members. If no names are specified, all members of the archive are extracted. The member name is used as the name of each extract output file. The extract command does not alter or delete entries from the library.

`a`	After: Positions the members to be moved or replaced after the member specified by the posname argument. If you specify `a` , you must specify posname.
`b`	Before: Positions the members to be moved or replaced before the member specified by the posname argument. If you specify `b` , you must specify posname.
`e`	Enumerate: Lists the defined symbols for the members specified for the type command. This modifier is meaningful only when used with the type ( `t` ) command. When used with the verbose ( `v` ) command modifier, all defined and referenced symbols in the specified members are displayed.
`f`	Files: On OS/390, specifies the use of a DDname prefix by the AR370 utility. Refer to the `files` option in Compiler Options for more information.
`j`	Japan or uppercase: Produces all terminal output in uppercase ( `japan` ).
`q`	Quick: Processes members of existing archives more quickly. This option keeps AR370 from reprocessing every member in the archive. It greatly reduces the amount of I/O needed to add, replace, delete, and move members in an archive, since no work file is used. You should use this option with care, however, because an existing library containing data could be destroyed if space in the data set runs out. Prior to using AR370 with the `q` option, it is recommended that you back up the archive so that you will not lose your data in the event that the original data set is destroyed. The `q` option causes the member order to be maintained only in the symbol table. This avoids the I/O needed to reposition the actual objects within the archive. Only the order of members in the symbol table is relevant to the linker. Therefore, the order of the actual object files in the archive does not always have to be maintained. If an archive has been modified by AR370 and is subsequently changed without the `q` option, the actual order of the objects within the archive is changed to match the order of the members in the symbol table.
`v`	Verbose: When used with the type ( `t` ) command, the `v` command modifier produces a long listing of information for each specified member in the form of name, date, size, and number of symbols. If no members are specified, a listing is produced for all members in the archive. When used with the `d` , `m` , or `x` operations, the `v` modifier causes the AR370 archive utility to print each command operation character and the member name associated with that operation. For the `r` operation, the AR370 archive utility shows an `a` if it adds a new file or an `r` if it replaces an existing member. The verbose modifier also produces the AR370 archive utility's title and copyright notice.
`y`	Yes: List the mangled name along with the demangled name. The `y` modifier is meaningful only when used with the `e` (`enumerate`) optional modifier.