File Names

The names of all input and output files are customizable. The MAKEFILE, SYSADATA, SYSLIN, SYSPRINT, SYSPUNCH, and SYSTERM options described in chapter 4 may be used to set the names of the make dependency file, object, associated data, listing, punch, and message files respectively. The Library Search Path described later in this chapter and specified via the SYSLIB option and the X390LIB environment variable is used to set the file name patterns of macro and copy members. The X390INI environment variable and the INCLUDE option parameter variable completely specify the file names of option files.

Input Files

Assembler statements, whether they are source statements, macro definitions, or in copy members, may be in either EBCDIC, ASCII or Unicode. If in ASCII or EBCDIC, the lines may be either delimited or undelimited. Unicode lines are always delimited. Undelimited ASCII and EBCDIC lines must be 80 characters long. Delimited EBCDIC lines may be of any length, may contain tab characters (X'05'), and must end with a new-line character (X'15' or X'25'). Delimited ASCII and Unicode lines may be of any length, may contain tab characters (X'09'), and must end with a carriage return (X'0D'), line feed (X'0A'), or both. Files containing delimited ASCII lines may be terminated by an ending EOT (X'04') or EOF (X'1A'). If tab characters are used, the tab stops are assumed to be at columns 9, 17, 25, 33, 41, 49, 57, 64, and 73. After expanding any tab characters, lines shorter than 80 characters are padded with blanks. Any data on delimited lines after column 80 is ignored.

All of the statements in a file must be in the same character set (EBCDIC, ASCII or Unicode). Unicode and delimited EBCDIC files are only supported if the CODEPAGE option is used (or defaulted) to specify the character set translation table. If the ASCII translation options are used, Unicode and delimited EBCDIC files cannot be processed and a different method is used to determine if a file contains ASCII or EBCDIC characters.

If the CODEPAGE option is active, input files containing Unicode (UCS-4) characters encoded in UTF-32BE, UTF32LE, UTF-16BE, UTF-16LE or UTF-8 are supported. The assembler will process the characters in the file in Unicode if any of the following are true:

1. If the first four bytes of a file are X'0000FEFF' or X'FFFE0000' or if the first three bytes are X'00' and the fourth byte is non-zero or if the first byte is non-zero and the next three are X'00', the assembler will decode the file using UTF-32.
2. If the first two bytes are X'FEFF' or X'FFFE' or if either the first or second byte is X'00' but both are not X'0000', the assembler will decode the file using UTF-16.
3. If the first three bytes are X'EFBBBF', the assembler will decode the file using UTF-8.

If not Unicode, the character set (ASCII or EBCDIC) is determined by scanning the first 160 characters of the file. If the CODEPAGE option is active and any of the first 160 bytes are less than X'40' and not X'05' or X'15', the file is assumed to be ASCII. If the CODEPAGE option is not active and any of the first 160 characters are not defined as valid EBCDIC characters, the file is assumed to be ASCII. If there are any tab, carriage return, or line feed characters in the first 160 characters of an ASCII file or any tab or new-line characters in the first 160 characters of an EBCDIC file, the file is assumed to contain delimited lines.

Internally, the assembler processes all statements in EBCDIC, so ASCII and Unicode files are converted as they are read. The translation between the EBCDIC, ASCII and Unicode character sets is customizable, as described in chapter 6.

Source Files

If no source files are specified on the command line and stdin has been redirected, the source is read from stdin. This allows the source to be piped into the assembler from another program. If more than one source file is specified on the x390 command line, they are logically concatenated and read in one after another in the order listed. This is especially useful with the PROCESS(BATCH) option.

Macros and Copy Members

Copy member files are read whenever the assembler COPY statement is processed. Macro definition files are read whenever an undefined operation code is encountered on an assembler statement. The assembler reads both of these file types from the directories, ZIP files or CMS MACLIBs specified by the Library Search Path. Also, chapter 5 describes how to access macros and copy members automatically from mainframe libraries.

The assembler can read macros and copy files stored in ZIP files or in downloaded CMS MACLIB files. Either of these are convienient ways to store large groups of infrequently changed macros and copy files.

If you have a license for the Tachyon File Tools product, you can use the TSO TRANSMIT command to export macro libraries to a transmittable sequential file, download the transmittable data set and then extract the members using the Tachyon Un-Xmit program.

ZIP files

Within ZIP files, macro and copy files may be either “stored” uncompressed or compressed using the “deflate” algorithm. “Deflate” compression is the default for all modern ZIP file creation utilities. File names stored in ZIP files use forward slashes (/) as directory separators. When run in Windows, the assembler will automatically convert any backward slashes (\) in file specifications to forward slashes. Also under Windows, the assembler processes all file names within a ZIP file as if they were specified in upper case, allowing files to be found without regard to the actual case of the file name.

ZIP files may be created with any of the available ZIP utilities. There are even versions of these utilities which can be run on the mainframe to convert an entire library into a ZIP file, which can then be easily transferred to your workstation.

TAR files

TAR files contain a collection of files and may be used to archive macro and copy files. TAR files are created by the UNIX or Linux tar command. When TAR files containing macros are created on OS/390 UNIX System Services, they usually contain EBCDIC text, otherwise they usually contain ASCII text. Macros and copy files in TAR files require more disk space than in compressed ZIP files. When run in Windows, the assembler processes file names in a TAR file like it does for file names in a ZIP file.

CMS MACLIB Files

