Assembler Interface Development

This chapter describes how to generate an assembler interface code using the ofasmif tool in OpenFrame ASM.

1. Interface Version 3 Specification File

ofasmif creates a cpp interface source file from an interface version 3 specification file. An interface is needed to make calls from ASM to non-ASM or from non-ASM to ASM.

ENTRY Interface Specification

The ENTRY interface specification file (version 3) must be created to enable calls from non-ASM to ASM. It has the following structure:

{
  "entry_list":
  [
    {
      "entry_name" : "ENTRYNAME1",
      "fixed_parameter_list" :
      [
        {
          "param_size" : (PARASIZE),
          "param_type" : (PARATYPE),
          "pointer_offset_list" : [OFFSET_POSITION, ...],
          "pointer_size_list" : [POINTER_SIZE, ...]
        },
      ]
    },
    {
      "entry_name" : "ENTRYNAME2",
      "variable_parameter_list" :
      {
        "max_length" : (MAXLEN)
      }
    }
  ],
  "program_name" : "PROGNAME",
  "version" : 3,
  "interface_type" : "entry"
}

entry_list

A JSON array of entry specifications of a program.

Each entry defines an entry_name corresponding to the program entry point and the parameters, fixed_parameter_list and variable_parameter_list, that are passed into the program.

entry_name

Name of the entry point (different from the program name).

fixed_parameter_list

A JSON array of fixed number of parameters for the entry. Each parameter consists of a param_size and param_type.

For pointer-type parameters, pointer_offset_list and pointer_size_list must also be configured.

Parameter	Description
param_size	Parameter size in bytes.
param_type	Parameter type. P: pointer type NP: non-pointer type V: variable length type PCB: PCB type
pointer_offset_list	For pointer-type parameters, specifies a list of offsets for the pointers contained in the parameter structure. The offset values of the pointers in the structure must be defined in order.
pointer_size_list	For pointer-type parameters, specifies a list of sizes for the pointers contained in the parameter structure. Similar to pointer_offset_list, the pointer sizes must be defined in order. The number of the items in the list must be the same as that of pointer_offset_list, with each offset paired with its size.

Parameter

Description

param_size

Parameter size in bytes.

param_type

Parameter type.

P: pointer type
NP: non-pointer type
V: variable length type
PCB: PCB type

pointer_offset_list

For pointer-type parameters, specifies a list of offsets for the pointers contained in the parameter structure. The offset values of the pointers in the structure must be defined in order.

pointer_size_list

For pointer-type parameters, specifies a list of sizes for the pointers contained in the parameter structure.

Similar to pointer_offset_list, the pointer sizes must be defined in order. The number of the items in the list must be the same as that of pointer_offset_list, with each offset paired with its size.

variable_paramter_list

A JSON object to hold a variable number of parameters for the entry.

Parameter Description

max_length

Maximum allowed number of parameters.

program_name

Assembler program name. An assembler program has an asmo file extension.
interface_type

Interface type. For ENTRY interfaces, enter "entry".
version

Interface specification version (same as the version of the ofasmif command).

The latest version of the interface specification currently provided by the ofasmif command is version 4.

Parameter	Description
max_length	Maximum allowed number of parameters.

EXIT Interface Specification

The EXIT interface specification file (version 3) must be created to enable calls from ASM to non-ASM. It has the following structure:

{
  "entry_list":
  [
    {
      "entry_name" : "ENTRYNAME1",
      "fixed_parameter_cnt" : (PARAMCOUNT)
    }
  ],
  "program_name" : "PROGNAME",
  "version" : 3,
  "interface_type" : "exit"
}

interface_type

Interface type. For EXIT interfaces, enter "exit".

For details on each item, refer to ENTRY Interface Specification. In the fixed_parameter_cnt field, enter the number of parameters received from the non-ASM.

LOAD Interface Specification

The LOAD interface specification file (version 3) must be created when calling another module from ASM using the CICS LOAD command. It has the following structure:

{
  "entry_list":
  [
    {
      "entry_name" : "ENTRYNAME1",
      "fixed_parameter_list" :
      [
        {
          "param_size" : (PARASIZE),
          "param_type" : (PARATYPE),
          "pointer_offset_list" : [OFFSET_POSITION, ...],
          "pointer_size_list" : [POINTER_SIZE, ...]
        }
      ]
    }
  ],
  "program_name" : "PROGNAME",
  "version" : 3,
  "interface_type" : "load"
}

interface_type

Interface type. For LOAD interfaces, enter "load".

For details on each item, refer to ENTRY Interface Specification.

2. Interface Version 4 Specification File

ofasmif creates a cpp interface source file from an interface version 4 specification file. An interface is needed to make calls from ASM to non-ASM or from non-ASM to ASM.

ENTRY Interface Specification

The ENTRY interface specification file (version 4) must be created to enable calls from non-ASM to ASM. It has the following structure:

