ar370
archive utility is used to maintain groups of files that are combined into a single
archive file. Normally, the ar370
archive utility is used to generate an archive containing object
files used by cool
to resolve external references.
An ar370
archive is organized as a collection of members, identified by a member name that
resembles a filename. The member names serve only to identify the members to the ar370
utility.
Otherwise, member names are not significant. For each object file contained in an ar370
archive,
the ar370
utility records the names of external symbols defined or referenced in the member
(including external objects with extended names). This allows cool
to find the member that
defines a particular symbol. No connection is required between an ar370
member name and the
external symbol names defined by the member.
Physically, each ar370
archive is composed of three parts.
TABLE 14. ar370
Components
---------------------------------------------------------------------- | Component | Contents | ====================================================================== | header | information such as the date of the last | | | modification and the release number of the | | | ar370 utility that made the modification. | ---------------------------------------------------------------------- | member archive | a copy of each file added to the library. (For | | | ar370 archives, unlike the files in a UNIX | | | directory, the order of members may be | | | significant.) | ---------------------------------------------------------------------- | symbol table | a list of each external symbol defined or | | | referred to by any member of the archive. | ----------------------------------------------------------------------
When adding or replacing members, the ar370
utility inserts a copy of each input file into the
member archive. The utility also searches the external symbol dictionary (ESD) of each input file,
creates a sorted list of ESD entries, and inserts the list in the library symbol table. The library
symbol table is used by cool
to search an archive efficiently for ESD symbols and extended
names.
CAUTION: ar370
archives are created and maintained only by ar370
. The internal
structures and the data they contain are in EBCDIC. ar370
archives should never be modified or
accessed in any way, other than through ar370
.
Note: The SAS/C Cross-Platform Compiler includes two utilities that are useful for working
with ar370
archives: ar2updte
and updte2ar
. For details, see Appendix C, "ar2updte and
updte2ar Utilities" on page 103.
ar370
archive utility is invoked directly with the following command:
The cmds argument must be specified, and consists of an optionalar370
cmds
[
posname
]
libname
[
fname...
]
-
, followed by one of the
command characters d
, m
, r
, x
or t
. (t
may be specified with any other command.) Optionally, you
can concatenate the command character with one or more of the command modifier characters a
, b
,
e
, 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 libname argument specifies the filename of the archive library and must be present. By
convention, an extension of .a
is used to identify archive library files.
Each fname argument specifies the name of a file to be added or replaced, or the name of an archive member to be manipulated. Member names must be specified exactly as they appear in the archive.
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.txt
and walk.txt
in the
ar370
archive named zoom.a
. Verbose output is requested.
ar370 rv zoom.a run.txt walk.txt
If either run.txt
or walk.txt
does not exist in the zoom.a
archive, it is added to the
archive by the r
command character.
When performing an add or replace, the name of the archive member is generally derived from
the file name. You can specify an alternate name for the archive member by following the complete
input file name with the replace-as operator `=
' and the alternate name for the archive member. For
example:
ar370 r mylib this.text.a1=that.objThis command stores the file
this.text.a1
in the archive mylib
with the member name
that.obj
.
TABLE 15. Command Characters
------------------------------------------------------------------------------------------ | Command | Description | | Character | | ========================================================================================== | 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, specifying 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) the posname member. 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 about only | | | those members appears. 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. | ------------------------------------------------------------------------------------------
TABLE 16. Modifier Characters
--------------------------------------------------------------------------------------- | Modifier | Description | | Characters | | ======================================================================================= | a | 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 | 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 symbols (defined and referenced) in | | | the specified members are displayed. | --------------------------------------------------------------------------------------- | j | Japan or uppercase: Produces all 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, we recommend that you back up the archive so that you | | | will not lose your data in the event that the original dataset is | | | destroyed. | | | | | | Note that 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 t, 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. | ---------------------------------------------------------------------------------------
TABLE 17. 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 | -----------------------------------------------