If you have macro libraries on CMS, they can be downloaded in binary format to your workstation and read directly by the assembler. Macros and copy files in MACLIBs require more disk space than in compressed ZIP files. They also cannot be modified as easily as when they are downloaded as individual files. However if your macros are already in MACLIBs, you do not need to convert them in order for the assembler to access them.

Option Files

Groups of frequently used overrides to the default options may be kept in option files. Lists of these files are specified in the X390INI environment variable and by the INCLUDE assembler option. If the X390INI environment variable is not set, the assembler will attempt to read the file txa.ini from the directory containing the assembler product, however, if txa.ini does not exist, no error is reported.

Each line of an option file may be blank, may be a comment line, or may contain one option. If the first non-whitespace character is an asterisk (*), it is assumed to be a comment line and is not processed. If the first non-whitespace character is not an asterisk, it is assumed to contain an option. Any of the options described in the previous section may be specified in option files using either the full syntax or the abbreviated form. To provide a comment on an option line, follow the option by at least one blank, the remainder of the line will then be ignored.

Output Files

The creation of the assembler output files is entirely controlled through various option settings. The files themselves are described below with references to the applicable options. The options are described in detail in chapter 4.

Assembly Listing

The assembly listing file will be created if the LIST option is set. The listing is written to the file specified by the SYSPRINT option and may be output in several different formats in either EBCDIC or ASCII. The EBCDIC formats are suitable for uploading to and printing from the mainframe, whereas the ASCII formats are oriented to viewing and printing from the workstation. Some of the LINEWIDTH and PRINTCTL options apply to EBCDIC and others to ASCII, so these options control the character set used for the listing file. The page size is controlled through the LINECOUNT option. If the FOLD option is set, the listing file will be in upper case only, instead of the normal mixed case. If FOLD is not set, the headings and any messages may be in either mixed or upper case depending on the LANGUAGE option. See the descriptions of these options for more explanation. Also see the section entitled Controlling the Listing Paper Size for information about how to optimize the listing for printing on Hewlett-Packard compatible printers.

Assembly Messages

Unless the MSGLEVEL(0,0) option is specified, the assembler prints a few messages, such as the copyright notice and the final return code message to stderr. If desired, all error and MNOTE messages may be printed to stdout, stderr or a file by setting the TERM and SYSTERM options. The TERM option value also determines the format of the messages, including if these messages will contain the file name and line number of the statement that generated the message. Messages are written to the file specified by the SYSTERM option and are in either mixed case or lower case ASCII depending on the value of the LANGUAGE option.

Object File

The assembled object code file, along with the output from PUNCH and REPRO statements will be created if the OBJECT(OMF), OBJECT(XOBJ), OBJECT(GOFF) or OBJECT(ELF) option is set. The object code is written to the file specified by the SYSLIN option. Unless OBJECT(ELF) is set, this file contains fixed length records of 80 bytes each and is suitable for uploading to the mainframe as input to the linkage editor or loader. OBJECT(ELF) files may be linked and run by Linux for S/390 or Linux for zSeries. Object files may also be linked by the Tachyon Linkage Editor and the resulting load modules executed by the Tachyon Operating System or uploaded to the mainframe using Tachyon Re-Xmit. Appendix E contains a further discussion of using the assembler to create ELF object files.

Punch Deck

Sometimes instead of an object file, the assembler is used to generate text records through the PUNCH and REPRO statements. For instance, this is the case when the assembler is used to generate BMS symbolic description maps for CICS programs. If these records will be used on the workstation, it may be desirable for the records to be translated into ASCII, instead of the normal EBCDIC output. If you specify the OBJECT(DECK) option the output from PUNCH and REPRO statements will be output in ASCII to the file specified by the SYSPUNCH option.

Associated Data File

In addition to the Assembly Listing, the assembler can produce an “associated data file”. This file contains more information about the assembly than is available in the listing. Also, this file is in a format that is more easily read by a program than the listing, making it useful for programs that must extract information about an assembly. When generated without record prefixes, the associated data file is compatible with IBM’s Program Understanding Tool (ASMPUT) of the HLASM Toolkit Feature. When generated without record prefixes or in GOFF format, the associated data file can be read by z/XDC.

The associated data file is produced if the ADATA option is set. The associated data is written to the file specified by the SYSADATA option. Appendix D contains a further discussion of the associated data file contents.

ADATA records can also be produced in a GOFF object file if the OBJECT(GOFF,ADATA) option is set.

Make Dependency File

The assembler can produce a dependency file which can be helpful in building a make control file for your programs. The dependency file contains a list of all macros and copy members accessed by the assembler. One line per dependency is written to the file. Each line contains the name of the output file (from the SYSLIN or SYSPUNCH option) followed by the name of the file associated with the macro or copy member. Dependency lines are not written for members fetched from ZIP files, TAR files or CMS MACLIBs since the make utility cannot look inside these files to check the time of the last change. The dependency file is produced if the MAKEDEPEND option is set. The dependency lines are written to the file specified by the MAKEFILE option.

Work Files

Two work files are created and deleted during each assembly. One is used for storage of macros as they are defined. The second is used for intermediate storage of the generated statements. The SIZE option value determines if these files are kept in memory or are written to disk. The size of each of these work files is printed in the statistics at the end of each assembly. If the source file is read from stdin, it will be temporarily stored in a third work file.

For UNIX, the work files are created in the /tmp directory. For Windows, the location of these work files is controlled by the TMP environment variable.