CALL request (CALL) for the IMS installed level API

Use the CALL function of the DFSGVRM API to obtain the version, release, and modification level of the IMS system.

When the calling application issues the CALL request, IMS builds a parameter list to call module DFSGVRM0, and the parameter list is mapped by DFSGVRMP. The storage for the parameter list is obtained by the calling application and must be GVRMP_LN in length. The address of the parameter list is specified either as a symbol or a register by using the PARMS parameter on the CALL request.

The CALL function returns an output area that contains the IMS installed level and that is mapped by DFSGVRMO. The address of the output area is in the GVRMP_A_OUTPUT_AREA field of the parameter list. Optionally, you can use the RETAREA parameter on the CALL request to specify a register that receives the address of the output area. Specifying the RETAREA parameter provides a way to prevent the calling application from having to reference the field in the parameter list directly.

If the RETAREA register or the parameter list field GVRMP_A_OUTPUT_AREA is nonzero after the output area is returned by the CALL function, regardless of the return code the calling application must use the REL function to release the output storage areas.

Syntax for CALL requests

Parameters for CALL requests

PARMS=symbol | (R2-R12)

Specifies the address of the parameter list to call module DFSGVRM0. The parameter list is mapped by DFSGVRMP.

If specified as a symbol, the symbol must represent an area of storage that is GVRMP_LN in length.

If specified as a register, the register must point to an area that is GVRMP_LN in length.

RETAREA=(R2-R12)

Specifies a register that receives the address of the output area that is returned by the DFSGVRM module and that is mapped by DFSGVRMO.

This parameter is optional.

If this parameter is not specified, the address of the output area is in the GVRMP_A_OUTPUT_AREA field of the parameter list.

The application that issues the CALL function is responsible for releasing the output area when the RETAREA register or the GVRMP_A_OUTPUT_AREA field is non-zero, regardless of the macro return code. The output area address is set to zero when the output area is not present on return.

LOC=24|31

Specifies whether the output area should be retrieved from below (LOC=24) or above (LOC=31) the 16 MB line.

This parameter is optional.

If this parameter is not specified, the area is above the 16 MB line (LOC=31).

Return and reason codes for CALL requests

When the DFSGVRM FUNC=CALL request is made, IMS returns the return code in register 15 and the reason code in register 0.

Table 1. Return and reason codes for CALL requests
Return code	Reason code	Meaning
X'00000000'	X'00000000'	The request completed successfully.
X'00000008'	X'`yyyyzzzz`'	Unable to LOAD module DFSGVRM0. In the reason code: `yyyy` Is the low-order 2 bytes of the ABEND code that LOAD would have issued. `zzzz` Is the low-order 2 bytes of the reason code for the ABEND that would have been issued.
X'0000000C'	Return code from DELETE macro	Failure trying to delete module DFSGVRM0 after successful invocation of DFSGVRM0. The return area provided is valid and available for use.
X'00000010'	Return code from STORAGE RELEASE	Unable to free the output area that is referred to by the AREA= parameter.
X'00001008'	Return code from STORAGE OBTAIN	The DFSGVRM0 module could not obtain storage for the output area.
X'0000100C'	X'`yyyyzzzz`'	Unable to LOAD module DFSVC000. In the reason code: `yyyy` Is the low-order 2 bytes of the ABEND code that LOAD would have issued. `zzzz` Is the low-order 2 bytes of the reason code for the ABEND that would have been issued.
X'000010FF'	Various	An internal error occurred.