as — Use the HLASM assembler to produce object files

Format

as
       [--option[, option] …] …
       [-a[egimrsx][=file]] …
       [-g]
       [--[no]gadata[=file]]
       [--[no]gdwarf4[=file]]
       [-moption]
       [-I name]
       [-o objectfile]
       [-d textfile]
       [-v]
       [--[no]help]
       [--[no]verbose]
       file

Description

The as command processes assembler source files and invokes the HLASM assembler to produce object files.

Options

--

Accepts all options that are accepted by HLASM. Multiple options can be specified by separating them with a comma. This style of option specification is designed to provide smooth migration for users accustomed to specifying options in JCL. For example:

--"FLAG(ALIGN),RENT"

-a[egimrsx][=file]

Instructs the assembler to produce a listing.

-ae: Instructs the assembler to produce the External Symbol Dictionary section of the assembler listing. This is equivalent to specifying: --ESD.
-ag: Instructs the assembler to produce the General Purpose Register Cross Reference section of the assembler listing. This is equivalent to specifying: --RXREF.
-ai: Instructs the assembler to copy all product information to the list data set. This is equivalent to specifying: --INFO.
-am: Instructs the assembler to produce the Macro and Copy Code Source Summary section of the assembler listing. This is equivalent to specifying: --MXREF.
-ar: Instructs the assembler to produce the Relocation Dictionary (RLD) section of the assembler listing. This is equivalent to specifying: --RLD.
-as: Instructs the assembler to produce the Ordinary Symbol and Literal Cross Reference section of the assembler listing. It also instructs the assembler to produce the un-referenced symbols defined in the CSECTs section of the assembler listing. This is equivalent to specifying: --XREF(SHORT,UNREFS).
-ax: Instructs the assembler to produce the DSECT Cross Reference section of the assembler listing. This is equivalent to specifying: --DXREF.
=file: Specifies the file name of the listing output. If you do not specify a file name, the output goes to stdout.

You may combine these options; for example, use -ams for an assembly listing with expanded macro and symbol output. The =file option, if used, must be specified last.

-g

Instructs the assembler to collect debug information. By default, the debug information is produced in DWARF Version 4 format (or --gdwarf4).

--[no]gadata[=file]

Instructs the assembler to collect associated data and write it to the associated data file. You can optionally specify the name of the output debug file. The specified name cannot be a PDS or z/OS® UNIX file system directory name. If you do not specify a file name, the default name is created as follows:

If you are compiling a data set, the as command uses the source file name to form the name of the output data set. The high-level qualifier is replaced with the user ID under which the as command is running, and .ADATA is appended as the low-level qualifier. For example, if TS12345 is compiling TSMYID.MYSOURCE(src) with this option, the produced debug file name will be TS12345.MYSOURCE.ADATA(src).
If you are compiling a z/OS UNIX file, the as command stores the debug information in a file that has the name of the source file with an .ad extension. For example, if you are compiling src.a with this option, the compiler will create a debug file named src.ad.

--[no]gdwarf4[=file]

Instructs the assembler to generate debug information conforming to the DWARF Version 4 format. Debugging tools (for example, dbx) can take advantage of this debug information. You can optionally specify the name of the output debug file. The file name of the output debug file must be a PDS member, a sequential data set or z/OS UNIX file; it cannot be a PDS directory or z/OS UNIX System Services file system directory name. If you do not specify a file name, the default name is created as follows:

If you are compiling a data set, the as command uses the source file name to form the name of the output data set. The high-level qualifier is replaced with the userid under which the as command is running, and .DBG is appended as the low-level qualifier. For example, if TS12345 is compiling TSMYID.MYSOURCE(src) with the -g option, the produced debug file name will be TS12345.MYSOURCE.DBG(src). If TS12345 is compiling TSMYID.SEQSRC with the -g option, the produced debug file name will be TS12345.SEQSRC.DBG.
If you are compiling a z/OS UNIX file, the as command stores the debug information in a file that has the name of the source file with a .dbg extension. For example, if you are compiling src.a with the -g option, the produced debug file name will be src.dbg.

-moption

HLASM keyword options are specified using the following syntax:

-m<option>[=<parm>[=<value>][:<parm>[=<value>]]...]

