GINST

GDDM-GKS V1R1 Programming Guide and Reference

GINST

GDDM-GKS V1R1 Programming Guide and Reference
SC33-0334-00

Purpose


GINST	(wkid,stdnr,lstr,istr,pet,xmin, xmax,ymin,ymax,buflen, inipos,ldr,datrec)

Function: Input function. Initializes a string input device at a workstation. Use this call only if your program is written in FORTRAN IV or VS FORTRAN. Otherwise, use the function Initialize string (GINSTS) instead.

Parameters

wkid (specified by user) (fullword integer)
The workstation identifier.

stdnr (specified by user) (fullword integer)
The string device number. GDDM-GKS provides only one string device at a workstation. The string device number is always 1.

lstr (specified by user) (fullword integer)
The length of the initial string. This must be less than or equal to the length of the string input buffer buflen. The actual value used is the lesser of lstr and the length of the initial string istr.

istr (specified by user) (character)
The initial string to be displayed. In a VS FORTRAN program, the string can be of variable length. For FORTRAN IV, you must define the string as CHARACTER*80.

pet (specified by user) (fullword integer)
The prompt and echo type. GDDM-GKS provides only one prompt and echo type; this parameter should always equal 1.

xmin (specified by user) (short floating point)

xmax (specified by user) (short floating point)

ymin (specified by user) (short floating point)

ymax (specified by user) (short floating point)
Echo area in device coordinates.

buflen (specified by user) (fullword integer)
The length of the string input buffer.

inipos (specified by user) (fullword integer)
Initial cursor position. It may range from 1 to the length of the initial string plus 1.

ldr (specified by user) (fullword integer)
Dimension of the data record array datrec.

datrec (specified by user) (array of 80-byte character tokens)
The data record.

Operating states

WSOP, WSAC, SGOP

Related functions

Request string (FORTRAN only) (GRQST), Set string mode (GSSTM)

Description

This function initializes the string device by defining the initial string, prompt and echo type, and echo area.

The function copies the initial string into the input buffer and places the cursor at the initial cursor position. Replacement of characters begins at this point.

The input buffer size is compared with the "maximum input buffer size" for the device, which is contained in the workstation description table. If the requested buffer size is greater than the maximum, the maximum buffer size is substituted. If you define an initial string longer than the buffer size, error 154 is reported. GKS defines the initial cursor position parameter, inipos, as a (mandatory) part of the data record for the string device. If inipos is invalid, error 152 is reported.

GDDM-GKS provides one prompt and echo type:

pet=1

Echo string within echo area. The string is echoed starting at the lower left corner of the echo area. No clipping to the echo area limits is performed. The data record is not used.

For example, you can use a string input device to obtain a rotation angle for a segment transformation. The initial string is "angle=," which is six characters long. The initial cursor position is set to character "7" so that the initial string is not overwritten. The echo area is defined using the maximum X and Y values for DC as returned by Inquire Maximum Display Surface Size.


      stdnr=1
      lstr=6
      istr='angle='
      pet=1
      xmin = 0.0
      xmax = xdc
      ymin = ydc/10.0
      ymax = ydc
      buflen = 30
      inipos = 7
      ldr=0
      CALL GINST (wkid, stdnr, lstr, istr, pet,
     *xmin, xmax, ymin, ymax, buflen, inipos,
     *ldr, datrec)

This illustration shows the input buffer containing the initial string, and indicates the location of the initial cursor position.

Principal errors


        7  GKS not in proper state: GKS shall be in one of the states
           WSOP, WSAC, or SGOP
       20  Specified workstation identifier is invalid
       25  Specified workstation is not open
       38  Specified workstation is neither of category INPUT nor of
           category OUTIN
       51  Rectangle definition is invalid
      140  Specified input device is not present on workstation
      141  Input device is not in REQUEST mode
      144  Specified prompt and echo type is not supported on this
           workstation
      145  Echo area is outside display space
      146  Contents of input data record are invalid
      152  Initial value is invalid
      154  Length of the initial string is greater than the buffer size

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