Declaring variables

GDDM V3R2 Base Application Programming Reference

Declaring variables

GDDM V3R2 Base Application Programming Reference
SC33-0868-02

This section describes how to declare variables to match the function declarations used in the header files.

Parameters as described for each function should be declared as follows:

Fullword integer

Int

Halfword integer

Short

Floating point

Float

Character

Array of type char

Array of n-byte

character tokens Two-dimensional array of type char

Arrays

Use a one-dimensional of the type specified.

Structures

Use appropriate storage mapping.

For example:

Fullword integers, halfword integers, and floating point values

Specified by user:


       int n=2;
       gscol(n);

Returned by GDDM:


       int n;
       gscol(&n);


       int *n;
       gscol(n);

Note: To receive values returned by GDDM, the parameter should be an address. To ensure this, either use the address(&) operator, or declare the variable to be used as a pointer(*).

Array of fullword integers:


       int array[10];
       apqids(1,10,array);

Note: Because array is a pointer to the first element in the array of fullword integers, it can be used in the same way for parameters specified by the user and returned by GDDM.

Character: Parameters described as being of type 'character' should be declared as char xxx[n], where xxx is the name of the variable, and n is the number of characters it is to contain. For example:


           char string[7];
           strncpy(string,"EXAMPLE",7);
           gschar(10.0,10.0,7,string);

The strncpy function is used to avoid adding the NULL character to the variable string. C uses the NULL character to delimit strings.

Parameters described as 'an array of n byte character tokens' should be declared as char xxx[a][n], where xxx is the variable name, n is the number of bytes in each character token, and a is the number of such tokens required. For example:


          char nlist[2][8];
          strncpy(nlist[0],"*       ",8);
          strncpy(nlist[1],"ADMPLOT ",8);

This example initializes a variable nlist. This could be used for the name list parameter on a dsopen call, to open a directly attached plotter. The source strings are padded to 8 characters with blanks. This is to avoid the NULL character being placed anywhere in the target string. Because all the character variables are arrays, they are passed in the same way, whether they are values specified by the user or returned by GDDM.

Structures: Some parameters to GDDM calls can use structures to split information into separate fields. The application anchor block parameter, which is used on all reentrant calls, is an example of this. It can be declared as a structure of the following form:


            struct {
                    int feedback;
                    int *anchor;
                   } aab;

The header file ADMTSTRC.H is provided with sample type definitions for structures used in GDDM calls. These types are as follows:

Admaab (Application anchor block)

The first parameter passed to all REENTRANT application calls.

Admccs (Chart control structure)

Used for the chart_control parameter in the CHART call.

Admers (Error record structure)

The structure returned by GDDM from the FSQERR call. It is also passed to any user-specified error exit defined by the FSEXIT call.

Admspib (Spib block)

The structure used in the SPINIT call, to initialize the System Programmer's Application Call Interface.

You can declare a variable to be any of these types. The variable can then be passed directly to the functions using it, by first 'casting' the type to be that expected by the call. Alternatively, a union operator can be used to map the structure to the same area of memory as a variable of the type expected by the function. The following examples show both ways of using the structures.

In the following example, the variable error is cast to be of the type expected by the function. The address operator (&) is used because the parameter (error) is being returned by GDDM.


       Admers error;

       fsqerr(160,(char *)&error);

In the following example, the function is passed a variable of the type it expects. Use of the union operator has ensured that the structure begins at the same place in memory as the variable. Because of this, the elements in the structure will be set on return from the fsqerr call.


       union {
              Admers error;
              char str[160];
             } u;

       fsqerr(160,u.str);

The address of the error record structure is also passed by GDDM to an error exit specified by means of the fsexit function. The sample Admers type can also be used to declare the parameters to the error exit function. The following example shows a possible declaration for such a function:


      void err_exit(Admers *ers);

Casting must be used to specify this function in the fsexit function. For example:


      fsexit((int)&err_exit,8);

Notices | Terms of use | Support | Contact z/OS