3.3.1 Declarations

HLLAPI application programs should declare or use the following data types:

• Variables

• Constants

• Function constants

To have HLLAPI structures and function constants defined automatically, include the hapi_c.h header file in your source module(s), as follows:

     #include <hapi_c.h>

The four arguments passed on the call to HLLAPI are three integers (passed indirectly using pointers) and a character string. They should be declared in the following form:

     AP_INT32   api_func;
     char       api_string[DATA_SIZE];
     AP_INT32   api_len;
     AP_INT32   api_retc;

The argument names are arbitrary. The arguments may be global to your program or local to a function. The length of the character string for the second parameter, shown as DATA_SIZE in the above example, varies depending on the particular HLLAPI function being used; see Data String Size, and consult the function description to determine the appropriate value to use for the size.

The four arguments passed to HLLAPI can be given any names within the program, but they must be passed to HLLAPI in the correct order. The meaning of each argument varies according to the particular HLLAPI function being called; typical usage is given below.

Argument 1 (integer) is used for the function code of the HLLAPI function being called.

Argument 2 (character string) is a string of text or control information supplied to HLLAPI, or an empty string into which HLLAPI will return data.

Argument 3 (integer) is often used to specify the length of the string that is being supplied as Argument 2, but it can be used to supply or return other numeric values.

Argument 4 (integer) is often used to supply or return a presentation space position-the position on the 3270 display where data was found or where an action is to be performed. It is also used for return codes from HLLAPI indicating whether or not a HLLAPI function was called successfully, or to supply or return other numeric values.

3.3.2 Data String Size

The data string supplied as the second argument to a HLLAPI function can be any size; for HLLAPI functions that return data to the program, you should ensure that it is large enough to hold the maximum amount of data that may be returned. These functions are Copy Field to String, Copy Operator Information Area (OIA), Copy Presentation Space, Copy Presentation Space to String, Query Sessions, and Query System.

For example, Copy Presentation Space requires a data string at least as large as the presentation space to be copied. This depends on the screen model of the 3270 emulation session as shown in Presentation Space.

Presentation Space

3.3.3 Initializing Function Parameters

Before requesting a HLLAPI function, a program must initialize the variables used as function parameters with appropriate values.

All HLLAPI function calls require the first parameter to be set to a valid function code. Depending on the function code, none, some, or all of the three remaining parameters may need to be initialized. For more information, see HLLAPI Function Requests.

The following example code shows how an application program can load these values prior to requesting the HLLAPI Copy String to Presentation Space function:

     api_func = HA_COPY_STR_TO_PS;
     api_str = "listfiles * exec";
     api_len = strlen(api_str);
     api_retc = 1761;

This example performs the following:

1. Sets the function code for Copy String to Presentation Space using the symbol defined in the hapi_c.h file.

2. Sets up the string to be copied-listfiles * exec.

3. Sets the length parameter to the length of the string.

4. Sets the fourth parameter to 1761. The Copy String to Presentation Space function's description states that this is the position in the presentation space where you want the function to place the copied data.

In this example initializing the length, api_len, is required only if the session parameter STRLEN (the default) is enabled. (For more information, see HLLAPI Function Requests.)

3.3.4 Requesting a Function

Once you have initialized the function parameters, the program is ready to transfer control to the HLLAPI library.

The HLLAPI function call is defined in the HLLAPI header file hapi_c.h. The following code demonstrates the function call to HLLAPI:

     hllapi (&api_func, send_string, &api_len, &api_retc);

SNAP-IX provides three different function names that can be used to call HLLAPI; this is to retain compatibility with other HLLAPI implementations that use these names. You are advised to use the function call hllapi in new applications; the other two names, hllc and clim, are provided for compatibility with applications originally written for older IBM DOS HLLAPI implementations. In the function call shown above, hllapi can be replaced by hllc or clim using the same syntax.

The four arguments are passed to HLLAPI by address.

The return code should then be checked to determine if the function was performed successfully. The following sample code shows how an application might handle the return code after calling HLLAPI with the function code set to 15 (the Copy String to Presentation Space function code.) When designing return code handling for a function, refer to its description to determine which return code values need to be handled.

switch(api_retc)
{
   case HARC_SUCCESS:
   case HARC_TRUNCATION:
       break;                          /* Some or all data was copied      */

   case HARC_NO_CONNECTION:
       connect_error();                /* Not connected                    */
       break;

   case HARC_INVALID_PS_POS:           /* PS position not valid            */
   case HARC_BAD_PARM:                 /* String length bad                */
       parameter_error (api_retc);
       break;

   case HARC_LOCKED:                   /* PS inhibited or bad data values  */
       state_or_data error (api_str);
       break;

    case HARC_SYSTEM_ERROR:            /* System error                      */
       do_query_system();              /* Call Query System function        */
                                       /* and display returned data         */
       terminate():                    /* Cleanup and terminate application */
       break:

     default:                          /* Unknown error                     */
       display_error (api_retc)
       terminate ();                   /* Cleanup and terminate application */
       break;
}

In this example, the functions within the switch statement's body are functions that an application could have defined to handle various conditions. Their form and content are entirely dependent on the application's design and implementation.

3.3.5 Accessing Values from Returned Data Strings

Several HLLAPI functions (for example Query Sessions) return formatted data strings that contain logical and numeric values as well as characters. When accessing data from these strings, you should be aware of the following:

     ps_size = ((unsigned char) mystring[4] * 256) + (unsigned char) mystring[3];