GINSTS

GDDM-GKS V1R1 Programming Guide and Reference

GINSTS

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

Purpose


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

APL code	1498
GKS RCP code	X'38004A00' (939543040)

Function: To initialize string.

Input function. Initializes a string input device at a workstation. If your program is written in FORTRAN IV or VS FORTRAN, use the function Initialize string (FORTRAN only) (GINST) 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.

istr (specified by user) (character)
The initial string to be displayed.

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 (GRQSTS), 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. 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 the function Inquire display space size (GQDSP).


            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 GINSTS (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