{
  "entry_list":
  [
    {
      "entry_name" : "ENTRYNAME1",
      "fixed_parameter_list" :
      [
        {
          "param_size" : (PARASIZE),
          "param_type" : (PARATYPE),
          "pointer_offset_list" : [OFFSET_POSITION, ...],
          "pointer_size_list" : [POINTER_SIZE, ...],
          "child_list" :
          [
            {
              "index" : (INDEX),
              "param_size" : (PARASIZE),
              "pointer_offset_list" : [OFFSET_POSITION, ...],
              "pointer_size_list" : [POINTER_SIZE, ...]
            },
            ...
          ]
        },
        ...
      ]
    },
    {
      "entry_name" : "ENTRYNAME2",
      "variable_parameter_list" :
      {
        "max_length" : (MAXLEN)
      }
    },
    ...
  ],
  "program_name" : "PROGNAME",
  "version" : 4,
  "interface_type" : "entry"
}

entry_list

A JSON array of entry specifications of a program.

Each entry defines an entry_name corresponding to the program entry point and the parameters, fixed_parameter_list and variable_parameter_list, that are passed into the program.

entry_name

Name of the entry point (different from the program name).

fixed_parameter_list

A JSON array of fixed number of parameters for the entry. Each parameter consists of a param_size and param_type.

For pointer-type parameters, pointer_offset_list and pointer_size_list must also be configured.

Parameter	Description
param_size	Parameter size in bytes.
param_type	Parameter type. P: pointer type NP: Non-Pointer type V: variable length PCB: PCB type
pointer_offset_list	For pointer-type parameters, specifies a list of offsets for the pointers contained in the parameter structure. The offset values of the pointers in the structure must be defined in order.
pointer_size_list	For pointer-type parameters, specifies a list of sizes for the pointers contained in the parameter structure. Similar to pointer_offset_list, the pointer sizes must be defined in order. The number of the items in the list must be the same as that of pointer_offset_list, with each offset paired with its size.
child_list	(For P-type parameters) Used when the data pointed by each pointer specified in a P-type parameter contains additional pointers. This field can be used recursively. index: Index of the pointer to be defined among those specified in pointer_offset_list and pointer_size_list. param_size: Size of the data referenced by the pointer. It must be identical to the value of pointer_size_list[index]. pointer_offset_list: Offsets of each pointer included in the data referenced by the pointer. pointer_size_list: Size of the data pointed to by each pointer included in the data referenced by the pointer.

Parameter

Description

param_size

Parameter size in bytes.

param_type

Parameter type.

P: pointer type
NP: Non-Pointer type
V: variable length
PCB: PCB type

pointer_offset_list

For pointer-type parameters, specifies a list of offsets for the pointers contained in the parameter structure. The offset values of the pointers in the structure must be defined in order.

pointer_size_list

For pointer-type parameters, specifies a list of sizes for the pointers contained in the parameter structure.

Similar to pointer_offset_list, the pointer sizes must be defined in order. The number of the items in the list must be the same as that of pointer_offset_list, with each offset paired with its size.

child_list

(For P-type parameters) Used when the data pointed by each pointer specified in a P-type parameter contains additional pointers. This field can be used recursively.

index: Index of the pointer to be defined among those specified in pointer_offset_list and pointer_size_list.
param_size: Size of the data referenced by the pointer. It must be identical to the value of pointer_size_list[index].
pointer_offset_list: Offsets of each pointer included in the data referenced by the pointer.
pointer_size_list: Size of the data pointed to by each pointer included in the data referenced by the pointer.

variable_paramter_list

A JSON object to hold a variable number of parameters for the entry.

Parameter Description

max_length

Maximum allowed number of parameters.

program_name

Assembler program name. An assembler program has an asmo file extension.
interface_type

Interface type. For ENTRY interfaces, enter "entry".
version

Interface specification version (same as the version of the ofasmif command).

The latest version of the interface specification currently provided by the ofasmif command is version 4.

Parameter	Description
max_length	Maximum allowed number of parameters.

EXIT Interface Specification

The EXIT interface specification file (version 4) must be created to enable calls from ASM to non-ASM. It has the following structure:

{
  "entry_list":
  [
    {
      "entry_name" : "ENTRYNAME1",
      "fixed_parameter_list" :
      [
        {
          "param_type" : "NP"
        },
        {
          "param_size" : (PARASIZE),
          "param_type" : "P",
          "pointer_offset_list" : [OFFSET_POSITION, ...],
          "pointer_size_list" : [POINTER_SIZE, ...]
        }
      ]
    }
  ],
  "program_name" : "PROGNAME",
  "version" : 4,
  "interface_type" : "exit"
}

interface_type

Interface type. For EXIT interfaces, enter "exit".

For details on each item, refer to ENTRY Interface Specification. If param_type is set to "NP" or "F", the param_size does not need to be specified.

LOAD Interface Specification

The LOAD interface specification file (version 4) must be created when calling another module from ASM using the CICS LOAD command. It has the following structure:

