Compilation

This chapter describes how to compile ASM code using the OpenFrame ASM compiler.

1. Compile

OpenFrame ASM compiles ASM code into an object file that can run on OpenFrame ASM Virtual Machine (VM).

The following is the process for compiling ASM code and generating object code. The file must have the .asm extension.

ofasm -E <filename>.asm

The compilation process is divided into two stages: preprocessing and assembly. Each stage can be executed separately.

  • Preprocessing

    Preprocessing a .asm file generates a .asmi file. This process involves interpreting and executing macro commands and conditional assembly commands.

    Preprocessing in OpenFrame ASM is executed as follows:

    ofasm -E <filename>.asm

  • Assembly

    Assembling a .asmi file generates a .asmo file. A .asmo file can be run on the OpenFrame ASM VM.

    Assembly in OpenFrame ASM is executed as follows:

    ofasm -S <filename>.asmi

2. ofasm Command

The following describes how to use the OpenFrame ASM compile command (ofasm).

ofasm sourcefile... [command option...]

  • Source Files

    The files to compile must have the 'asm' extension to be recognized as an ASM source file.

  • Command Options

    The following describes basic command options for compiling a source file.

    Option Description

    -o filename

    Specifies the name of the object file. If not specified, the default name is <input filename>.asmo.

    --debug

    Outputs log messages during preprocessing and compilation.

    -L <dir>

    Sets a macro library path.

    -h(H) or --help

    Displays help.

    --version

    Displays the current version information of OpenFrame ASM.

    -E

    Only executes preprocessing (input: .asm file, output: .asmi file).

    -S

    Only executes assembly (input: .asmi file, output: .asmo file).

    --enable-cics

    Enables CICS library.

    --list

    Displays macros, copybooks, machine and assembler instructions, and outdated instruction supported by OpenFrame ASM.

    -x <params..>

    Immediately executes the assembler using the parameter specified by the user on the command line. Parameters must be hexadecimal values.

    -f <filepath>

    Can only be used with the -x option. Specifies a JSON files that defines parameter information.

    -r <reg_no> <value>

    Can only be used with the -x option. Specifies the register value before execution.

    --entry <entryname>

    Can only be used with the -x option. Specifies the name of the entry to execute.

    --save-punch

    Generates an output file for PUNCH record data.

    --enable-spm

    Enables structured programming macros.

    --license

    Displays license information.

    --force-rmode31

    Forcibly applies 31-bit RMODE to the object code of the target program.

    --no-reuse

    A new program instance is created every time the target program is loaded into OpenFrame ASM.

    --sysparm <string>

    Specifies the value of &SYSPARM used during preprocessing for the target program.

    --enable-outdated

    Enables the use of outdated instructions for the target program. For details, refer to the outdated instructions displayed by the --list option.

    --amode <24,31,ANY>

    Specifies the addressing mode to use for compilation. This value overrides the AMODE value defined in the target file.

    --rmode <24,31,ANY>

    Specifies the residency mode to use for compilation. This value overrides the RMODE value defined in the target file.

3. Configuration File

In OpenFrame ASM, options applied during compile time and runtime can be configured through properties.conf. If you change options applied at compile time, you must recompile all assembler files and then run them to operate properly.

  • Path

    $OFASM_HOME/config/properties.conf

  • Options

    {
  "OFASM_LOG" :
  {
    "ONLINE" :
    {
      "OFASM_LOG_LEVEL": 0,
      "OFASM_LOG_AFTER": 0
    },
    "BATCH" :
    {
      "OFASM_LOG_LEVEL": 0,
      "OFASM_LOG_AFTER": 0
    }
  },
  "NETCOBOL_COMPATIBLE" : "OFF",
  "MAKE_PLIST_IN_EXIT" : "OFF",
  "CHECK_OBJ_VERSION" : "OFF",
  "VM_MEMORY_SIZE" : 0,
  "USE_CODE_CONVERSION" : {
    "ASCII_TO_EBCDIC" : "",
    "EBCDIC_TO_ASCII" : "",
    "SORT_TYPE" : 0
  },
  "HEAP_MONITOR" : "OFF",
  "USE_TCFH_FILE_IO" : "NO",
  "FORCE_RMODE_31" : [],
  "USER_SVC" : {}
}

OFASM_LOG

Options for log output to stdout while the ASM program is running. The settings for OFASM_LOG only apply to separate debug binaries.

