Evaluating the return codes

The SM2GMS and SM2GDAT macros store the return codes in a structure of the type ESMFHDR, which can be addressed via the “hdr” structure element of the structure of the type “SM2GMS_get_measurement_stat_mdl” (in the case of SM2GMS) or of the structure of the type “SM2GDAT_get_data_mdl” (in the case of SM2GDAT).

The ESMFHDR structure is declared in FHDR.H and structured as follows:

struct  ESMFHDR {
        struct FHDRifid_mdl if_id;      /* interface identifier     */
        struct FHDRretc_mdl returncode; /* return code              */
};

The “if_id” structure element of the type “FHDRifid_mdl” is used internally by the SM2GMS and SM2GDAT macros and has no significance for the evaluation of the return codes.

The “returncode” structure element of the type “FHDRretc_mdl” has the following structure:

/* returncode structure                                             */
struct FHDRretc_mdl {
        union /* rc */ {
                struct {
                        struct {
                                unsigned char subcode2;
                                unsigned char subcode1;
                        } subcode;
                        union /* mc */ {
                                unsigned short maincode;
                                struct {
                                unsigned char maincode2;
                                unsigned char maincode1;
                                } main_returncode;
                        } mc;
                } structured_rc;
                unsigned long rc_nbr;   /* general return code:       */
        } rc;
};

Symbolic names and constants are available for the evaluation of the return codes. These are defined in FHDR.H and SM2RC.H, and their use is explained below.

To check the return codes, the user must first query the “returncode.rc.structured_
rc.mc.maincode” structure element of the ESMFHDR structure. This structure element (referred to subsequently as MAINCODE) can be addressed by means of the symbolic name FHDR_RC_MAINCODE.

Examples

SM2GMS.hdr.FHDR_RC_SUBCODE1
SM2GDAT.hdr.FHDR_RC_SUBCODE1

When the macro is executed successfully, MAINCODE has the value
“FHDRsuccessful_processing”.

In the event of an error, MAINCODE and the “returncode.rc.structured_
rc.subcode.subcode1” structure element supply error information.
The “returncode.rc.structured_rc.subcode.subcode1” structure element (referred to subsequently as SUBCODE1) can be addressed by means of the symbolic name FHDR_RC_SUBCODE1.

Examples

SM2GMS.hdr.FHDR_RC_SUBCODE1
SM2GDAT.hdr.FHDR_RC_SUBCODE1

The following table explains the most important return codes:

SUBCODE1	MAINCODE	Meaning and action to be taken
0	0	The call was successful.
1	65535	The requested function is not supported (incorrect entry for UNIT or FUNCTION in the standard header). Unrecoverable error. Action: None
3	65535	The specified version of the interface is not supported (incorrect version entry in the standard header). Unrecoverable error. Action: None
4	65535	Parameter list is not aligned on a word boundary. Unrecoverable error. Action: None
65	65535	The SM2 subsystem does not exist. Action: The subsystem must be explicitly created.
128	65535	The SM2 subsystem is incapable of responding for a short period. Action: Wait for a short time and then repeat the call.
129	65535	The SM2 subsystem is incapable of responding for a longer period. Action: Wait for a sufficiently long time and then repeat the call.
1	1	Can only occur in the case of the SM2GDAT macro. The size specified in the “length_buffer” parameter is too small for the requested SM2 data buffers. In this case, the macro stores the actually required size in the “length_buffer” structure element of the structure of the type “SM2GDAT_get_data_mdl”, which was passed to the macro as a parameter in the call. Action: Supply the “length_buffer” parameter with the value of the “length_buffer” structure element, make an output area of this size available, and repeat the call.
1	2	Can only occur in the case of the SM2GDAT macro. The size specified in the “length_buffer” parameter is large enough for the requested data buffers, but SM2 cannot validate the output area; i.e. it recognizes that (calculated from the beginning of the output area) it cannot write to the area required for the requested data buffers. This error code does not cover the situation in which the caller specifies a large enough size in “length_buffer” but does not make enough space available for the output area. SM2 cannot determine whether the caller is overwriting his or her own data areas or program code. Action: Correct the program – always make available at least as most space as is specified in the “length_buffer” parameter.
64	3	Can only occur in the case of the SM2GDAT macro. SM2 has no new data. Action: Wait (e.g. 5 seconds) and then try again. If necessary, synchronize the call cycle with the SM2 cycle. The SM2GMS macro supplies the currently set SM2 monitoring cycle.
32	4	System error. Action: None
32	5	The SM2 monitoring task is not running. Action: None
64	6	Specified host unavailable.

The following symbolic constants are available in FHDR.H and SM2RC.H for the values for MAINCODE and SUBCODE1 listed in the table.

Symbolic constants for MAINCODE

#define FHDRsuccessful_processing	0
#define SM2RCbuffer_too_short	1
#define SM2RCbuffer_not_valid	2
#define SM2RCno_data	3
#define SM2RCsystem_error	4
#define SM2RCgatherer_down	5
#define SM2RChost_not_available	6
#define FHDRlinkage_error	65535

Symbolic constants for SUBCODE1

#define FHDRfct_not_supported	1
#define FHDRver_not_supported	3
#define FHDRalignment_error	4
#define FHDRss_not_created	65
#define FHDRwait_short_term	128
#define FHDRwait_long_term	129

The example in the following section provides a practical guide to evaluating return codes.

SM2RC.H is in the SYSLIB.SM2.<ver> library and can be printed out with the following command:

/PRINT-DOCUMENT 
   FROM-FILE=*LIBRARY-ELEMENT(
      LIBRARY=SYSLIB.SM2.<ver>,
      ELEMENT=SM2RC.H,TYPE=S)

FHDR.H is in the SYSLIB.BS2CP.<ver> library and can be printed out analogously.