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

INITIALIZE STRING (PHOP,WSOP,*,*)

Purpose

Use Initialize String 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 z coordinates of the echo volume remain unchanged. The graPHIGS API uses the string device's input character set to interpret the initial string.

For all prompt and echo types, the first entry of the string data record is the input buffer size, which is an integer in the range (1..n). The graPHIGS API compares this against the available input buffer size for the specified string device. If the requested buffer size is greater, then the graPHIGS API records the available size in the workstation state list instead of the specified input buffer size. If the initial string is longer than the buffer size, then the graPHIGS API issues an error.

When the graPHIGS API receives string input, it obtains a buffer of the size defined by the input buffer size. The graPHIGS API copies the initial string into the buffer, and places the cursor at the initial editing position within the buffer. Replacement of characters begins at this initial position.

This function supports the following prompt/echo types:

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

    Note:

    The string device must be in Request mode.

    Language Bindings

    • C

    pinit_string (ws_id, string_num, init_string, pet, echo_area, string_data)

    Input Parameters

    Pint ws_id
    Workstation identifier.

    Pint string_num
    String device number (>=1).

    const char *init_string
    Initial string.

    Pint pet
    Prompt and echo type.

    const Plimit *echo_area
    Echo area in DC.

    const Pstring_data *string_data
    Data record.

    FORTRAN

    PINST (wkid, stdnr, lstr, istr, pet, xmin, xmax, ymin, ymax, ldr, datrec)

    Input Parameters

    integer wkid
    Workstation identifier.

    integer stdnr
    String device number (>=1).

    integer lstr
    Length of the initial string (>=0). The number of characters actually used is the minimum of lstr and the length of istr.

    character*(*) istr
    Initial string.

    integer pet
    Prompt and echo type.

    real xmin
    Minimum x coordinate determining echo area in DC.

    real xmax
    Maximum x coordinate determining echo area in DC.

    real ymin
    Minimum y coordinate determining echo area in DC.

    real ymax
    Maximum y coordinate determining echo area in DC.

    integer ldr
    Dimension of the data record array.

    character*80 datrec(ldr)
    Data record.

    The pprec parameters used to build the string input data record are as follows: (IL=2, IA=input buffer size, initial editing position, RL=0, RA=(), SL=0, LSTR=(), STR=()).

    FORTRAN Subset

    PINST (wkid, stdnr, lstr, istr, pet, xmin, xmax, ymin, ymax, ldr, datrec)

    Input Parameters

    integer wkid
    Workstation identifier.

    integer stdnr
    String device number (>=1).

    integer lstr
    Length of the initial string.

    character*80 istr
    Initial string.

    integer pet
    Prompt and echo type.

    real xmin
    Minimum x coordinate determining echo area in DC.

    real xmax
    Maximum x coordinate determining echo area in DC.

    real ymin
    Minimum y coordinate determining echo area in DC.

    real ymax
    Maximum y coordinate determining echo area in DC.

    integer ldr
    Dimension of the data record array.

    character*80 datrec(ldr)
    Data record.

    The pprec parameters used to build the string input data record are as follows: (IL=2, IA=input buffer size, initial editing position, RL=0, RA=(), SL=0, LSTR=(), STR=()).

    Errors

    3
    Function Requires State (PHOP,WSOP,*,*)
    54
    Specified Workstation Is Not Open
    61
    Specified Workstation Is Not Of Category Input Or Outin
    250
    Specified Device Not Available On Workstation
    251
    Function Requires Input Device To Be In Request Mode
    254
    Invalid Echo Area/Volume: XMIN>=XMAX, YMIN>=YMAX OR ZMIN>ZMAX
    255
    Echo Area/Volume Boundary Point(s) Outside Device Range
    253
    Prompt/Echo Type Not Available On Specified Workstation
    260
    Input Device Data Record Field Is In Error
    261
    Initial Value Is Invalid
    263
    Length Of Initial String > Buffer Size

    Related Subroutines

  • Inquire String Device State

  • Inquire Default String Device Data

  • Inquire Display Space Size

  • Inquire Number Of Available Logical Input Devices

  • Pack Data Record

  • Set String Mode

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