{
  "entry_list":
  [
    {
      "entry_name" : "ENTRYNAME1",
      "fixed_parameter_list" :
      [
        {
          "param_size" : (PARASIZE),
          "param_type" : (PARATYPE),
          "pointer_offset_list" : [OFFSET_POSITION, ...],
          "pointer_size_list" : [POINTER_SIZE, ...]
        }
      ]
    }
  ],
  "program_name" : "PROGNAME",
  "version" : 4,
  "interface_type" : "load"
}

interface_type

Interface type. For LOAD interfaces, enter "load".

For details on each item, refer to ENTRY Interface Specification.

3. ofasmif Command

The following describes how to use the ofasmif command.

ofasmif [command option...]

Command Options

The following describes each basic command option for compiling source files.

Option	Description
-i filename	Sets an input file. Must have the json extension to be recognized as an interface specification file.
--cpp-only	Generates only the cpp file. Must be used with the -i option.
--comp-only	Compiles the cpp file using g++. Must be used with the -i option.
-g <interface type>	Interface type of the JSON file to be generated.
-n <program name>	Name of the JSON file to be used as the program name. Must be used with the -g option.
-e <entry name>	Entry name of the JSON file to be generated. Must be used with the -g option. If not set, the program name will be used as the entry name.
-t <parameter type>	Parameter types (V, F, PCB, or JCL). Must be used with the -e option.
-m <number of parameters>	Maximum number of parameters. Used for -t V (variable parameters).
-s <size list>	Size list of parameters. Used for -t F (fixed parameters).
--ptr-offset <pointer parameter offset list>	Specifies the list of offsets for pointer parameters when using -t F (fixed parameters) with pointer parameters. This must be used with the --ptr-size option, and the two lists must correspond to each other.
--ptr-size <pointer parameter size list>	Specifies the list of sizes for pointer parameters when using -t F (fixed parameters) with pointer parameters. This must be used with the --ptr-offset option, and the two lists must correspond to each other.
-p <filename>	Enables auto indentation.
-h(H)	Displays help.

Option

Description

-i filename

Sets an input file. Must have the json extension to be recognized as an interface specification file.

--cpp-only

Generates only the cpp file. Must be used with the -i option.

--comp-only

Compiles the cpp file using g++. Must be used with the -i option.

-g <interface type>

Interface type of the JSON file to be generated.

-n <program name>

Name of the JSON file to be used as the program name. Must be used with the -g option.

-e <entry name>

Entry name of the JSON file to be generated. Must be used with the -g option. If not set, the program name will be used as the entry name.

-t <parameter type>

Parameter types (V, F, PCB, or JCL). Must be used with the -e option.

-m <number of parameters>

Maximum number of parameters. Used for -t V (variable parameters).

-s <size list>

Size list of parameters. Used for -t F (fixed parameters).

--ptr-offset <pointer parameter offset list>

Specifies the list of offsets for pointer parameters when using -t F (fixed parameters) with pointer parameters. This must be used with the --ptr-size option, and the two lists must correspond to each other.

--ptr-size <pointer parameter size list>

Specifies the list of sizes for pointer parameters when using -t F (fixed parameters) with pointer parameters. This must be used with the --ptr-offset option, and the two lists must correspond to each other.

-p <filename>

Enables auto indentation.

-h(H)

Displays help.

Examples

The following examples show generating various interfaces by parameter type using the ofasmif -g option.

Basic variable parameter ENTRY interface. Up to 10 parameters can be specified.
```
ofasmif -g entry -n TEST -e TEST
```

Variable parameter ENTRY interface. The maximum number of parameters must be specified.
```
ofasmif -g entry -n TEST -e TEST -t V -m 10
```

Fixed parameter ENTRY interface. This is an example of a case without pointer parameters.
```
ofasmif -g entry -n TEST -e TEST -t F -s 100,200,300
```

Fixed parameter ENTRY interface. This is an example of a case with pointer parameters.

ofasmif -g entry -n TEST -e TEST -t F -s 100,14,24 --ptr-offset “[(),(0,4),(4,8)]” --ptr-size “[(),(100,200),(200,300)]”

PCB parameter ENTRY interface. The maximum number of PCB parameters must be specified.
```
ofasmif -g entry -n TEST -e TEST -t PCB -m 100
```

JCL parameter ENTRY interface.
```
ofasmif -g entry -n TEST -e TEST -t JCL
```

EXIT interface. This is an example of a case without pointer parameters.
```
ofasmif -g exit -n TEST -e TEST -m 10
```

EXIT interface. This is an example of a case with pointer parameters.

ofasmif -g exit -n TEST -e TEST -t F -s 100,14,24 --ptr-offset “[(),(0,4),(4,8)]” --ptr-size “[(),(100,200),(200,300)]”

LOAD interface. It is created in the same way as a fixed parameter ENTRY interface.
```
ofasmif -g exit -n TEST -e TEST -t F -s 1024
```

Interface for multiple ENTRYs.

ofasmif -g entry -n TEST -e ENTRY_1 -t F -s 100,200 -e ENTRY_2 -t V -m 10