RSX-11 Network Macro Formats

DECnet-RSX MACRO-11 Programming Facilities

DECnet-RSX provides a library of MACRO-II macros to use in network intertask communication. This chapter:

• Describes the three network macro formats.

• Explains the connect block and access options for your task.

• Lists the graphic conventions for this chapter.

• Describes each intertask communication macro call.

2.1 RSX-11 Network Macro Formats

You can use the following formats to code macros:

• BUILD type macro. Creates a parameter block at assembly time and is generally used in conjunction with an EXECUTE type macro or a DIR$ direc-tive.

• EXECUTE type macro. References the parameter block that a BUILD type macro created and executes the requested function. An EXECUTE type macro lets you override parameters that the BUILD type macro specified.

• STACK type macro. Creates a parameter block on the processor stack and executes the requested function.

2.1.1 BUILD Type Macros

You use the BUILD type macro at assembly time. This macro creates a parameter block that contains arguments that describe the network function you requested.

A pre-defined parameter block is especially useful for repetitions of the same net-work operation. If you omit an optional parameter from this block, the macro allocates space for it anyway. Later, you can use an EXECUTE type macro to fill in the argument. If you plan to use the EXECUTE type macro, however, you must include all of the BUILD type macro's trailing arguments.

The format for a BUILD type macro is:

label: XXX[W]$ parameter-list[Jlag]

where

label is a symbolic name associated with the location of the parame-ter block.

xxx is the name of a DECnet-RSX macro.

[W] specifies that this network function will complete synchro-nously. The issuing task waits until the function completes before continuing. If you omit the W, the call completes asyn-chronously.

parameter-list is a list of arguments that describe particular features of this call. Each parameter must be a valid argument for a .WORD or .BYTE MACRO-11 directive. Each call description includes a list of the parameters for the call. The number of arguments specified must not exceed the number specified in an EXECUTE type macro that will use this parameter block.

flag is a symbolic name that specifies an optional subfunction of the network macro.

You can execute a BUILD type macro by issuing an EXECUTE type macro or a DIR$ macro. A DIR$ macro call pushes the address of the network function parameter block that you created with the BUILD macro on the processor stack and then issues an EMT 377 for the Executive to execute the macro. You can write a DIR$ macro as follows:

DIR$ adr,err

where

adr is the address of the parameter block in the format of a source operand of an MOV instruction.

err is the address of an optional error routine. The C-bit in the processor status word (PSW) is set whenever an error is encountered.

A DIR$ macro generates less code than a corresponding EXECUTE macro.

2.1.2 EXECUTE Type Macros

The EXECUTE type macro references a network function parameter block that you create at assembly time with a BUILD type macro. An EXECUTE type macro lets you enter parameters that override those that you originally defined with a BUILD macro.

You must include all trailing arguments in a BUILD type macro that an EXECUTE type macro references.

Once you redefine or specify new parameters for the call, the EXECUTE macro automatically executes the function that the call requests. The format for an EXECUTE type macro is:

xxx[W]$E label[,override-parameter-list][Jlag]

where xxx

[W]

label

is the name of a DECnet-RSX macro.

specifies that this network function will complete synchro-nously. The issuing task waits until the function completes before continuing. If you omit the W, the call completes asyn-chronously.

represents one of two values:

• The label of the BUILD type macro that supplies parame-ters for this EXECUTE macro. You can include arguments immediately following the label to override any parame-ters previously defined in the BUILD parameter block.

override-parameter-list

flag

• The label of an area of memory that will contain the parameters that you are currently specifying. The parame-ter block is built and the call is executed in the same macro.

is a list of one or more arguments to replace parameters that you previously defined for this call in a BUILD type macro.

Each argument in this list must be a valid source operand for an MOV S, label + offset MACRO-II instruction.

You can override the value of a parameter and assign it a null value. For example, if an AST is not required, specify the parameter as O.

is a symbolic name that specifies an optional subfunction of the network macro.

2.1.3 STACK Type Macros

The STACK type macro creates the network function parameter block for the call on the processor stack and then executes the requested function. You must spec-ify all required parameters when you issue this macro or it will generate assembly errors.

The format for a STACK type macro is:

XXx[W] $ S parameter-list[ flag]

where

xxx is the name of a DECnet-RSX macro.

[W] specifies that this network function will complete synchro-nously. The issuing task waits until the function completes before continuing. If you omit the W, the call completes asyn-chronously.

parameter-list is a list of arguments that describe particular features of this call. Each argument must have the form of a valid MACRO-II MOV instruction source operand. Each call description includes a list of the parameters for the call.

flag is a symbolic name that specifies an optional subfunction of the network macro.

2.1.4 Macro Format Examples

The following examples demonstrate the three macro types. The first, a BUILD type macro, creates a parameter block for the call designated by XXX$:

label: xxx[W]$lun,e/n,status,ast, <pl~p2~ ... ~pn>

The first example of an EXECUTE type macro references the parameter block cre-ated for label:

xxx[W] $ E label

The second EXECUTE type macro overrides the parameter list arguments p 1 and p2:

xxx[W]$E label"", <pl~p2>

The last example, a STACK type macro, creates a parameter block on the stack, and executes the call.

xxx[W]$S #lun,#e/n,#status,#ast,

<