where <option> is an option name, <parm> is a suboption name, and <value> is the suboption value.

Keyword options with no parameters represent switches that may be either on or off. The keyword by itself turns the switch on, and the keyword preceded by the letters NO turns the switch off. For example, -mLIST tells the HLASM assembler to produce a listing and -mNOLIST tells the HLASM assembler not to produce a listing. If an option that represents a switch is set more than once, the HLASM assembler uses the last setting.

Keyword option and parameter names may appear in mixed case letters in the invocation command.

-I name

Instructs HLASM to look for assembler macro invocation in the specified location. The name can be either a PDS name or z/OS UNIX file system directory name. If a PDS data set is specified, it must be fully qualified. The specified locations are then prepended to a default set of macro libraries. The as command assumes a default set of macro libraries that is compatible with the defaults for the C/C++ compilers. The default data sets used are: -I CEE.SCEEMAC, -I SYS1.MACLIB, and -I SYS1.MODGEN. The default data sets can be changed via the environment variable _AS_MACLIB, for example:

export _AS_MACLIB="FIRST.PDS:SECOND.PDS"

-o objectfile

Specifies the name of the object file. If the name specified is a PDS or z/OS UNIX System Services directory name, a default file name is created in the PDS or z/OS UNIX directory specified as follows:

If the source file is a sequential data set, the second last part of the data set name will be used. If the data set name only contains one part after the high-level qualifier, then the last part will be used.
If the source file is a PDS member, the member name will be used.
If the source file is a z/OS UNIX file, the suffix will be removed if applicable.
If the object file is going into a PDS, the first eight characters of the name will be used. If there is a dot, anything after the first dot will be removed.
If the object file is going into a z/OS UNIX directory, .o will be appended to the name.

For example:

Source file: //'abc.hello.source'
Ouput file in PDS: HELLO
Output file in UNIX directory: hello.o

Source file: //'ABC.HELLO'
Ouput file in PDS: HELLO
Output file in UNIX directory: HELLO.o

Source file: //SOURCE(hello)
Ouput file in PDS: HELLO
Output file in UNIX directory: hello.o

Source file: /abc/hello.s
Ouput file in PDS: HELLO
Output file in UNIX directory: hello.o

Source file: /abc/hellothere.s
Ouput file in PDS: HELLOTHE
Output file in UNIX directory: hellothere.o

-d textfile

Specifies the name of the object file output in text mode. If the name specified is a PDS or z/OS UNIX System Services directory name, a default file name is created in the PDS or z/OS UNIX directory with the same rule as -o.

-v

Writes the version of the as command to stderr.

--[no]help

Help menu. Displays the syntax of the as command.

--[no]verbose

Specifies verbose mode, which writes additional information messages to stdout.

file may be:

An MVS™ data set (for example, //somename)
An absolute z/OS UNIX file (for example, /somename)
A relative z/OS UNIX file (for example, ./somename or somename)

The output of the as command is an object file. If you do not specify a file name via the -o option, the default name is created as follows:

If you are compiling a data set, the as command uses the source file name to form the name of the output data set. The high-level qualifier is replaced with the user ID under which the as command is running, and .OBJ is appended as the low-level qualifier. For example, if TS12345 is compiling TSMYID.MYSOURCE(src), the compiler will create an object file named TS12345.MYSOURCE.OBJ(src).
If you are compiling a z/OS UNIX file, the as command names the object file with the name of the source file with an .o extension. For example, if you are compiling src.a, the object file name will be src.o.

Notes:

The as command does not accept standard input as a file.
The as command invokes the HLASM assembler to produce the object file. The HLASM assembler is invoked with the default options ASA and TERM. The ASA option instructs HLASM to use American National Standard printer control characters in records written to the listing file, thus making the listing file more readable in the z/OS UNIX System Services environment. The TERM option instructs HLASM to write error messages to stderr. These defaults can be changed by using the -m option or -- option.
HLASM messages and as error messages are directed to stderr. Verbose option output is directed to stdout.
When invoking as from the shell, any option arguments or operands specified that contain characters with special meaning to the shell must be escaped. For example, source files specified as PDS member names contain parentheses; if they are specified as fully qualified names, they contain single quotation marks. To escape these special characters, either enclose the option argument or operand in double quotation marks, or precede each character with a backslash.