See Code disclaimer information for information pertaining to code examples.
Receiver variables are generally used by retrieve APIs to return information to a caller. This section provides coding examples of repeating entry types and of the use of offsets to go from one entry to the next in the receiver variable.
See Receiver variables for more information.
For the examples, see the following:
In the following example, the EXTI0100 format is defined in the qusreg.h header file, which is included by the qusrgfa2.h header file in the QSYSINC library.
This format is of the repeating entry type with all fixed-length fields. The repeating portion of the format (Qus_EXTI0100_Entry_t) is repeated after the fixed portion. The fixed portion of the format (Qus_EXTI0100_t) is returned only once. To go from one entry to the next, you add the offset exit point entry field to the starting position of the receiver variable to get to the first entry. Add the length exit point entry field to the current position in the receiver variable to move to the subsequent entries.
typedef _Packed struct Qus_EXTI0100_Entry {
char Exit_Point_Name[20];
char Format_Name[8];
int Max_Exit_Programs;
int Number_Exit_Programs;
char Allow_Deregistration;
char Allow_Change_Control;
char Registered_Exit_Point;
char Prep_Name_Add_Pgm[10];
char Prep_Lib_Add_Pgm[10];
char Prep_Format_Add[8];
char Prep_Name_Rmv_Pgm[10];
char Prep_Lib_Rmv_Pgm[10];
char Prep_Format_Rmv[8];
char Prep_Name_Rtv_Info[10];
char Prep_Lib_Rtv_Info[10];
char Prep_Format_Rtv[8];
char Desc_Indicator;
char Desc_Msg_File[10];
char Desc_Msg_Library[10];
char Desc_Msg_Id[7];
char Text_Description[50];
/*char Reserved[];*/
} Qus_EXTI0100_Entry_t;
typedef _Packed struct Qus_EXTI0100 {
int Bytes_Returned;
int Bytes_Available;
char Continue_Handle[16];
int Offset_Exit_Point_Entry;
int Number_Points_Returned;
int Length_Exit_Point_Entry;
/*char Reserved[];*/
/*Qus_EXTI0100_Entry_t Array[];*/
} Qus_EXTI0100_t;
In this example, the EXTI0200 format is defined in the qusreg.h header file, which is included by the qusrgfa2.h header file in the QSYSINC library.
This format is of the repeating entry type with some variable-length fields. The repeating portion of the format (Qus_EXTI0200_Entry_t) is repeated for each entry returned, and the fixed portion of the format (Qus_EXTI0200_t) is returned only once. To go from one entry to the next, you add the offset program entry field to the starting position of the receiver variable to get to the first entry. Then add the offset next entry field to the starting position of the receiver variable to get to each subsequent entry. To get to the Prog_Data field, add the offset exit data field to the starting position of the receiver variable and use the length exit data field to determine the number of bytes of information in the Prog_Data field.
typedef _Packed struct Qus_EXTI0200_Entry {
int Offset_Next_Entry;
char Exit_Point_Name[20];
char Format_Name[8];
char Registered_Exit_Pt;
char Complete_Entry;
char Reserved[2];
int Program_Number;
char Program_Name[10];
char Program_Library[10];
int Data_Ccsid;
int Offset_Exit_Data;
int Length_Exit_Data;
/*char Reserved[];*/
/*Qus_Program_Data_t Prog_Data;*/
} Qus_EXTI0200_Entry_t;
typedef _Packed struct Qus_EXTI0200 {
int Bytes_Returned;
int Bytes_Available;
char Continue_Handle[16];
int Offset_Program_Entry;
int Number_Programs_Returned;
int Length_Program_Entry;
/*char Reserved[];*/
/*Qus_EXTI0200_Entry_t Array[];*/
} Qus_EXTI0200_t;
The following portion of code illustrates the use of the offsets to go from one entry to the next in the receiver variable:
/******************************************************************/
/* Save the number of exit programs returned, and set the pointer */
/* to point to the first exit program entry. */
/******************************************************************/
rcv_ptr=rcv_var;
num_exit_pgms=((Qus_EXTI0200_t *)rcv_ptr)>Number_Programs_Returned;
rcv_ptr += ((Qus_EXTI0200_t *)rcv_ptr)>Offset_Program_Entry;
rsl_ok=1;
for (i=0; i<num_exit_pgms; i++)
{
memcpy(exit_pgm_name,
((Qus_EXTI0200_Entry_t *)rcv_ptr)>Program_Name,10);
memcpy(exit_pgm_lib,
((Qus_EXTI0200_Entry_t *)rcv_ptr)>Program_Library,10);
/****************************************************************/
/* Resolve to the exit program. If an error occurs on the */
/* resolve operation to the library, the rsl_ok indicator is */
/* set to failed in the RSL_PGM_HDLR exception handler. */
/* The RSLVSP MI instruction signals all errors to this */
/* program; therefore, enable the exception handler to */
/* capture any errors that may occur. */
/****************************************************************/
#pragma exception_handler (RSLVSP_PGM_HDLR,rsl_ok,0,_C2_MH_ESCAPE)
exit_pgm_ptr=((Pgm_OS *)rslvsp(_Program,
exit_pgm_name,
exit_pgm_lib,
_AUTH_POINTER));
#pragma disable_handler
/****************************************************************/
/* If the resolve is successful, call the exit program. */
/* If not, move on to the next exit program. */
/****************************************************************/
if (rsl_ok)
{
exit_pgm_ptr(info_for_exit_pgm);
}
/****************************************************************/
/* Set the receiver variable to point to the next exit program */
/* that is returned. */
/****************************************************************/
rsl_ok=1;
rcv_ptr=rcv_var +
((Qus_EXTI0200_Entry_t *)rcv_ptr)>Offset_Next_Entry;
}