This option only applies at runtime.

ONLINE / BATCH: Sets the log options to apply to Online and Batch products.

Setting Value Description

OFASM_LOG_LEVEL

Sets the log level. Only integer values can be used.

  • 0: Disables logging (default)

  • 1 ~ 5: Enables logging

  • 6: Adds a timestamp to the log format used in level 5.

OFASM_LOG_AFTER

Determines from which log number to start output. Only integer values can be used.

  • 0 : Disables logging (default)

  • 1+: Determines from which log number to start output.

The following example shows the output results for each log level.

  • Level 1: Outputs some errors that can be ignored.

  • Level 2: In addition to Level 1, outputs the target label when branching and the program name when switching programs within OFASM.

    // Switches from initial state (VM_ENTER) to the TEST program.
[VM_ENTER] (VM_ENTER) > (TEST    )

// Entered the TEST label, and the address is 0x0001f7b0.
[TEST    ] 0001f7b0 >> (TEST)TEST
Addr=[0000000000128954], Length=[0000000000000005], Hex=[0x48454c4c4f], Char=[HELLO]

// Switches from the TEST program to an unspecified program XXXXXXXX.
[TEST    ] (TEST    ) > (XXXXXXXX)

// Returns from XXXXXXXX to VMRETURN.
[XXXXXXXX] (XXXXXXXX) > (VMRETURN)

  • Level 3: In addition to Level 2, outputs the executed machine instructions.

    [VM_ENTER] (VM_ENTER) > (TEST    )
[TEST    ] 0001f7b0 >> (TEST)TEST
[TEST    ] 0001f7b0 >> LR      12,15
[TEST    ] 0001f7b2 >> DBGMEM  10(5,12),2(0)
Addr=[0000000000128954], Length=[0000000000000005], Hex=[0x48454c4c4f], Char=[HELLO]
[TEST    ] 0001f7b8 >> BCR     15,14
[TEST    ] 0001f7b8 >> 00002000
[TEST    ] (TEST    ) > (XXXXXXXX)
[XXXXXXXX] (XXXXXXXX) > (VMRETURN)

  • Level 4: In addition to Level 3, adds the execution order before each executed machine instruction.

    [VM_ENTER][0000000000] (VM_ENTER) > (TEST    )
[TEST    ][0000000001] 0001f7b0 >> (TEST)TEST
[TEST    ][0000000001] 0001f7b0 >> LR      12,15
[TEST    ][0000000002] 0001f7b2 >> DBGMEM  10(5,12),2(0)
Addr=[0000000000128954], Length=[0000000000000005], Hex=[0x48454c4c4f], Char=[HELLO]
[TEST    ][0000000003] 0001f7b8 >> BCR     15,14
[TEST    ][0000000003] 0001f7b8 >> 00002000
[TEST    ][0000000003] (TEST    ) > (XXXXXXXX)
[XXXXXXXX][0000000004] (XXXXXXXX) > (VMRETURN)

  • Level 5: In addition to Level 4, outputs parameter information and other detailed logs when the program switches or returns.

    // VM started
[VM_ENTER][0000000000] VM::start()

// Entering the program load phase
[VM_ENTER][0000000000] Loader::loadProgram()

// Entering ASM program load phase
[VM_ENTER][0000000000] Loader::loadAsmProgram()

// RMODE for the current program determined as 24
[VM_ENTER][0000000000] Global RMODE : 24

// Path of the program file to be loaded
[VM_ENTER][0000000000] ./TEST.asmo[REUSE]

// Entry name within the program file
[VM_ENTER][0000000000] TEST
[VM_ENTER][0000000000] (VM_ENTER) > (TEST    )

// Entering parameter load phase
[TEST    ][0000000000] Loader::loadParameters()

// Entering the parameter list generation phase
[TEST    ][0000000000] Loader::buildParameterAddressList()
[TEST    ][0000000001] 0001f7b0 >> (TEST)TEST
[TEST    ][0000000001] 0001f7b0 >> LR      12,15
[TEST    ][0000000002] 0001f7b2 >> DBGMEM  10(5,12),2(0)
Addr=[0000000000128954], Length=[0000000000000005], Hex=[0x48454c4c4f], Char=[HELLO]
[TEST    ][0000000003] 0001f7b8 >> BCR     15,14
[TEST    ][0000000003] 0001f7b8 >> 00002000
[TEST    ][0000000003] (TEST    ) > (XXXXXXXX)

