Request information list

Pointer to a list of binary fullword items that describe the external function request. The assembler sets this pointer, which is always valid.

The Request Information List consists of these fields:

Parameter list version

A fullword identifying which version of the parameter list is provided to the external function. For High Level Assembler Release 6 this field contains a value of 3.

Function type

A fullword, set by the assembler to indicate the function type:

0
CLOSE call
1
SETAF function
2
SETCF function

Number of parameters

A fullword indicating the number of parameters provided on the call to this external function.

The assembler always sets this field.

Return code

A fullword, set by the external function, indicating success or failure of the operation, and action to be taken by the assembler on return from the external function:

0
Operation successful. Value or string returned.
>0
Operation failed. Request assembler to terminate immediately.

When the return code is greater than 0 the assembler issues diagnostic error message ASMA941U.

Flag byte

X'80'
Function requests a CLOSE call.

The CLOSE call is not enabled by default. Each time the external function is called, it is able to set (or reset) this flag to indicate that it needs to perform some extra processing (releasing storage, for example) before being deleted. The external function may therefore set the flag on one call and reset it on another.

If the flag is set at the end of the assembly, HLASM will call the function with a CLOSE code to allow it to release resources.

The assembler maintains the Flag Byte and provides it to the external function on all calls.

Reserved

This storage is reserved for future use by IBM. The external function should not use this field, nor should it rely on the contents of this field (which are liable to change without notice).

External functions can request that a message be issued on their behalf. The function provides the text of the message, and the assembler inserts the function's name and the supplied text into one of five messages. The relevant information is contained in two fields, Message Length and Message Severity:

Msg length

A halfword, set by the external function, indicating the length of the message to be issued.

Msg severity

A halfword, set by the external function, from which the assembler determines the associated message number. The severity code returned by the function is rounded up to a multiple of four as shown in Table 22.

Table 22. Message severity and associated messages
Severity Code Specified Severity Code Used Associated Message
0 0 ASMA710I
1-4 4 ASMA711W
5-8 8 ASMA712E
9-12 12 ASMA713S
>12 16 ASMA714C

Return value (SETAF)

A fullword, set by the external function. This field is set to zero by the assembler before the external function call.

Parm value n (SETAF)

A fullword, set by the assembler, containing the value of the parameter passed to the external function.

The Number of Parameters field indicates the number of Parm Value n fields in the Request Information List.

Return string length (SETCF)

An unsigned fullword, set by the external function, containing the length of the string pointed to by the Pointer to Parm String field.

The assembler uses this field as the length of the returned string.

If the length is greater than 1024, it is reset to 1024 by the assembler. The consequence of returning a string longer than 1024 bytes is unpredictable.

Parm string n length (SETCF)

An unsigned fullword, set by the assembler, containing the length of the string pointed to by the Ptr to Parm String n field.

The external function should use this length to determine the length of the Parm String n passed by the assembler.

The assembler sets this field to a value between 0 and 1024 inclusive.

The Number of Parameters field indicates the number of Parm String n Length fields in the Request Information List.


[ Top of Page | Previous Page | Next Page | Contents | Index ]