[ Previous | Next | Contents | Glossary | Home | Search ]
The graPHIGS Programming Interface : Subroutine Reference

GPINST - Initialize String

GPINST (wsid, device, length, string, echo, area, buflen, cursor, datalen, data)

Purpose

Use GPINST to initialize the specified string input device.

The Initialize String subroutine stores the initial string, prompt/echo type, echo area, and string data record in the workstation state list for the specified device. The string device's input character set is used to interpret the initial string and prompt strings.

The input string returned is the size of the string input buffer (buflen) However, if your application specifies a prompt/echo type 2 (echo) and the buflen size plus the prompt are greater than the device's maximum buffer size, then the input string returned will be the device's maximum buffer size minus the prompt string.

Note:

The string device must be in Request mode.

Parameters

wsid -- specified by user, fullword integer

Workstation identifier of the device to be initialized.

device -- specified by user, fullword integer

String device number (>=1)

length -- specified by user, fullword integer

Length of initial string, in bytes (>=0)

string -- specified by user, variable length character string

Initial string.

echo -- specified by user, fullword integer

Prompt/echo type to be initialized (>=1)

area -- specified by user, 6 short floating-point numbers (DC)

Echo area (Xmin, Xmax, Ymin, Ymax, Zmin, Zmax)

buflen -- specified by user, fullword integer

String input buffer size, in bytes (>=0)

cursor -- specified by user, fullword integer

Initial cursor position in the string buffer relative to the position of the initial string (>=1) If a prompt string is used (echo type=2), the initial string is placed in the string buffer immediately after the prompt string. Otherwise, the initial string is placed at position one in the string buffer.

If the string input buffer size parameter is zero, the initial cursor position parameter is not checked, and the graPHIGS API uses the value of zero for the initial position.

datalen -- specified by user, fullword integer

Data record length, in bytes (>=0)

Note:

The data record length parameter must equal zero (datalen=0) if no data record is required for the given prompt/echo type. For prompt/echo types which require a data record, the specified data record length must be greater than or equal to 12.

data -- specified by user, variable data

String data record.

For all prompt/echo types the input buffer size is compared to maximum input buffer size for string devices in the WDT. If the requested buffer size is greater, the maximum input buffer size for string devices is substituted in the stored record. If the initial string is longer than the buffer size, an error is issued.

Prompt/echo Types

Type One

displays the current string value within the echo area using a workstation-dependent technique.

Type Two

displays an application-specified prompt string which precedes the initial string. This prompt string is passed in by way of the data record and is placed in the string device input buffer. It is not returned to the user. The prompt may not be typed over and is not returned with the string device input. The initial cursor position is specified relative to the initial string position in the string buffer.

String echo Type Two requires the following data record:

                      ----------------------------
                   0  |            0             | Number of integers
                      |--------------------------|
                   4  |            0             | Number of reals
                      |--------------------------|
                   8  |            1             | Number of strings
     Character        |--------------------------|
     string 12 -----> |      prompt string       |
                      ----------------------------

The prompt string includes the length of the string in the first byte of the input. This length (in bytes) is inclusive of the length field. Therefore, a length of one specifies a null prompt string.

Error Codes

25
SPECIFIED WORKSTATION DOES NOT EXIST
140
DEVICE NUMBER < ONE OR DEVICE NOT AVAILABLE
141
INPUT DEVICE NOT IN CORRECT MODE
144
PROMPT/ECHO TYPE NOT AVAILABLE ON WORKSTATION
145
ECHO AREA BOUNDARY VALUE IN ERROR
146
FIELD IN INPUT DEVICE DATA RECORD IN ERROR
324
PROMPT/ECHO TYPE < ONE
501
DATA RECORD WAS NOT SPECIFIED BUT IS REQUIRED
502
FIELD IN DATA RECORD NOT SUPPORTED ON WORKSTATION
506
NUMBER OF INITIAL VALUES < ZERO
509
DATA LENGTH VALUE < ZERO OR REQUIRED LENGTH
513
NUMBER OF INITIAL VALUES EXCEEDS DEVICE MAXIMUM
577
BUFFER LENGTH IS < ZERO
578
BUFFER LENGTH EXCEEDS DEVICE MAXIMUM
579
INITIAL POSITION IS < ONE OR > NUMBER OF INITIAL VALUES PLUS ONE
580
INITIAL POSITION EXCEEDS BUFFER SIZE

Related Subroutines

GPQDS
Inquire Maximum Display Surface Size
GPQDST
Inquire Default String Device Data
GPQLI
Inquire List of Logical Input Devices
GPQST
Inquire String Device State
GPSTMO
Set String Mode

RCP code

201335302 (X'0C002206')

[ Previous | Next | Contents | Glossary | Home | Search ]