// Entering the parameter list deallocation phase
[XXXXXXXX][0000000004] Loader::freeParameterAddressList()

// Entering the parameter list return phase
[XXXXXXXX][0000000004] Loader::storeParameters()
[XXXXXXXX][0000000004] VM::end()

// VM terminated
[XXXXXXXX][0000000004] (XXXXXXXX) > (VMRETURN)

    The program name XXXXXXX in the log is displayed when the program was not loaded by the user or is provided by the system.

NETCOBOL_COMPATIBLE

Enable this field when using NetCOBOL products with OpenFrame ASM.

This option applies at compile time and runtime.

Setting Value Description

OFF

Disables NetCOBOL compatibility. (Default)

ON

Enables NetCOBOL compatibility.

MAKE_PLIST_IN_EXIT

Enable this field when calling a non-ASM application using the EXIT interface, if it uses a fixed parameter format. This option is valid only in interface version 4.

This option applies during interface switching and at runtime.

Setting Value Description

OFF

This option can be applied when the parameter format is variable and there are 10 or fewer parameters. (Default)

ON

This option can be used when the parameter format is fixed and the number of parameters is not specified.

CHECK_OBJ_VERSION

At runtime, if the executing module differs from the current ofasm version, a warning message is displayed.

This option is applied at runtime.

Setting Value Description

OFF

Compares the executing module with the current ofasm version at runtime, and does not display a warning message even if they differ. (Default)

ON

Compares the executing module with the current ofasm version at runtime and displays a warning message if they differ.

VM_MEMORY_SIZE

Sets the size of the memory to be used by the OpenFrame ASM VM in megabytes (MB). The minimum value is 32, and the maximum value is 2048. Only integer values are allowed.

This option only applies at runtime.

Setting Value Description

0

Uses 1024 MB (1 GB) of memory. (Default)

32 ~ 2048

Uses the specified amount of memory in megabytes (MB).

USE_CODE_CONVERSION

Specifies the code page map (.cpm) file to be used in the OFATOE and OFETOA machine instructions provided by OpenFrame ASM.

This option only applies at runtime.

  • ASCII_TO_EBCDIC/EBCDIC_TO_ASCII: Specifies the cpm file to be used for OFATOE and OFETOA, respectively.

Setting Value Description

<empty>

Does not use cpm files. (Default)

<file name>.cpm

Uses the cpm file with the specified file name.

The specified cpm file must be located within $OPENFRAME_HOME/cpm.

  • SOSI_TYPE: Specifies the default SO/SI conversion option to be used in the OFATOE and OFETOA machine instructions as an integer value. Currently, only the value 1 is supported.

Setting Value Description

<empty>

Uses 1. (Default)

1 = so[EBC]si → so[ASC]si

Does not convert SOSI values.

HEAP_MONITOR

Outputs logs related to memory allocation and deallocation in the OpenFrame ASM VM.

This option only applies at runtime.

Setting Value Description

OFF

Disables logging related to memory allocation and deallocation. (Default)

ON

Uses logs related to memory allocation and deallocation.

USE_TCFH_FILE_IO

Specifies the OpenFrame base module used by the OpenFrame ASM VM.

This option only applies at runtime.

Setting Value Description

NO

Does not use tcfh base module. This option is used for backward compatibility. (Default)

YES

Uses the tcfh base module.

FORCE_RMODE_31

Forcibly applies 31-bit RMODE to the programs specified in this list.

The following example shows how to load the TEST01 and TEST02 programs with 31-bit RMODE applied.

{
  "FORCE_RMODE_31" : ["TEST01", "TEST02"],
}

USER_SVC

User SVCs use SVC numbers ranging from 200 to 255, which are defined by the user and not provided by the host.

To use user-defined SVCs, first set the OFASM_USERSVCLIB environment variable to the path of the directory containing the User SVC modules.

export OFASM_USERSVCLIB=<user SVC directory path>

Then, define which module to use for each SVC in the properties.config file as follows.

{
  "USER_SVC" :
  {
    "IGC00<SVC number>" : "<program name>"
  }
}

For example, to call the TEST module for SVC239, define it as follows:

{
  "USER_SVC" :
  {
    "IGC00239" : "TEST"
  }
}